Podręcznik PHP
Copyright
Prawa autorskie do tego podręcznika © 1997 - 2012 należą do PHP Documentation Group. Materiał ten może być rozprowadzany tylko pod warunkami określonymi w Creative Commons Attribution 3.0 lub nowszych. Kopia Creative Commons Attribution 3.0 license jest dystrybuowana z tym podręcznikiem. Najnowsza wersja jest aktualnie dostępna pod adresem » http://creativecommons.org/licenses/by/3.0/.
W przypadku zainteresowania redystrybucją lub publikowaniem tego dokumentu w całości lub jego części, zmodyfikowanego lub niezmodyfikowanego, wszystkie pytania należy zadawać właścicielom praw autorskich do niego pod adresem » doc-license@lists.php.net. Adres ten jest podłączony do publicznie archiwizowanej listy dyskusyjnej.
Podręcznik PHP
Przedmowa
PHP, co jest skrótem od "PHP: Hypertext Preprocessor", jest powszechnie używanym językiem skryptowym ogólnego przeznaczenia, który jest szczególnie przystosowany do tworzenia aplikacji internetowych, także poprzez zagnieżdżenie wewnątrz języka HTML. Składnia, wywodząca się z języków C, Java i Perl, jest łatwa do nauczenia się. Głównym celem języka jest umożliwienie programistom szybkiego tworzenia stron internetowych, ale PHP umożliwia znacznie więcej.
Podręcznik ten składa się głównie z opisu funkcji, ale zawiera także opis języka, objaśnienie niektórych z głównych cech PHP, jak również kilka dodatkowych informacji.
Podręcznik można pobrać w kilku formatach spod adresu » http://www.php.net/download-docs.php. Więcej informacji na temat prac nad tym podręcznikiem można znaleźć w rozdziale 'O podręczniku'. Osobom zainteresowanym historią PHP polecamy odpowiedni dodatek.
Autorzy i współpracownicy
Wyróżniamy najbardziej aktywnych twórców na pierwszej stronie podręcznika, ale jest wielu innych współpracowników, którzy pomagają w pracach, lub włożyli w przeszłości wiele pracy przy tym projekcie. Jest wiele niewymienionych tutaj ludzi, którzy wnieśli wkład w rozwój tego podręcznika licznymi komentarzami. Cały czas te uwagi są one uwzględniane w odnośnikach, i za nie serdecznie dziękujemy. Wszystkie poniższe listy uporządkowane są w kolejności alfabetycznej.
Autorzy i edytorzy
Poniżsi współpracownicy powinni zostać wyróżnieni za wpływ jaki mieli (lub ciągle mają) w rozwój podręcznika: Bill Abt, Jouni Ahto, Alexander Aulbach, Daniel Beckham, Stig Bakken, Nilgün Belma Bugüner, Jesus M. Castagnetto, Ron Chmara, Sean Coates, John Coggeshall, Simone Cortesi, Peter Cowburn, Daniel Egeberg, Markus Fischer, Wez Furlong, Sara Golemon, Rui Hirokawa, Brad House, Pierre-Alain Joye, Etienne Kneuss, Moriyoshi Koizumi, Rasmus Lerdorf, Andrew Lindeman, Stanislav Malyshev, Justin Martin, Rafael Martinez, Rick McGuire, Moacir de Oliveira Miranda Júnior, Kalle Sommer Nielsen, Yasuo Ohgaki, Richard Quadling, Derick Rethans, Rob Richards, Sander Roobol, Egon Schmid, Thomas Schoefbeck, Sascha Schumann, Dan Scott, Masahiro Takagi, Yannick Torres, Michael Wallner, Lars Torben Wilson, Jim Winstead, Jeroen van Wolffelaar i Andrei Zmievski.
Poniżsi współpracownicy włożyli wiele pracy przy edycji podręcznika: Stig Bakken, Gabor Hojtsy, Hartmut Holzgraefe i Egon Schmid.
Opiekunowie notatek
Aktualnie najbardziej aktywni opiekunowie to: Daniel Brown, Nuno Lopes, Felipe Pena, Thiago Pojda i Maciek Sokolewicz.
Te osoby także pracowały nad zarządzaniem notatkami: Mehdi Achour, Daniel Beckham, Friedhelm Betz, Victor Boivie, Jesus M. Castagnetto, Nicolas Chaillan, Ron Chmara, Sean Coates, James Cox, Vincent Gevers, Sara Golemon, Zak Greant, Szabolcs Heilig, Oliver Hinckel, Hartmut Holzgraefe, Etienne Kneuss, Rasmus Lerdorf, Matthew Li, Andrew Lindeman, Aidan Lister, Hannes Magnusson, Maxim Maletsky, Bobby Matthis, James Moore, Philip Olson, Sebastian Picklum, Derick Rethans, Sander Roobol, Damien Seguy, Jason Sheets, Tom Sommer, Jani Taskinen, Yasuo Ohgaki, Jakub Vrana, Lars Torben Wilson, Jim Winstead, Jared Wyles i Jeroen van Wolffelaar.
Na początek
What is PHP?
PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML.
Nice, but what does that mean? An example:
Przykład #1 An introductory example
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Example</title>
</head>
<body>
<?php
echo "Hi, I'm a PHP script!";
?>
</body>
</html>
Instead of lots of commands to output HTML (as seen in C or Perl),
PHP pages contain HTML with embedded code that does
"something" (in this case, output "Hi, I'm a PHP script!").
The PHP code is enclosed in special start and end processing
instructions <?php and ?>
that allow you to jump into and out of "PHP mode."
What distinguishes PHP from something like client-side JavaScript is that the code is executed on the server, generating HTML which is then sent to the client. The client would receive the results of running that script, but would not know what the underlying code was. You can even configure your web server to process all your HTML files with PHP, and then there's really no way that users can tell what you have up your sleeve.
The best things in using PHP are that it is extremely simple for a newcomer, but offers many advanced features for a professional programmer. Don't be afraid reading the long list of PHP's features. You can jump in, in a short time, and start writing simple scripts in a few hours.
Although PHP's development is focused on server-side scripting, you can do much more with it. Read on, and see more in the What can PHP do? section, or go right to the introductory tutorial if you are only interested in web programming.
What can PHP do?
Anything. PHP is mainly focused on server-side scripting, so you can do anything any other CGI program can do, such as collect form data, generate dynamic page content, or send and receive cookies. But PHP can do much more.
There are three main areas where PHP scripts are used.
- Server-side scripting. This is the most traditional and main target field for PHP. You need three things to make this work. The PHP parser (CGI or server module), a web server and a web browser. You need to run the web server, with a connected PHP installation. You can access the PHP program output with a web browser, viewing the PHP page through the server. All these can run on your home machine if you are just experimenting with PHP programming. See the installation instructions section for more information.
- Command line scripting. You can make a PHP script to run it without any server or browser. You only need the PHP parser to use it this way. This type of usage is ideal for scripts regularly executed using cron (on *nix or Linux) or Task Scheduler (on Windows). These scripts can also be used for simple text processing tasks. See the section about Command line usage of PHP for more information.
- Writing desktop applications. PHP is probably not the very best language to create a desktop application with a graphical user interface, but if you know PHP very well, and would like to use some advanced PHP features in your client-side applications you can also use PHP-GTK to write such programs. You also have the ability to write cross-platform applications this way. PHP-GTK is an extension to PHP, not available in the main distribution. If you are interested in PHP-GTK, visit » its own website.
PHP can be used on all major operating systems, including Linux, many Unix variants (including HP-UX, Solaris and OpenBSD), Microsoft Windows, Mac OS X, RISC OS, and probably others. PHP has also support for most of the web servers today. This includes Apache, IIS, and many others. And this includes any web server that can utilize the FastCGI PHP binary, like lighttpd and nginx. PHP works as either a module, or as a CGI processor.
So with PHP, you have the freedom of choosing an operating system and a web server. Furthermore, you also have the choice of using procedural programming or object oriented programming (OOP), or a mixture of them both.
With PHP you are not limited to output HTML. PHP's abilities includes outputting images, PDF files and even Flash movies (using libswf and Ming) generated on the fly. You can also output easily any text, such as XHTML and any other XML file. PHP can autogenerate these files, and save them in the file system, instead of printing it out, forming a server-side cache for your dynamic content.
One of the strongest and most significant features in PHP is its support for a wide range of databases. Writing a database-enabled web page is incredibly simple using one of the database specific extensions (e.g., for mysql), or using an abstraction layer like PDO, or connect to any database supporting the Open Database Connection standard via the ODBC extension. Other databases may utilize cURL or sockets, like CouchDB.
PHP also has support for talking to other services using protocols such as LDAP, IMAP, SNMP, NNTP, POP3, HTTP, COM (on Windows) and countless others. You can also open raw network sockets and interact using any other protocol. PHP has support for the WDDX complex data exchange between virtually all Web programming languages. Talking about interconnection, PHP has support for instantiation of Java objects and using them transparently as PHP objects.
PHP has useful text processing features, which includes the Perl compatible regular expressions (PCRE), and many extensions and tools to parse and access XML documents. PHP standardizes all of the XML extensions on the solid base of libxml2, and extends the feature set adding SimpleXML, XMLReader and XMLWriter support.
And many other interesting extensions exist, which are categorized both alphabetically and by category. And there are additional PECL extensions that may or may not be documented within the PHP manual itself, like » XDebug.
As you can see this page is not enough to list all the features and benefits PHP can offer. Read on in the sections about installing PHP, and see the function reference part for explanation of the extensions mentioned here.
A simple tutorial
Spis treści
Here we would like to show the very basics of PHP in a short, simple tutorial. This text only deals with dynamic web page creation with PHP, though PHP is not only capable of creating web pages. See the section titled What can PHP do for more information.
PHP-enabled web pages are treated just like regular HTML pages and you can create and edit them the same way you normally create regular HTML pages.
What do I need?
In this tutorial we assume that your server has activated support for PHP and that all files ending in .php are handled by PHP. On most servers, this is the default extension for PHP files, but ask your server administrator to be sure. If your server supports PHP, then you do not need to do anything. Just create your .php files, put them in your web directory and the server will automatically parse them for you. There is no need to compile anything nor do you need to install any extra tools. Think of these PHP-enabled files as simple HTML files with a whole new family of magical tags that let you do all sorts of things. Most web hosts offer PHP support, but if your host does not, consider reading the » PHP Links section for resources on finding PHP enabled web hosts.
Let us say you want to save precious bandwidth and develop locally. In this case, you will want to install a web server, such as » Apache, and of course » PHP. You will most likely want to install a database as well, such as » MySQL.
You can either install these individually or choose a simpler way. Our manual has installation instructions for PHP (assuming you already have some web server set up). If you have problems with installing PHP yourself, we would suggest you ask your questions on our » installation mailing list. If you choose to go on the simpler route, then » locate a pre-configured package for your operating system, which automatically installs all of these with just a few mouse clicks. It is easy to setup a web server with PHP support on any operating system, including MacOSX, Linux and Windows. On Linux, you may find » rpmfind and » PBone helpful for locating RPMs. You may also want to visit » apt-get to find packages for Debian.
Your first PHP-enabled page
Create a file named hello.php and put it in your web server's root directory (DOCUMENT_ROOT) with the following content:
Przykład #1 Our first PHP script: hello.php
<html>
<head>
<title>PHP Test</title>
</head>
<body>
<?php echo '<p>Hello World</p>'; ?>
</body>
</html>
Use your browser to access the file with your web server's URL, ending with the /hello.php file reference. When developing locally this URL will be something like http://localhost/hello.php or http://127.0.0.1/hello.php but this depends on the web server's configuration. If everything is configured correctly, this file will be parsed by PHP and the following output will be sent to your browser:
<html> <head> <title>PHP Test</title> </head> <body> <p>Hello World</p> </body> </html>
This program is extremely simple and you really did not need to use PHP to create a page like this. All it does is display: Hello World using the PHP echo() statement. Note that the file does not need to be executable or special in any way. The server finds out that this file needs to be interpreted by PHP because you used the ".php" extension, which the server is configured to pass on to PHP. Think of this as a normal HTML file which happens to have a set of special tags available to you that do a lot of interesting things.
If you tried this example and it did not output anything, it prompted for download, or you see the whole file as text, chances are that the server you are on does not have PHP enabled, or is not configured properly. Ask your administrator to enable it for you using the Installation chapter of the manual. If you are developing locally, also read the installation chapter to make sure everything is configured properly. Make sure that you access the file via http with the server providing you the output. If you just call up the file from your file system, then it will not be parsed by PHP. If the problems persist anyway, do not hesitate to use one of the many » PHP support options.
The point of the example is to show the special PHP tag format. In this example we used <?php to indicate the start of a PHP tag. Then we put the PHP statement and left PHP mode by adding the closing tag, ?>. You may jump in and out of PHP mode in an HTML file like this anywhere you want. For more details, read the manual section on the basic PHP syntax.
Informacja: A Note on Line Feeds
Line feeds have little meaning in HTML, however it is still a good idea to make your HTML look nice and clean by putting line feeds in. A linefeed that follows immediately after a closing ?> will be removed by PHP. This can be extremely useful when you are putting in many blocks of PHP or include files containing PHP that aren't supposed to output anything. At the same time it can be a bit confusing. You can put a space after the closing ?> to force a space and a line feed to be output, or you can put an explicit line feed in the last echo/print from within your PHP block.
Informacja: A Note on Text Editors
There are many text editors and Integrated Development Environments (IDEs) that you can use to create, edit and manage PHP files. A partial list of these tools is maintained at » PHP Editors List. If you wish to recommend an editor, please visit the above page and ask the page maintainer to add the editor to the list. Having an editor with syntax highlighting can be helpful.
Informacja: A Note on Word Processors
Word processors such as StarOffice Writer, Microsoft Word and Abiword are not optimal for editing PHP files. If you wish to use one for this test script, you must ensure that you save the file as plain text or PHP will not be able to read and execute the script.
Informacja: A Note on Windows Notepad
If you are writing your PHP scripts using Windows Notepad, you will need to ensure that your files are saved with the .php extension. (Notepad adds a .txt extension to files automatically unless you take one of the following steps to prevent it.) When you save the file and are prompted to provide a name for the file, place the filename in quotes (i.e. "hello.php"). Alternatively, you can click on the 'Text Documents' drop-down menu in the 'Save' dialog box and change the setting to "All Files". You can then enter your filename without quotes.
Now that you have successfully created a working PHP script, it is time to create the most famous PHP script! Make a call to the phpinfo() function and you will see a lot of useful information about your system and setup such as available predefined variables, loaded PHP modules, and configuration settings. Take some time and review this important information.
Przykład #2 Get system information from PHP
<?php phpinfo(); ?>
Something Useful
Let us do something more useful now. We are going to check what sort of browser the visitor is using. For that, we check the user agent string the browser sends as part of the HTTP request. This information is stored in a variable. Variables always start with a dollar-sign in PHP. The variable we are interested in right now is $_SERVER['HTTP_USER_AGENT'].
Informacja:
$_SERVER is a special reserved PHP variable that contains all web server information. It is known as a superglobal. See the related manual page on superglobals for more information. These special variables were introduced in PHP » 4.1.0. Before this time, we used the older $HTTP_*_VARS arrays instead, such as $HTTP_SERVER_VARS. Although deprecated, these older variables still exist. (See also the note on old code.)
To display this variable, you can simply do:
Przykład #1 Printing a variable (Array element)
<?php
echo $_SERVER['HTTP_USER_AGENT'];
?>
A sample output of this script may be:
Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)
There are many types of variables available in PHP. In the above example we printed an Array element. Arrays can be very useful.
$_SERVER is just one variable that PHP automatically makes available to you. A list can be seen in the Reserved Variables section of the manual or you can get a complete list of them by looking at the output of the phpinfo() function used in the example in the previous section.
You can put multiple PHP statements inside a PHP tag and create little blocks of code that do more than just a single echo. For example, if you want to check for Internet Explorer you can do this:
Przykład #2 Example using control structures and functions
<?php
if (strpos($_SERVER['HTTP_USER_AGENT'], 'MSIE') !== FALSE) {
echo 'You are using Internet Explorer.<br />';
}
?>
A sample output of this script may be:
You are using Internet Explorer.<br />
Here we introduce a couple of new concepts. We have an if statement. If you are familiar with the basic syntax used by the C language, this should look logical to you. Otherwise, you should probably pick up an introductory PHP book and read the first couple of chapters, or read the Language Reference part of the manual.
The second concept we introduced was the strpos()
function call. strpos() is a function built into
PHP which searches a string for another string. In this case we are
looking for 'MSIE' (so-called needle) inside
$_SERVER['HTTP_USER_AGENT'] (so-called haystack). If
the needle is found inside the haystack, the function returns the position
of the needle relative to the start of the haystack. Otherwise, it
returns FALSE. If it does not return FALSE, the if expression evaluates to TRUE
and the code within its {braces} is executed. Otherwise, the code is not
run. Feel free to create similar examples,
with if,
else, and other
functions such as strtoupper() and
strlen(). Each related manual page contains examples
too. If you are unsure how to use functions, you will want to read both
the manual page on how to read a
function definition and the section about
PHP functions.
We can take this a step further and show how you can jump in and out of PHP mode even in the middle of a PHP block:
Przykład #3 Mixing both HTML and PHP modes
<?php
if (strpos($_SERVER['HTTP_USER_AGENT'], 'MSIE') !== FALSE) {
?>
<h3>strpos() must have returned non-false</h3>
<p>You are using Internet Explorer</p>
<?php
} else {
?>
<h3>strpos() must have returned false</h3>
<p>You are not using Internet Explorer</p>
<?php
}
?>
A sample output of this script may be:
<h3>strpos() must have returned non-false</h3> <p>You are using Internet Explorer</p>
Instead of using a PHP echo statement to output something, we jumped out of PHP mode and just sent straight HTML. The important and powerful point to note here is that the logical flow of the script remains intact. Only one of the HTML blocks will end up getting sent to the viewer depending on the result of strpos(). In other words, it depends on whether the string MSIE was found or not.
Dealing with Forms
One of the most powerful features of PHP is the way it handles HTML forms. The basic concept that is important to understand is that any form element will automatically be available to your PHP scripts. Please read the manual section on Variables from external sources for more information and examples on using forms with PHP. Here is an example HTML form:
Przykład #1 A simple HTML form
<form action="action.php" method="post"> <p>Your name: <input type="text" name="name" /></p> <p>Your age: <input type="text" name="age" /></p> <p><input type="submit" /></p> </form>
There is nothing special about this form. It is a straight HTML form with no special tags of any kind. When the user fills in this form and hits the submit button, the action.php page is called. In this file you would write something like this:
Przykład #2 Printing data from our form
Hi <?php echo htmlspecialchars($_POST['name']); ?>.
You are <?php echo (int)$_POST['age']; ?> years old.
A sample output of this script may be:
Hi Joe. You are 22 years old.
Apart from the htmlspecialchars() and (int) parts, it should be obvious what this does. htmlspecialchars() makes sure any characters that are special in html are properly encoded so people can't inject HTML tags or Javascript into your page. For the age field, since we know it is a number, we can just convert it to an integer which will automatically get rid of any stray characters. You can also have PHP do this for you automatically by using the filter extension. The $_POST['name'] and $_POST['age'] variables are automatically set for you by PHP. Earlier we used the $_SERVER superglobal; above we just introduced the $_POST superglobal which contains all POST data. Notice how the method of our form is POST. If we used the method GET then our form information would live in the $_GET superglobal instead. You may also use the $_REQUEST superglobal, if you do not care about the source of your request data. It contains the merged information of GET, POST and COOKIE data. Also see the import_request_variables() function.
You can also deal with XForms input in PHP, although you will find yourself comfortable with the well supported HTML forms for quite some time. While working with XForms is not for beginners, you might be interested in them. We also have a short introduction to handling data received from XForms in our features section.
Using old code with new versions of PHP
Now that PHP has grown to be a popular scripting language, there are a lot of public repositories and libraries containing code you can reuse. The PHP developers have largely tried to preserve backwards compatibility, so a script written for an older version will run (ideally) without changes in a newer version of PHP. In practice, some changes will usually be needed.
Two of the most important recent changes that affect old code are:
- The deprecation of the old $HTTP_*_VARS arrays (which need to be indicated as global when used inside a function or method). The following superglobal arrays were introduced in PHP » 4.1.0. They are: $_GET, $_POST, $_COOKIE, $_SERVER, $_FILES, $_ENV, $_REQUEST, and $_SESSION. The older $HTTP_*_VARS arrays, such as $HTTP_POST_VARS, also exist. Od PHP 5.0.0, długie tablice zmiennych predefiniowanych mogą być wyłączone dyrektywą konfiguracji register_long_arrays.
- External variables are no longer registered in the global scope by default. In other words, as of PHP » 4.2.0 the PHP directive register_globals is off by default in php.ini. The preferred method of accessing these values is via the superglobal arrays mentioned above. Older scripts, books, and tutorials may rely on this directive being on. If it were on, for example, one could use $id from the URL http://www.example.com/foo.php?id=42. Whether on or off, $_GET['id'] is available.
What's next?
With your new knowledge you should be able to understand most of the manual and also the various example scripts available in the example archives. You can also find other examples on the php.net websites in the links section: » http://www.php.net/links.php.
To view various slide presentations that show more of what PHP can do, see the PHP Conference Material Site: » http://talks.php.net/
Instalacja i konfiguracja
Ogólnie o instalacji
Przed instalacją musisz wiedzieć do czego potrzebne ci jest PHP. PHP jest używane głównie w trzech polach, tak jak to zostało opisane w rozdziale Co potrafi PHP?
- skrypty po stronie serwera
- skrypty wywoływane z linii poleceń
- aplikacje po stronie klienta
Dla pierwszej pozycji w najbardziej popularnej postaci potrzebne są trzy rzeczy: samo PHP, serwer WWW i przeglądarka internetowa. Najprawdopodobniej posiadasz już przeglądarkę, i zależnie od systemu operacyjnego także serwer (np. Apache na systemach Linux lub IIS na systemach Windows). Możesz także wynająć przestrzeń na serwerze komercyjnym. Tym sposobem nie musisz niczego własnoręcznie konfigurować, a jedynie pisać skrypty, umieszczać je na serwerze i oglądać wyniki w oknie przeglądarki.
Własnoręcznie konfigurując serwer i PHP masz dwie możliwości połączenia PHP z serwerem. Dla wielu serwerów PHP posiada bezpośredni interfejs modułu (zwany także SAPI). Do tych serwerów należą Apache, Microsoft Internet Information Server, Netscape i iPlanet. Przez wiele innych serwerów jest obsługiwane przez ISAPI, interfejs modułów Microsoft (na przykład OmniHTTPd). Jeśli PHP nie ma obsługi modułowej dla twojego serwera, możesz używać go jako procesor CGI lub FastCGI. Oznacza to, że możesz skonfigurować twój serwer tak, aby korzystał z pliku wykonywalnego PHP (php.exe na systemach Windows) do przetwarzania wszystkich plików PHP dostępnych na serwerze.
Jeśli jesteś zainteresowany używaniem PHP do pisania skryptów wywoływanych z linii poleceń (np. pisania skryptów do automatycznego generowania off-line obrazów dla Ciebie lub przetwarzania plików tekstowych zależnie od przekazanych argumentów), potrzebujesz pliku wykonywalnego PHP. Aby uzyskać więcej informacji przeczytaj rozdział Pisanie aplikacji PHP wywoływanych z linii poleceń. W tym przypadku nie potrzebujesz ani serwera ani przeglądarki.
W PHP możesz pisać także aplikacje z interfejsem użytkownika używając rozszerzenia PHP-GTK. Jest to podejście zupełnie inne niż tworzenie stron internetowych, ponieważ nie wysyłasz żadnego wyjścia HTMLowego, ale obsługujesz okienka i obiekty w nich zawarte. Aby uzyskać więcej informacji o PHP-GTK, odwiedź » stronę poświęconą temu rozszerzeniu. PHP-GTK nie jest zawarte w oficjalnej dystrybucji PHP.
Od tego miejsca rozdział dotyczy konfiguracji PHP z serwerami WWW pracującymi pod kontrolą systemów Unix i Windows w postaci modułów serwera lub binariów CGI. W następnych sekcjach znajdziesz informacje o wywoływaniu PHP z linii poleceń.
Kod źródlowy oraz dystrybucje binarne dla Windows, można znaleźć na stronie » http://www.php.net/downloads.php. Zalecane jest korzystanie z jednego z najbliższego » serweru lustrzanego do pobierania dystrybucji PHP.
Installation on Unix systems
Spis treści
- Apache 1.3.x on Unix systems
- Apache 2.x on Unix systems
- Lighttpd 1.4 on Unix systems
- Sun, iPlanet and Netscape servers on Sun Solaris
- CGI and command line setups
- HP-UX specific installation notes
- OpenBSD installation notes
- Solaris specific installation tips
- Debian GNU/Linux installation notes
This section will guide you through the general configuration and installation of PHP on Unix systems. Be sure to investigate any sections specific to your platform or web server before you begin the process.
As our manual outlines in the General Installation Considerations section, we are mainly dealing with web centric setups of PHP in this section, although we will cover setting up PHP for command line usage as well.
There are several ways to install PHP for the Unix platform, either with a compile and configure process, or through various pre-packaged methods. This documentation is mainly focused around the process of compiling and configuring PHP. Many Unix like systems have some sort of package installation system. This can assist in setting up a standard configuration, but if you need to have a different set of features (such as a secure server, or a different database driver), you may need to build PHP and/or your web server. If you are unfamiliar with building and compiling your own software, it is worth checking to see whether somebody has already built a packaged version of PHP with the features you need.
Prerequisite knowledge and software for compiling:
- Basic Unix skills (being able to operate "make" and a C compiler)
- An ANSI C compiler
- A web server
- Any module specific components (such as GD, PDF libs, etc.)
When building directly from SVN sources or after custom modifications you might also need:
- autoconf: 2.13+ (for PHP < 5.4.0), 2.59+ (for PHP >= 5.4.0)
- automake: 1.4+
- libtool: 1.4.x+ (except 1.4.2)
- re2c: Version 0.13.4 or newer
- flex: Version 2.5.4 (for PHP <= 5.2)
- bison: Version 1.28 (preferred), 1.35, or 1.75
The initial PHP setup and configuration process is controlled by the use of the command line options of the configure script. You could get a list of all available options along with short explanations running ./configure --help. Our manual documents the different options separately. You will find the core options in the appendix, while the different extension specific options are descibed on the reference pages.
When PHP is configured, you are ready to build the module and/or executables. The command make should take care of this. If it fails and you can't figure out why, see the Problems section.
Apache 1.3.x on Unix systems
This section contains notes and hints specific to Apache installs of PHP on Unix platforms. We also have instructions and notes for Apache 2 on a separate page.
You can select arguments to add to the configure on line 10 below from the list of core configure options and from extension specific options described at the respective places in the manual. The version numbers have been omitted here, to ensure the instructions are not incorrect. You will need to replace the 'xxx' here with the correct values from your files.
Przykład #1 Installation Instructions (Apache Shared Module Version) for PHP
1. gunzip apache_xxx.tar.gz
2. tar -xvf apache_xxx.tar
3. gunzip php-xxx.tar.gz
4. tar -xvf php-xxx.tar
5. cd apache_xxx
6. ./configure --prefix=/www --enable-module=so
7. make
8. make install
9. cd ../php-xxx
10. Now, configure your PHP. This is where you customize your PHP
with various options, like which extensions will be enabled. Do a
./configure --help for a list of available options. In our example
we'll do a simple configure with Apache 1 and MySQL support. Your
path to apxs may differ from our example.
./configure --with-mysql --with-apxs=/www/bin/apxs
11. make
12. make install
If you decide to change your configure options after installation,
you only need to repeat the last three steps. You only need to
restart apache for the new module to take effect. A recompile of
Apache is not needed.
Note that unless told otherwise, 'make install' will also install PEAR,
various PHP tools such as phpize, install the PHP CLI, and more.
13. Setup your php.ini file:
cp php.ini-development /usr/local/lib/php.ini
You may edit your .ini file to set PHP options. If you prefer your
php.ini in another location, use --with-config-file-path=/some/path in
step 10.
If you instead choose php.ini-production, be certain to read the list
of changes within, as they affect how PHP behaves.
14. Edit your httpd.conf to load the PHP module. The path on the right hand
side of the LoadModule statement must point to the path of the PHP
module on your system. The make install from above may have already
added this for you, but be sure to check.
LoadModule php5_module libexec/libphp5.so
15. And in the AddModule section of httpd.conf, somewhere under the
ClearModuleList, add this:
AddModule mod_php5.c
16. Tell Apache to parse certain extensions as PHP. For example,
let's have Apache parse the .php extension as PHP. You could
have any extension(s) parse as PHP by simply adding more, with
each separated by a space. We'll add .phtml to demonstrate.
AddType application/x-httpd-php .php .phtml
It's also common to setup the .phps extension to show highlighted PHP
source, this can be done with:
AddType application/x-httpd-php-source .phps
17. Use your normal procedure for starting the Apache server. (You must
stop and restart the server, not just cause the server to reload by
using a HUP or USR1 signal.)
Alternatively, to install PHP as a static object:
Przykład #2 Installation Instructions (Static Module Installation for Apache) for PHP
1. gunzip -c apache_1.3.x.tar.gz | tar xf -
2. cd apache_1.3.x
3. ./configure
4. cd ..
5. gunzip -c php-5.x.y.tar.gz | tar xf -
6. cd php-5.x.y
7. ./configure --with-mysql --with-apache=../apache_1.3.x
8. make
9. make install
10. cd ../apache_1.3.x
11. ./configure --prefix=/www --activate-module=src/modules/php5/libphp5.a
(The above line is correct! Yes, we know libphp5.a does not exist at this
stage. It isn't supposed to. It will be created.)
12. make
(you should now have an httpd binary which you can copy to your Apache bin dir if
it is your first install then you need to "make install" as well)
13. cd ../php-5.x.y
14. cp php.ini-development /usr/local/lib/php.ini
15. You can edit /usr/local/lib/php.ini file to set PHP options.
Edit your httpd.conf or srm.conf file and add:
AddType application/x-httpd-php .php
Depending on your Apache install and Unix variant, there are many possible ways to stop and restart the server. Below are some typical lines used in restarting the server, for different apache/unix installations. You should replace /path/to/ with the path to these applications on your systems.
Przykład #3 Example commands for restarting Apache
1. Several Linux and SysV variants: /etc/rc.d/init.d/httpd restart 2. Using apachectl scripts: /path/to/apachectl stop /path/to/apachectl start 3. httpdctl and httpsdctl (Using OpenSSL), similar to apachectl: /path/to/httpsdctl stop /path/to/httpsdctl start 4. Using mod_ssl, or another SSL server, you may want to manually stop and start: /path/to/apachectl stop /path/to/apachectl startssl
The locations of the apachectl and http(s)dctl binaries often vary. If your system has locate or whereis or which commands, these can assist you in finding your server control programs.
Different examples of compiling PHP for apache are as follows:
./configure --with-apxs --with-pgsql
This will create a libphp5.so shared library that is loaded into Apache using a LoadModule line in Apache's httpd.conf file. The PostgreSQL support is embedded into this library.
./configure --with-apxs --with-pgsql=shared
This will create a libphp5.so shared library for Apache, but it will also create a pgsql.so shared library that is loaded into PHP either by using the extension directive in php.ini file or by loading it explicitly in a script using the dl() function.
./configure --with-apache=/path/to/apache_source --with-pgsql
This will create a libmodphp5.a library, a mod_php5.c and some accompanying files and copy this into the src/modules/php5 directory in the Apache source tree. Then you compile Apache using --activate-module=src/modules/php5/libphp5.a and the Apache build system will create libphp5.a and link it statically into the httpd binary. The PostgreSQL support is included directly into this httpd binary, so the final result here is a single httpd binary that includes all of Apache and all of PHP.
./configure --with-apache=/path/to/apache_source --with-pgsql=shared
Same as before, except instead of including PostgreSQL support directly into the final httpd you will get a pgsql.so shared library that you can load into PHP from either the php.ini file or directly using dl().
When choosing to build PHP in different ways, you should consider the advantages and drawbacks of each method. Building as a shared object will mean that you can compile apache separately, and don't have to recompile everything as you add to, or change, PHP. Building PHP into apache (static method) means that PHP will load and run faster. For more information, see the Apache » web page on DSO support.
Informacja:
Apache's default httpd.conf currently ships with a section that looks like this:
Unless you change that to "Group nogroup" or something like that ("Group daemon" is also very common) PHP will not be able to open files.User nobody Group "#-1"
Informacja:
Make sure you specify the installed version of apxs when using --with-apxs=/path/to/apxs . You must NOT use the apxs version that is in the apache sources but the one that is actually installed on your system.
Apache 2.x on Unix systems
This section contains notes and hints specific to Apache 2.x installs of PHP on Unix systems.
Nie zalecamy korzystania z wątkowanego MPM na produkcyjnych serwerach Apache2. Zamiast niego wskazane jest używanie preforkowanego MPM, który jest domyślny w Apache 2.0 i Apache 2.2. Wyjaśnienie powodów można znaleźć w odpowiednim punkcie FAQ, dotyczącym używania Apache2 z wątkowanym MPM
The » Apache Documentation is the most authoritative source of information on the Apache 2.x server. More information about installation options for Apache may be found there.
The most recent version of Apache HTTP Server may be obtained from » Apache download site, and a fitting PHP version from the above mentioned places. This quick guide covers only the basics to get started with Apache 2.x and PHP. For more information read the » Apache Documentation. The version numbers have been omitted here, to ensure the instructions are not incorrect. In the examples below, 'NN' should be replaced with the specific version of Apache being used.
There are currently two versions of Apache 2.x - there's 2.0 and 2.2. While there are various reasons for choosing each, 2.2 is the current latest version, and the one that is recommended, if that option is available to you. However, the instructions here will work for either 2.0 or 2.2.
-
Obtain the Apache HTTP server from the location listed above, and unpack it:
gzip -d httpd-2_x_NN.tar.gz tar -xf httpd-2_x_NN.tar
-
Likewise, obtain and unpack the PHP source:
gunzip php-NN.tar.gz tar -xf php-NN.tar
-
Build and install Apache. Consult the Apache install documentation for more details on building Apache.
cd httpd-2_x_NN ./configure --enable-so make make install
-
Now you have Apache 2.x.NN available under /usr/local/apache2, configured with loadable module support and the standard MPM prefork. To test the installation use your normal procedure for starting the Apache server, e.g.:
and stop the server to go on with the configuration for PHP:/usr/local/apache2/bin/apachectl start
/usr/local/apache2/bin/apachectl stop
-
Now, configure and build PHP. This is where you customize PHP with various options, like which extensions will be enabled. Run ./configure --help for a list of available options. In our example we'll do a simple configure with Apache 2 and MySQL support.
If you built Apache from source, as described above, the below example will match your path for apxs, but if you installed Apache some other way, you'll need to adjust the path to apxs accordingly. Note that some distros may rename apxs to apxs2.
cd ../php-NN ./configure --with-apxs2=/usr/local/apache2/bin/apxs --with-mysql make make install
If you decide to change your configure options after installation, you'll need to re-run the configure, make, and make install steps. You only need to restart apache for the new module to take effect. A recompile of Apache is not needed.
Note that unless told otherwise, 'make install' will also install PEAR, various PHP tools such as phpize, install the PHP CLI, and more.
-
Setup your php.ini
cp php.ini-development /usr/local/lib/php.ini
You may edit your .ini file to set PHP options. If you prefer having php.ini in another location, use --with-config-file-path=/some/path in step 5.
If you instead choose php.ini-production, be certain to read the list of changes within, as they affect how PHP behaves.
-
Edit your httpd.conf to load the PHP module. The path on the right hand side of the LoadModule statement must point to the path of the PHP module on your system. The make install from above may have already added this for you, but be sure to check.
LoadModule php5_module modules/libphp5.so
-
Tell Apache to parse certain extensions as PHP. For example, let's have Apache parse .php files as PHP. Instead of only using the Apache AddType directive, we want to avoid potentially dangerous uploads and created files such as exploit.php.jpg from being executed as PHP. Using this example, you could have any extension(s) parse as PHP by simply adding them. We'll add .php to demonstrate.
<FilesMatch \.php$> SetHandler application/x-httpd-php </FilesMatch>Or, if we wanted to allow .php, .php2, .php3, .php4, .php5, .php6, and .phtml files to be executed as PHP, but nothing else, we'd use this:
<FilesMatch "\.ph(p[2-6]?|tml)$"> SetHandler application/x-httpd-php </FilesMatch>And to allow .phps files to be handled by the php source filter, and displayed as syntax-highlighted source code, use this:
<FilesMatch "\.phps$"> SetHandler application/x-httpd-php-source </FilesMatch>mod_rewrite may be used To allow any arbitrary .php file to be displayed as syntax-highlighted source code, without having to rename or copy it to a .phps file:
RewriteEngine On RewriteRule (.*\.php)s$ $1 [H=application/x-httpd-php-source]
The php source filter should not be enabled on production systems, where it may expose confidential or otherwise sensitive information embedded in source code.
-
Use your normal procedure for starting the Apache server, e.g.:
/usr/local/apache2/bin/apachectl start
OR
service httpd restart
Following the steps above you will have a running Apache2 web server with support for PHP as a SAPI module. Of course there are many more configuration options available Apache and PHP. For more information type ./configure --help in the corresponding source tree.
Apache may be built multithreaded by selecting the worker MPM, rather than the standard prefork MPM, when Apache is built. This is done by adding the following option to the argument passed to ./configure, in step 3 above:
--with-mpm=worker
This should not be undertaken without being aware of the consequences of this decision, and having at least a fair understanding of the implications. The Apache documentation regarding » MPM-Modules discusses MPMs in a great deal more detail.
Informacja:
The Apache MultiViews FAQ discusses using multiviews with PHP.
Informacja:
To build a multithreaded version of Apache, the target system must support threads. In this case, PHP should also be built with experimental Zend Thread Safety (ZTS). Under this configuration, not all extensions will be available. The recommended setup is to build Apache with the default prefork MPM-Module.
Lighttpd 1.4 on Unix systems
This section contains notes and hints specific to Lighttpd 1.4 installs of PHP on Unix systems.
Please use the » Lighttpd trac to learn how to install Lighttpd properly before continuing.
Fastcgi is the preferred SAPI to connect PHP and Lighttpd. Fastcgi is automagically enabled in php-cgi in PHP 5.3, but for older versions configure PHP with --enable-fastcgi. To confirm that PHP has fastcgi enabled, php -v should contain PHP 5.2.5 (cgi-fcgi) Before PHP 5.2.3, fastcgi was enabled on the php binary (there was no php-cgi).
Letting Lighttpd spawn php processes
To configure Lighttpd to connect to php and spawn fastcgi processes, edit lighttpd.conf. Sockets are preferred to connect to fastcgi processes on the local system.
Przykład #1 Partial lighttpd.conf
server.modules += ( "mod_fastcgi" )
fastcgi.server = ( ".php" =>
((
"socket" => "/tmp/php.socket",
"bin-path" => "/usr/local/bin/php-cgi",
"bin-environment" => (
"PHP_FCGI_CHILDREN" => "16",
"PHP_FCGI_MAX_REQUESTS" => "10000"
),
"min-procs" => 1,
"max-procs" => 1,
"idle-timeout" => 20
))
)
The bin-path directive allows lighttpd to spawn fastcgi processes dynamically. PHP will spawn children according to the PHP_FCGI_CHILDREN environment variable. The "bin-environment" directive sets the environment for the spawned processes. PHP will kill a child process after the number of requests specified by PHP_FCGI_MAX_REQUESTS is reached. The directives "min-procs" and "max-procs" should generally be avoided with PHP. PHP manages its own children and opcode caches like APC will only share among children managed by PHP. If "min-procs" is set to something greater than 1, the total number of php responders will be multiplied PHP_FCGI_CHILDREN (2 min-procs * 16 children gives 32 responders).
Spawning with spawn-fcgi
Lighttpd provides a program called spawn-fcgi to ease the process of spawning fastcgi processes easier.
Spawning php-cgi
It is possible to spawn processes without spawn-fcgi, though a bit of heavy-lifting is required. Setting the PHP_FCGI_CHILDREN environment var controls how many children PHP will spawn to handle incoming requests. Setting PHP_FCGI_MAX_REQUESTS will determine how long (in requests) each child will live. Here's a simple bash script to help spawn php responders.
Przykład #2 Spawning FastCGI Responders
#!/bin/sh
# Location of the php-cgi binary
PHP=/usr/local/bin/php-cgi
# PID File location
PHP_PID=/tmp/php.pid
# Binding to an address
#FCGI_BIND_ADDRESS=10.0.1.1:10000
# Binding to a domain socket
FCGI_BIND_ADDRESS=/tmp/php.sock
PHP_FCGI_CHILDREN=16
PHP_FCGI_MAX_REQUESTS=10000
env -i PHP_FCGI_CHILDREN=$PHP_FCGI_CHILDREN \
PHP_FCGI_MAX_REQUESTS=$PHP_FCGI_MAX_REQUESTS \
$PHP -b $FCGI_BIND_ADDRESS &
echo $! > "$PHP_PID"
Connecting to remote FCGI instances
Fastcgi instances can be spawned on multiple remote machines in order to scale applications.
Przykład #3 Connecting to remote php-fastcgi instances
fastcgi.server = ( ".php" =>
(( "host" => "10.0.0.2", "port" => 1030 ),
( "host" => "10.0.0.3", "port" => 1030 ))
)
Sun, iPlanet and Netscape servers on Sun Solaris
This section contains notes and hints specific to Sun Java System Web Server, Sun ONE Web Server, iPlanet and Netscape server installs of PHP on Sun Solaris.
From PHP 4.3.3 on you can use PHP scripts with the NSAPI module to generate custom directory listings and error pages. Additional functions for Apache compatibility are also available. For support in current web servers read the note about subrequests.
You can find more information about setting up PHP for the Netscape Enterprise Server (NES) here: » http://benoit.noss.free.fr/php/install-php4.html
To build PHP with Sun JSWS/Sun ONE WS/iPlanet/Netscape web servers, enter the proper install directory for the --with-nsapi=[DIR] option. The default directory is usually /opt/netscape/suitespot/. Please also read /php-xxx-version/sapi/nsapi/nsapi-readme.txt.
-
Install the following packages from » http://www.sunfreeware.com/ or another download site:
- autoconf-2.13
- automake-1.4
- bison-1_25-sol26-sparc-local
- flex-2_5_4a-sol26-sparc-local
- gcc-2_95_2-sol26-sparc-local
- gzip-1.2.4-sol26-sparc-local
- m4-1_4-sol26-sparc-local
- make-3_76_1-sol26-sparc-local
- mysql-3.23.24-beta (if you want mysql support)
- perl-5_005_03-sol26-sparc-local
- tar-1.13 (GNU tar)
-
Make sure your path includes the proper directories
PATH=.:/usr/local/bin:/usr/sbin:/usr/bin:/usr/ccs/bin
and make it available to your system
export PATH. -
gunzip php-x.x.x.tar.gz(if you have a .gz dist, otherwise go to 4). -
tar xvf php-x.x.x.tar -
Change to your extracted PHP directory:
cd ../php-x.x.x -
For the following step, make sure /opt/netscape/suitespot/ is where your netscape server is installed. Otherwise, change to the correct path and run:
./configure --with-mysql=/usr/local/mysql \ --with-nsapi=/opt/netscape/suitespot/ \ --enable-libgcc
- Run make followed by make install.
After performing the base install and reading the appropriate readme file, you may need to perform some additional configuration steps.
Configuration Instructions for Sun/iPlanet/Netscape
Firstly you may need to add some paths to the LD_LIBRARY_PATH environment for the server to find all the shared libs. This can best done in the start script for your web server. The start script is often located in: /path/to/server/https-servername/start. You may also need to edit the configuration files that are located in: /path/to/server/https-servername/config/.
-
Add the following line to mime.types (you can do that by the administration server):
type=magnus-internal/x-httpd-php exts=php
-
Edit magnus.conf (for servers >= 6) or obj.conf (for servers < 6) and add the following, shlib will vary depending on your system, it will be something like /opt/netscape/suitespot/bin/libphp4.so. You should place the following lines after mime types init.
(PHP >= 4.3.3) The php_ini parameter is optional but with it you can place your php.ini in your web server config directory.Init fn="load-modules" funcs="php4_init,php4_execute,php4_auth_trans" shlib="/opt/netscape/suitespot/bin/libphp4.so" Init fn="php4_init" LateInit="yes" errorString="Failed to initialize PHP!" [php_ini="/path/to/php.ini"]
-
Configure the default object in obj.conf (for virtual server classes [version 6.0+] in their vserver.obj.conf):
(PHP >= 4.3.3) As additional parameters you can add some special php.ini-values, for example you can set a docroot="/path/to/docroot" specific to the context php4_execute is called. For boolean ini-keys please use 0/1 as value, not "On","Off",... (this will not work correctly), e.g. zlib.output_compression=1 instead of zlib.output_compression="On"<Object name="default"> . . . .#NOTE this next line should happen after all 'ObjectType' and before all 'AddLog' lines Service fn="php4_execute" type="magnus-internal/x-httpd-php" [inikey=value inikey=value ...] . . </Object>
-
This is only needed if you want to configure a directory that only consists of PHP scripts (same like a cgi-bin directory):
After that you can configure a directory in the Administration server and assign it the style x-httpd-php. All files in it will get executed as PHP. This is nice to hide PHP usage by renaming files to .html.<Object name="x-httpd-php"> ObjectType fn="force-type" type="magnus-internal/x-httpd-php" Service fn=php4_execute [inikey=value inikey=value ...] </Object>
-
Setup of authentication: PHP authentication cannot be used with any other authentication. ALL AUTHENTICATION IS PASSED TO YOUR PHP SCRIPT. To configure PHP Authentication for the entire server, add the following line to your default object:
<Object name="default"> AuthTrans fn=php4_auth_trans . . . </Object>
-
To use PHP Authentication on a single directory, add the following:
<Object ppath="d:\path\to\authenticated\dir\*"> AuthTrans fn=php4_auth_trans </Object>
Informacja:
The stacksize that PHP uses depends on the configuration of the web server. If you get crashes with very large PHP scripts, it is recommended to raise it with the Admin Server (in the section "MAGNUS EDITOR").
CGI environment and recommended modifications in php.ini
Important when writing PHP scripts is the fact that Sun JSWS/Sun ONE WS/iPlanet/Netscape is a multithreaded web server. Because of that all requests are running in the same process space (the space of the web server itself) and this space has only one environment. If you want to get CGI variables like PATH_INFO, HTTP_HOST etc. it is not the correct way to try this in the old PHP way with getenv() or a similar way (register globals to environment, $_ENV). You would only get the environment of the running web server without any valid CGI variables!
Informacja:
Why are there (invalid) CGI variables in the environment?
Answer: This is because you started the web server process from the admin server which runs the startup script of the web server, you wanted to start, as a CGI script (a CGI script inside of the admin server!). This is why the environment of the started web server has some CGI environment variables in it. You can test this by starting the web server not from the administration server. Use the command line as root user and start it manually - you will see there are no CGI-like environment variables.
Simply change your scripts to get CGI variables in the correct way for PHP 4.x by using the superglobal $_SERVER. If you have older scripts which use $HTTP_HOST, etc., you should turn on register_globals in php.ini and change the variable order too (important: remove "E" from it, because you do not need the environment here):
variables_order = "GPCS" register_globals = On
Special use for error pages or self-made directory listings (PHP >= 4.3.3)
You can use PHP to generate the error pages for "404 Not Found" or similar. Add the following line to the object in obj.conf for every error page you want to overwrite:
Error fn="php4_execute" code=XXX script="/path/to/script.php" [inikey=value inikey=value...]
Another possibility is to generate self-made directory listings. Just create a PHP script which displays a directory listing and replace the corresponding default Service line for type="magnus-internal/directory" in obj.conf with the following:
Service fn="php4_execute" type="magnus-internal/directory" script="/path/to/script.php" [inikey=value inikey=value...]
Note about nsapi_virtual() and subrequests (PHP >= 4.3.3)
The NSAPI module now supports the nsapi_virtual() function (alias: virtual()) to make subrequests on the web server and insert the result in the web page. This function uses some undocumented features from the NSAPI library. On Unix the module automatically looks for the needed functions and uses them if available. If not, nsapi_virtual() is disabled.
Informacja:
But be warned: Support for nsapi_virtual() is EXPERIMENTAL!!!
CGI and command line setups
By default, PHP is built as both a CLI and CGI program, which can be used for CGI processing. If you are running a web server that PHP has module support for, you should generally go for that solution for performance reasons. However, the CGI version enables users to run different PHP-enabled pages under different user-ids.
Używając instalacji CGI, serwer jest podatny na wiele potencjalnych ataków. Sposoby obrony przed nimi zostały opisane w rozdziale o bezpieczeństwie instalacji CGI.
Testing
If you have built PHP as a CGI program, you may test your build by typing make test. It is always a good idea to test your build. This way you may catch a problem with PHP on your platform early instead of having to struggle with it later.
Using Variables
Some server supplied environment variables are not defined in the current » CGI/1.1 specification. Only the following variables are defined there: AUTH_TYPE, CONTENT_LENGTH, CONTENT_TYPE, GATEWAY_INTERFACE, PATH_INFO, PATH_TRANSLATED, QUERY_STRING, REMOTE_ADDR, REMOTE_HOST, REMOTE_IDENT, REMOTE_USER, REQUEST_METHOD, SCRIPT_NAME, SERVER_NAME, SERVER_PORT, SERVER_PROTOCOL, and SERVER_SOFTWARE. Everything else should be treated as 'vendor extensions'.
HP-UX specific installation notes
This section contains notes and hints specific to installing PHP on HP-UX systems.
There are two main options for installing PHP on HP-UX systems. Either compile it, or install a pre-compiled binary.
Official pre-compiled packages are located here: » http://software.hp.com/
Until this manual section is rewritten, the documentation about compiling PHP (and related extensions) on HP-UX systems has been removed. For now, consider reading the following external resource: » Building Apache and PHP on HP-UX 11.11
OpenBSD installation notes
This section contains notes and hints specific to installing PHP on » OpenBSD 3.6.
Using Binary Packages
Using binary packages to install PHP on OpenBSD is the recommended and simplest method. The core package has been separated from the various modules, and each can be installed and removed independently from the others. The files you need can be found on your OpenBSD CD or on the FTP site.
The main package you need to install is php4-core-4.3.8.tgz, which contains the basic engine (plus gettext and iconv). Next, take a look at the module packages, such as php4-mysql-4.3.8.tgz or php4-imap-4.3.8.tgz. You need to use the phpxs command to activate and deactivate these modules in your php.ini.
Przykład #1 OpenBSD Package Install Example
# pkg_add php4-core-4.3.8.tgz # /usr/local/sbin/phpxs -s # cp /usr/local/share/doc/php4/php.ini-recommended /var/www/conf/php.ini (add in mysql) # pkg_add php4-mysql-4.3.8.tgz # /usr/local/sbin/phpxs -a mysql (add in imap) # pkg_add php4-imap-4.3.8.tgz # /usr/local/sbin/phpxs -a imap (remove mysql as a test) # pkg_delete php4-mysql-4.3.8 # /usr/local/sbin/phpxs -r mysql (install the PEAR libraries) # pkg_add php4-pear-4.3.8.tgz
Read the » packages(7) manual page for more information about binary packages on OpenBSD.
Using Ports
You can also compile up PHP from source using the » ports tree. However, this is only recommended for users familiar with OpenBSD. The PHP 4 port is split into two sub-directories: core and extensions. The extensions directory generates sub-packages for all of the supported PHP modules. If you find you do not want to create some of these modules, use the no_* FLAVOR. For example, to skip building the imap module, set the FLAVOR to no_imap.
Common Problems
- The default install of Apache runs inside a » chroot(2) jail, which will restrict PHP scripts to accessing files under /var/www. You will therefore need to create a /var/www/tmp directory for PHP session files to be stored, or use an alternative session backend. In addition, database sockets need to be placed inside the jail or listen on the localhost interface. If you use network functions, some files from /etc such as /etc/resolv.conf and /etc/services will need to be moved into /var/www/etc. The OpenBSD PEAR package automatically installs into the correct chroot directories, so no special modification is needed there. More information on the OpenBSD Apache is available in the » OpenBSD FAQ.
- The OpenBSD 3.6 package for the » gd extension requires XFree86 to be installed. If you do not wish to use some of the font features that require X11, install the php4-gd-4.3.8-no_x11.tgz package instead.
Older Releases
Older releases of OpenBSD used the FLAVORS system to compile up a statically linked PHP. Since it is hard to generate binary packages using this method, it is now deprecated. You can still use the old stable ports trees if you wish, but they are unsupported by the OpenBSD team. If you have any comments about this, the current maintainer for the port is Anil Madhavapeddy (avsm at openbsd dot org).
Solaris specific installation tips
This section contains notes and hints specific to installing PHP on Solaris systems.
Required software
Solaris installs often lack C compilers and their related tools. Read this FAQ for information on why using GNU versions for some of these tools is necessary.
For unpacking the PHP distribution you need
- tar
- gzip or
- bzip2
For compiling PHP you need
- gcc (recommended, other C compilers may work)
- make
- GNU sed
For building extra extensions or hacking the code of PHP you might also need
- flex (up to PHP 5.2)
- re2c
- bison
- m4
- autoconf
- automake
Using Packages
You can simplify the Solaris install process by using pkgadd to install most of your needed components. The Image Packaging System (IPS) for Solaris 11 Express also contains most of the required components for installation using the pkg command.
Debian GNU/Linux installation notes
This section contains notes and hints specific to installing PHP on » Debian GNU/Linux.
Unofficial builds from third-parties are not supported here. Any bugs should be reported to the Debian team unless they can be reproduced using the latest builds from our » download area.
While the instructions for building PHP on Unix apply to Debian as well, this manual page contains specific information for other options, such as using either the apt-get or aptitude commands. This manual page uses these two commands interchangeably.
Using APT
First, note that other related packages may be desired like libapache2-mod-php5 to integrate with Apache 2, and php-pear for PEAR.
Second, before installing a package, it's wise to ensure the package list is up to date. Typically, this is done by running the command apt-get update.
Przykład #1 Debian Install Example with Apache 2
# apt-get install php5-common libapache2-mod-php5 php5-cli
APT will automatically install the PHP 5 module for Apache 2 and all of its dependencies, and then activate it. Apache should be restarted in order for the changes take place. For example:
Przykład #2 Stopping and starting Apache once PHP is installed
# /etc/init.d/apache2 stop # /etc/init.d/apache2 start
Better control of configuration
In the last section, PHP was installed with only core modules. It's very likely that additional modules will be desired, such as MySQL, cURL, GD, etc. These may also be installed via the apt-get command.
Przykład #3 Methods for listing additional PHP 5 packages
# apt-cache search php5 # aptitude search php5 # aptitude search php5 |grep -i mysql
The examples will show a lot of packages including several PHP specific ones like php5-cgi, php5-cli and php5-dev. Determine which are needed and install them like any other with either apt-get or aptitude. And because Debian performs dependency checks, it'll prompt for those so for example to install MySQL and cURL:
Przykład #4 Install PHP with MySQL, cURL
# apt-get install php5-mysql php5-curl
APT will automatically add the appropriate lines to the different php.ini related files like /etc/php5/apache2/php.ini, /etc/php5/conf.d/pdo.ini, etc. and depending on the extension will add entries similar to extension=foo.so. However, restarting the web server (like Apache) is required before these changes take affect.
Common Problems
- If the PHP scripts are not parsing via the web server, then it's likely that PHP was not added to the web server's configuration file, which on Debian may be /etc/apache2/apache2.conf or similar. See the Debian manual for further details.
- If an extension was seemingly installed yet the functions are undefined, be sure that the appropriate ini file is being loaded and/or the web server was restarted after installation.
- There are two basic commands for installing packages on Debian (and other linux variants): apt-get and aptitude. However, explaining the subtle differences between these commands goes beyond the scope of this manual.
Installation on Mac OS X
Spis treści
This section contains notes and hints specific to installing PHP on Mac OS X. PHP is bundled with Macs, and compiling is similar to the Unix installation guide.
Using Packages
There are a few pre-packaged and pre-compiled versions of PHP for Mac OS X. This can help in setting up a standard configuration, but if you need to have a different set of features (such as a secure server, or a different database driver), you may need to build PHP and/or your web server yourself. If you are unfamiliar with building and compiling your own software, it's worth checking whether somebody has already built a packaged version of PHP with the features you need.
The following resources offer easy to install packages and precompiled binaries for PHP on Mac OS:
- MacPorts: » http://www.macports.org/
- Entropy: » http://www.entropy.ch/software/macosx/php/
- Fink: » http://www.finkproject.org/
- Homebrew: » http://github.com/mxcl/homebrew
Using the bundled PHP
PHP has come standard with Macs since OS X version 10.0.0. Enabling PHP with the default web server requires uncommenting a few lines in the Apache configuration file httpd.conf whereas the CGI and/or CLI are enabled by default (easily accessible via the Terminal program).
Enabling PHP using the instructions below is meant for quickly setting up a local development environment. It's highly recommended to always upgrade PHP to the newest version. Like most live software, newer versions are created to fix bugs and add features and PHP being is no different. See the appropriate MAC OS X installation documentation for further details. The following instructions are geared towards a beginner with details provided for getting a default setup to work. All users are encouraged to compile, or install a new packaged version.
The standard installation type is using mod_php, and enabling the bundled mod_php on Mac OS X for the Apache web server (the default web server, that is accessible via System Preferences) involves the following steps:
-
Locate and open the Apache configuration file. By default, the location
is as follows: /private/etc/apache2/httpd.conf
Using Finder or Spotlight to find
this file may prove difficult as by default it's private and owned by
the root user.
Informacja: One way to open this is by using a Unix based text editor in the Terminal, for example nano, and because the file is owned by root we'll use the sudo command to open it (as root) so for example type the following into the Terminal Application (after, it will prompt for a password): sudo nano /private/etc/apache2/httpd.conf Noteworthy nano commands: ^w (search), ^o (save), and ^x (exit) where ^ represents the Ctrl key.
Informacja: Versions of Mac OS X prior to 10.5 were bundled with older versions of PHP and Apache. As such, the Apache configuration file on legacy machines may be /etc/httpd/httpd.conf.
-
With a text editor, uncomment the lines (by removing the #) that look similar to the following (these two lines are often not together, locate them both in the file):
Notice the location/path. When building PHP in the future, the above files should be replaced or commented out.# LoadModule php5_module libexec/httpd/libphp5.so # AddModule mod_php5.c
-
Be sure the desired extensions will parse as PHP (examples: .php .html and .inc)
Due to the following statement already existing in httpd.conf (as of Mac Panther), once PHP is enabled the .php files will automatically parse as PHP.
<IfModule mod_php5.c> # If php is turned on, we respect .php and .phps files. AddType application/x-httpd-php .php AddType application/x-httpd-php-source .phps # Since most users will want index.php to work we # also automatically enable index.php <IfModule mod_dir.c> DirectoryIndex index.html index.php </IfModule> </IfModule>Informacja:
Before OS X 10.5 (Leopard), PHP 4 was bundled instead of PHP 5 in which case the above instructions will differ slightly by changing 5's to 4's.
- Be sure the DirectoryIndex loads the desired default index file This is also set in httpd.conf. Typically index.php and index.html are used. By default index.php is enabled because it's also in the PHP check shown above. Adjust accordingly.
- Set the php.ini location or use the default A typical default location on Mac OS X is /usr/local/php/php.ini and a call to phpinfo() will reveal this information. If a php.ini is not used, PHP will use all default values. See also the related FAQ on finding php.ini.
- Locate or set the DocumentRoot This is the root directory for all the web files. Files in this directory are served from the web server so the PHP files will parse as PHP before outputting them to the browser. A typical default path is /Library/WebServer/Documents but this can be set to anything in httpd.conf. Alternatively, the default DocumentRoot for individual users is /Users/yourusername/Sites
-
Create a phpinfo() file
The phpinfo() function will display information about PHP. Consider creating a file in the DocumentRoot with the following PHP code:
<?php phpinfo(); ?> - Restart Apache, and load the PHP file created above To restart, either execute sudo apachectl graceful in the shell or stop/start the "Personal Web Server" option in the OS X System Preferences. By default, loading local files in the browser will have an URL like so: http://localhost/info.php Or using the DocumentRoot in the user directory is another option and would end up looking like: http://localhost/~yourusername/info.php
The CLI (or CGI in older versions) is appropriately named php and likely exists as /usr/bin/php. Open up the terminal, read the command line section of the PHP manual, and execute php -v to check the PHP version of this PHP binary. A call to phpinfo() will also reveal this information.
Installation on Windows systems
Spis treści
- Windows Installer (PHP 5.1.0 and earlier)
- Windows Installer (PHP 5.2 and later)
- Manual Installation Steps
- Microsoft IIS
- Microsoft IIS 5.1 and IIS 6.0
- Microsoft IIS 7.0 and later
- Apache 1.3.x on Microsoft Windows
- Apache 2.x on Microsoft Windows
- Sun, iPlanet and Netscape servers on Microsoft Windows
- Sambar Server on Microsoft Windows
- Xitami on Microsoft Windows
- Building from source
- Installation of extensions on Windows
- Command Line PHP on Microsoft Windows
This section applies to Windows 98/Me and Windows NT/2000/XP/2003. PHP will not work on 16 bit platforms such as Windows 3.1 and sometimes we refer to the supported Windows platforms as Win32.
Informacja:
Windows 98/Me/NT4 is no longer supported as of PHP 5.3.0.
Informacja:
Windows 95 is no longer supported as of PHP 4.3.0.
There are two main ways to install PHP for Windows: either manually or by using the installer.
If you have a development environment such as Microsoft Visual Studio, you can also build PHP from the original source code.
Once you have PHP installed on your Windows system, you may also want to load various extensions for added functionality.
There are several all-in-one installers over the Internet, but none of those are endorsed by PHP.net, as we believe that using one of the official Windows packages from » http://www.php.net/downloads.php is the best choice to have your system secure and optimized.
Windows Installer (PHP 5.1.0 and earlier)
The Windows PHP installer is available from the downloads page at » http://www.php.net/downloads.php. This installs the CGI version of PHP and for IIS, PWS, and Xitami, it configures the web server as well. The installer does not include any extra external PHP extensions (php_*.dll) as you'll only find those in the Windows Zip Package and PECL downloads.
Informacja:
While the Windows installer is an easy way to make PHP work, it is restricted in many aspects as, for example, the automatic setup of extensions is not supported. Use of the installer isn't the preferred method for installing PHP.
First, install your selected HTTP (web) server on your system, and make sure that it works.
Run the executable installer and follow the instructions provided by the installation wizard. Two types of installation are supported - standard, which provides sensible defaults for all the settings it can, and advanced, which asks questions as it goes along.
The installation wizard gathers enough information to set up the php.ini file, and configure certain web servers to use PHP. One of the web servers the PHP installer does not configure for is Apache, so you'll need to configure it manually.
Once the installation has completed, the installer will inform you if you need to restart your system, restart the server, or just start using PHP.
Be aware, that this setup of PHP is not secure. If you would like to have a secure PHP setup, you'd better go on the manual way, and set every option carefully. This automatically working setup gives you an instantly working PHP installation, but it is not meant to be used on online servers.
Windows Installer (PHP 5.2 and later)
The Windows PHP installer for later versions of PHP is built using MSI technology using the Wix Toolkit (» http://wix.sourceforge.net/). It will install and configure PHP and all the built-in and PECL extensions, as well as configure many of the popular web servers such as IIS, Apache, and Xitami.
First, install your selected HTTP (web) server on your system, and make sure that it works. Then proceed with one of the following install types.
Normal Install
Run the MSI installer and follow the instructions provided by the installation wizard. You will be prompted to select the Web Server you wish to configure first, along with any configuration details needed.
You will then be prompted to select which features and extensions you wish to install and enable. By selecting "Will be installed on local hard drive" in the drop-down menu for each item you can trigger whether to install the feature or not. By selecting "Entire feature will be installed on local hard drive", you will be able to install all sub-features of the included feature (for example by selecting this option for the feature "PDO" you will install all PDO Drivers).
It is not recommended to install all extensions by default, since many of them require dependencies from outside PHP in order to function properly. Instead, use the Installation Repair Mode that can be triggered thru the 'Add/Remove Programs' control panel to enable or disable extensions and features after installation.
The installer then sets up PHP to be used in Windows and the php.ini file, and configures certain web servers to use PHP. The installer will currently configure IIS, Apache, Xitami, and Sambar Server; if you are using a different web server you'll need to configure it manually.
Silent Install
The installer also supports a silent mode, which is helpful for Systems Administrators to deploy PHP easily. To use silent mode:
msiexec.exe /i php-VERSION-win32-install.msi /q
You can control the install directory by passing it as a parameter to the install. For example, to install to e:\php:
msiexec.exe /i php-VERSION-win32-install.msi /q INSTALLDIR=e:\php
You can also specify what features to install. For example, to install the mysqli extension and the CGI executable:
msiexec.exe /i php-VERSION-win32-install.msi /q ADDLOCAL=cgi,ext_php_mysqli
The current list of Features to install is as follows:
MainExecutable - php.exe executable ( no longer available as of PHP 5.2.10/5.3.0; it is now included by default ) ScriptExecutable - php-win.exe executable ext_php_* - the various extensions ( for example: ext_php_mysql for MySQL ) apache13 - Apache 1.3 module apache20 - Apache 2.0 module apache22 - Apache 2.2 module apacheCGI - Apache CGI executable iis4ISAPI - IIS ISAPI module iis4CGI - IIS CGI executable iis4FastCGI - IIS CGI executable NSAPI - Sun/iPlanet/Netscape server module netserve - NetServe Web Server CGI executable Xitami - Xitami CGI executable Sambar - Sambar Server ISAPI module CGI - php-cgi.exe executable PEAR - PEAR installer Manual - PHP Manual in CHM Format
For more information on installing MSI installers from the command line, visit » http://msdn.microsoft.com/en-us/library/aa367988.aspx
Upgrading PHP with the Install
To upgrade, run the installer either graphically or from the command line as normal. The installer will read your current install options, remove your old installation, and reinstall PHP with the same options as before. It is recommended that you use this method of keeping PHP updated instead of manually replacing the files in the installation directory.
Manual Installation Steps
This section contains instructions for manually installing and configuring PHP on Microsoft Windows. For the instructions on how to use PHP installer to setup and configure PHP and a web server on Windows refer to Windows Installer (PHP 5.2 and later).
Selecting and downloading the PHP distribution package
Download the PHP zip binary distribution from » PHP for Windows: Binaries and Sources. There are several different versions of the zip package - chose the version that is suitable for the web server being used:
-
If PHP is used with IIS then choose PHP 5.3 VC9 Non Thread Safe or PHP 5.2 VC6 Non Thread Safe;
-
If PHP is used with IIS7 or greater and PHP 5.3+, then the VC9 binaries of PHP should be used.
-
If PHP is used with Apache 1 or Apache 2 then choose PHP 5.3 VC6 or PHP 5.2 VC6.
Informacja:
VC9 Versions are compiled with the Visual Studio 2008 compiler and have improvements in performance and stability. The VC9 versions require you to have the » Microsoft 2008 C++ Runtime (x86) or the » Microsoft 2008 C++ Runtime (x64) installed.
The PHP package structure and content
Unpack the content of the zip archive into a directory of your choice, for example C:\PHP\. The directory and file structure extracted from the zip will look as below:
Przykład #1 PHP 5 package structure
c:\php | +--dev | | | |-php5ts.lib -- php5.lib in non thread safe version | +--ext -- extension DLLs for PHP | | | |-php_bz2.dll | | | |-php_cpdf.dll | | | |-... | +--extras -- empty | +--pear -- initial copy of PEAR | | |-go-pear.bat -- PEAR setup script | |-... | |-php-cgi.exe -- CGI executable | |-php-win.exe -- executes scripts without an opened command prompt | |-php.exe -- Command line PHP executable (CLI) | |-... | |-php.ini-development -- default php.ini settings | |-php.ini-production -- recommended php.ini settings | |-php5apache2_2.dll -- does not exist in non thread safe version | |-php5apache2_2_filter.dll -- does not exist in non thread safe version | |-... | |-php5ts.dll -- core PHP DLL ( php5.dll in non thread safe version) | |-...
Below is the list of the modules and executables included in the PHP zip distribution:
-
go-pear.bat - the PEAR setup script. Refer to » Installation (PEAR) for more details.
-
php-cgi.exe - CGI executable that can be used when running PHP on IIS via CGI or FastCGI.
-
php-win.exe - the PHP executable for executing PHP scripts without using a command line window (for example PHP applications that use Windows GUI).
-
php.exe - the PHP executable for executing PHP scripts within a command line interface (CLI).
-
php5apache2_2.dll - Apache 2.2.X module.
-
php5apache2_2_filter.dll - Apache 2.2.X filter.
Changing the php.ini file
After the php package content has been extracted, copy the php.ini-production into php.ini in the same folder. If necessary, it is also possible to place the php.ini into any other location of your choice but that will require additional configuration steps as described in PHP Configuration.
The php.ini file tells PHP how to configure itself, and how to work with the environment that it runs in. Here are a number of settings for the php.ini file that help PHP work better with Windows. Some of these are optional. There are many other directives that may be relevant to your environment - refer to the list of php.ini directives for more information.
Required directives:
-
extension_dir = <path to extension directory> - The extension_dir needs to point to the directory where PHP extensions files are stored. The path can be absolute (i.e. "C:\PHP\ext") or relative (i.e. ".\ext"). Extensions that are listed lower in the php.ini file need to be located in the extension_dir.
-
extension = xxxxx.dll - For each extension you wish to enable, you need a corresponding "extension=" directive that tells PHP which extensions in the extension_dir to load at startup time.
-
log_errors = On - PHP has an error logging facility that can be used to send errors to a file, or to a service (i.e. syslog) and works in conjunction with the error_log directive below. When running under IIS, the log_errors should be enabled, with a valid error_log.
-
error_log = <path to the error log file> - The error_log needs to specify the absolute, or relative path to the file where PHP errors should be logged. This file needs to be writable for the web server. The most common places for this file are in various TEMP directories, for example "C:\inetpub\temp\php-errors.log".
-
cgi.force_redirect = 0 - This directive is required for running under IIS. It is a directory security facility required by many other web servers. However, enabling it under IIS will cause the PHP engine to fail on Windows.
-
cgi.fix_pathinfo = 1 - This lets PHP access real path info following the CGI Spec. The IIS FastCGI implementation needs this set.
-
fastcgi.impersonate = 1 - FastCGI under IIS supports the ability to impersonate security tokens of the calling client. This allows IIS to define the security context that the request runs under.
-
fastcgi.logging = 0 - FastCGI logging should be disabled on IIS. If it is left enabled, then any messages of any class are treated by FastCGI as error conditions which will cause IIS to generate an HTTP 500 exception.
Optional directives
-
max_execution_time = ## - This directive tells PHP the maximum amount of time that it can spend executing any given script. The default for this is 30 seconds. Increase the value of this directive if PHP application take long time to execute.
-
memory_limit = ###M - The amount of memory available for the PHP process, in Megabytes. The default is 128, which is fine for most PHP applications. Some of the more complex ones might need more.
-
display_errors = Off - This directive tells PHP whether to include any error messages in the stream that it returns to the Web server. If this is set to "On", then PHP will send whichever classes of errors that you define with the error_reporting directive back to web server as part of the error stream. For security reasons it is recommended to set it to "Off" on production servers in order not to reveal any security sensitive information that is often included in the error messages.
-
open_basedir = <paths to directories, separated by semicolon>, e.g. openbasedir="C:\inetpub\wwwroot;C:\inetpub\temp". This directive specified the directory paths where PHP is allowed to perform file system operations. Any file operation outside of the specified paths will result in an error. This directive is especially useful for locking down the PHP installation in shared hosting environments to prevent PHP scripts from accessing any files outside of the web site's root directory.
-
upload_max_filesize = ###M and post_max_size = ###M - The maximum allowed size of an uploaded file and post data respectively. The values of these directives should be increased if PHP applications need to perform large uploads, such as for example photos or video files.
PHP is now setup on your system. The next step is to choose a web server, and enable it to run PHP. Choose a web server from the table of contents.
In addition to running PHP via a web server, PHP can run from the command line just like a .BAT script. See Command Line PHP on Microsoft Windows for further details.
Microsoft IIS
This section contains PHP installation instructions specific to Microsoft Internet Information Services (IIS).
Microsoft IIS 5.1 and IIS 6.0
This section contains instructions for manually setting up Internet Information Services (IIS) 5.1 and IIS 6.0 to work with PHP on Microsoft Windows XP and Windows Server 2003. For instructions on setting up IIS 7.0 and later versions on Windows Vista, Windows Server 2008, Windows 7 and Windows Server 2008 R2 refer to Microsoft IIS 7.0 and later.
Configuring IIS to process PHP requests
Download and install PHP in accordance to the instructions described in manual installation steps
Informacja:
Non-thread-safe build of PHP is recommended when using IIS. The non-thread-safe builds are available at » PHP for Windows: Binaries and Sources Releases.
Configure the CGI- and FastCGI-specific settings in php.ini file as shown below:
Przykład #1 CGI and FastCGI settings in php.ini
fastcgi.impersonate = 1 fastcgi.logging = 0 cgi.fix_pathinfo=1 cgi.force_redirect = 0
Download and install the » Microsoft FastCGI Extension for IIS 5.1 and 6.0. The extension is available for 32-bit and 64-bit platforms - select the right download package for your platform.
Configure the FastCGI extension to handle PHP-specific requests by running the command shown below. Replace the value of the "-path" parameter with the absolute file path to the php-cgi.exe file.
Przykład #2 Configuring FastCGI extension to handle PHP requests
cscript %windir%\system32\inetsrv\fcgiconfig.js -add -section:"PHP" ^ -extension:php -path:"C:\PHP\php-cgi.exe"
This command will create an IIS script mapping for *.php file extension, which will result in all URLs that end with .php being handled by FastCGI extension. Also, it will configure FastCGI extension to use the executable php-cgi.exe to process the PHP requests.
Informacja:
At this point the required installation and configuration steps are completed. The remaining instructions below are optional but highly recommended for achieving optimal functionality and performance of PHP on IIS.
Impersonation and file system access
It is recommended to enable FastCGI impersonation in PHP when using IIS. This is controlled by the fastcgi.impersonate directive in php.ini file. When impersonation is enabled, PHP will perform all the file system operations on behalf of the user account that has been determined by IIS authentication. This ensures that even if the same PHP process is shared across different IIS web sites, the PHP scripts in those web sites will not be able to access each others' files as long as different user accounts are used for IIS authentication on each web site.
For example IIS 5.1 and IIS 6.0, in its default configuration, has anonymous authentication enabled with built-in user account IUSR_<MACHINE_NAME> used as a default identity. This means that in order for IIS to execute PHP scripts, it is necessary to grant IUSR_<MACHINE_NAME> account read permission on those scripts. If PHP applications need to perform write operations on certain files or write files into some folders then IUSR_<MACHINE_NAME> account should have write permission to those.
To determine which user account is used by IIS anonymous authentication, follow these steps:
-
In the Windows Start Menu choose "Run:", type "inetmgr" and click "Ok";
-
Expand the list of web sites under the "Web Sites" node in the tree view, right-click on a web site that is being used and select "Properties";
-
Click the "Directory Security" tab;
-
Take note of a "User name:" field in the "Authentication Methods" dialog
To modify the permissions settings on files and folders, use the Windows Explorer user interface or icacls command.
Przykład #3 Configuring file access permissions
icacls C:\inetpub\wwwroot\upload /grant IUSR:(OI)(CI)(M)
Set index.php as a default document in IIS
The IIS default documents are used for HTTP requests that do not specify a document name. With PHP applications, index.php usually acts as a default document. To add index.php to the list of IIS default documents, follow these steps:
-
In the Windows Start Menu choose "Run:", type "inetmgr" and click "Ok";
-
Right-click on the "Web Sites" node in the tree view and select "Properties";
-
Click the "Documents" tab;
-
Click the "Add..." button and enter "index.php" for the "Default content page:".
FastCGI and PHP Recycling configuration
Configure IIS FastCGI extension settings for recycling of PHP processes by using the commands shown below. The FastCGI setting instanceMaxRequests controls how many requests will be processed by a single php-cgi.exe process before FastCGI extension shuts it down. The PHP environment variable PHP_FCGI_MAX_REQUESTS controls how many requests a single php-cgi.exe process will handle before it recycles itself. Make sure that the value specified for FastCGI InstanceMaxRequests setting is less than or equal to the value specified for PHP_FCGI_MAX_REQUESTS.
Przykład #4 Configuring FastCGI and PHP recycling
cscript %windir%\system32\inetsrv\fcgiconfig.js -set -section:"PHP" ^ -InstanceMaxRequests:10000 cscript %windir%\system32\inetsrv\fcgiconfig.js -set -section:"PHP" ^ -EnvironmentVars:PHP_FCGI_MAX_REQUESTS:10000
Configuring FastCGI timeout settings
Increase the timeout settings for FastCGI extension if there are applications that have long running PHP scripts. The two settings that control timeouts are ActivityTimeout and RequestTimeout. Refer to » Configuring FastCGI Extension for IIS 6.0 for more information about those settings.
Przykład #5 Configuring FastCGI timeout settings
cscript %windir%\system32\inetsrv\fcgiconfig.js -set -section:"PHP" ^ -ActivityTimeout:90 cscript %windir%\system32\inetsrv\fcgiconfig.js -set -section:"PHP" ^ -RequestTimeout:90
Changing the Location of php.ini file
PHP searches for php.ini file in several locations and it is possible to change the default locations of php.ini file by using PHPRC environment variable. To instruct PHP to load the configuration file from a custom location run the command shown below. The absolute path to the directory with php.ini file should be specified as a value of PHPRC environment variable.
Przykład #6 Changing the location of php.ini file
cscript %windir%\system32\inetsrv\fcgiconfig.js -set -section:"PHP" ^ -EnvironmentVars:PHPRC:"C:\Some\Directory\"
Microsoft IIS 7.0 and later
This section contains instructions for manually setting up Internet Information Services (IIS) 7.0 and later to work with PHP on Microsoft Windows Vista SP1, Windows 7, Windows Server 2008 and Windows Server 2008 R2. For instructions on setting up IIS 5.1 and IIS 6.0 on Windows XP and Windows Server 2003 refer to Microsoft IIS 5.1 and IIS 6.0.
Enabling FastCGI support in IIS
FastCGI module is disabled in default installation of IIS. The steps to enable it differ based on the version of Windows being used.
To enable FastCGI support on Windows Vista SP1 and Windows 7:
-
In the Windows Start Menu choose "Run:", type "optionalfeatures.exe" and click "Ok";
-
In the "Windows Features" dialog expand "Internet Information Services", "World Wide Web Services", "Application Development Features" and then enable the "CGI" checkbox;
-
Click OK and wait until the installation is complete.
To enable FastCGI support on Windows Server 2008 and Windows Server 2008 R2:
-
In the Windows Start Menu choose "Run:", type "CompMgmtLauncher" and click "Ok";
-
If the "Web Server (IIS)" role is not present under the "Roles" node, then add it by clicking "Add Roles";
-
If the "Web Server (IIS)" role is present, then click "Add Role Services" and then enable the "CGI" checkbox under "Application Development" group;
-
Click "Next" and then "Install" and wait for the installation to complete.
Configuring IIS to process PHP requests
Download and install PHP in accordance to the instructions described in manual installation steps
Informacja:
Non-thread-safe build of PHP is recommended when using IIS. The non-thread-safe builds are available at » PHP for Windows: Binaries and Sources Releases.
Configure the CGI- and FastCGI-specific settings in php.ini file as shown below:
Przykład #1 CGI and FastCGI settings in php.ini
fastcgi.impersonate = 1 fastcgi.logging = 0 cgi.fix_pathinfo=1 cgi.force_redirect = 0
Configure IIS handler mapping for PHP by using either IIS Manager user interface or a command line tool.
Using IIS Manager user interface to create a handler mapping for PHP
Follow these steps to create an IIS handler mapping for PHP in IIS Manager user interface:
-
In the Windows Start Menu choose "Run:", type "inetmgr" and click "Ok";
-
In the IIS Manager user interface select the server node in the "Connections" tree view;
-
In the "Features View" page open the "Handler Mappings" feature;
-
In the "Actions" pane click "Add Module Mapping...";
-
In the "Add Module Mapping" dialog enter the following:
- Request path: *.php
- Module: FastCgiModule
- Executable: C:\[Path to PHP installation]\php-cgi.exe
- Name: PHP_via_FastCGI
-
Click "Request Restrictions" button and then configure the mapping to invoke handler only if request is mapped to a file or a folder;
-
Click OK on all the dialogs to save the configuration.
Using command line tool to create a handler mapping for PHP
Use the command shown below to create an IIS FastCGI process pool which will use php-cgi.exe executable for processing PHP requests. Replace the value of the fullPath parameter with the absolute file path to the php-cgi.exe file.
Przykład #2 Creating IIS FastCGI process pool
%windir%\system32\inetsrv\appcmd set config /section:system.webServer/fastCGI ^ /+[fullPath='c:\PHP\php-cgi.exe']
Configure IIS to handle PHP specific requests by running the command shown below. Replace the value of the scriptProcessor parameter with the absolute file path to the php-cgi.exe file.
Przykład #3 Creating handler mapping for PHP requests
%windir%\system32\inetsrv\appcmd set config /section:system.webServer/handlers ^ /+[name='PHP_via_FastCGI', path='*.php',verb='*',modules='FastCgiModule',^ scriptProcessor='c:\PHP\php-cgi.exe',resourceType='Either']
This command creates an IIS handler mapping for *.php file extension, which will result in all URLs that end with .php being handled by FastCGI module.
Informacja:
At this point the required installation and configuration steps are completed. The remaining instructions below are optional but highly recommended for achieving optimal functionality and performance of PHP on IIS.
Impersonation and file system access
It is recommended to enable FastCGI impersonation in PHP when using IIS. This is controlled by the fastcgi.impersonate directive in php.ini file. When impersonation is enabled, PHP will perform all the file system operations on behalf of the user account that has been determined by IIS authentication. This ensures that even if the same PHP process is shared across different IIS web sites, the PHP scripts in those web sites will not be able to access each other's files as long as different user accounts are used for IIS authentication on each web site.
For example IIS 7, in its default configuration, has anonymous authentication enabled with built-in user account IUSR used as a default identity. This means that in order for IIS to execute PHP scripts, it is necessary to grant IUSR account read permission on those scripts. If PHP applications need to perform write operations on certain files or write files into some folders then IUSR account should have write permission to those.
To determine what user account is used as an anonymous identity in IIS 7 use the following command. Replace the "Default Web Site" with the name of IIS web site that you use. In the output XML configuration element look for the userName attribute.
Przykład #4 Determining the account used as IIS anonymous identity
%windir%\system32\inetsrv\appcmd.exe list config "Default Web Site" ^
/section:anonymousAuthentication
<system.webServer>
<security>
<authentication>
<anonymousAuthentication enabled="true" userName="IUSR" />
</authentication>
</security>
</system.webServer>
Informacja:
If userName attribute is not present in the anonymousAuthentication element, or is set to an empty string, then it means that the application pool identity is used as an anonymous identity for that web site.
To modify the permissions settings on files and folders, use the Windows Explorer user interface or icacls command.
Przykład #5 Configuring file access permissions
icacls C:\inetpub\wwwroot\upload /grant IUSR:(OI)(CI)(M)
Set index.php as a default document in IIS
The IIS default documents are used for HTTP requests that do not specify a document name. With PHP applications, index.php usually acts as a default document. To add index.php to the list of IIS default documents, use this command:
Przykład #6 Set index.php as a default document in IIS
%windir%\system32\inetsrv\appcmd.exe set config ^ -section:system.webServer/defaultDocument /+"files.[value='index.php']" ^ /commit:apphost
FastCGI and PHP Recycling configuration
Configure IIS FastCGI settings for recycling of PHP processes by using the commands shown below. The FastCGI setting instanceMaxRequests controls how many requests will be processed by a single php-cgi.exe process before IIS shuts it down. The PHP environment variable PHP_FCGI_MAX_REQUESTS controls how many requests a single php-cgi.exe process will handle before it recycles itself. Make sure that the value specified for FastCGI InstanceMaxRequests setting is less than or equal to the value specified for PHP_FCGI_MAX_REQUESTS.
Przykład #7 Configuring FastCGI and PHP recycling
%windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi ^
/[fullPath='c:\php\php-cgi.exe'].instanceMaxRequests:10000
%windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi ^
/+"[fullPath='C:\{php_folder}\php-cgi.exe'].environmentVariables.^
[name='PHP_FCGI_MAX_REQUESTS',value='10000']"
FastCGI timeout settings
Increase the timeout settings for FastCGI if it is expected to have long running PHP scripts. The two settings that control timeouts are activityTimeout and requestTimeout. Use the commands below to change the timeout settings. Make sure to replace the value in the fullPath parameter to contain the absolute path to the php-cgi.exe file.
Przykład #8 Configuring FastCGI timeout settings
%windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi ^ /[fullPath='C:\php\php-cgi.exe',arguments=''].activityTimeout:"90" /commit:apphost %windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi ^ /[fullPath='C:\php\php-cgi.exe',arguments=''].requestTimeout:"90" /commit:apphost
Changing the Location of php.ini file
PHP searches for php.ini file in several locations and it is possible to change the default locations of php.ini file by using PHPRC environment variable. To instruct PHP to load the configuration file from a custom location run the command shown below. The absolute path to the directory with php.ini file should be specified as a value of PHPRC environment variable.
Przykład #9 Changing the location of php.ini file
appcmd.exe set config -section:system.webServer/fastCgi ^ /+"[fullPath='C:\php\php.exe',arguments=''].environmentVariables.^ [name='PHPRC',value='C:\Some\Directory\']" /commit:apphost
Apache 1.3.x on Microsoft Windows
This section contains notes and hints specific to Apache 1.3.x installs of PHP on Microsoft Windows systems. There are also instructions and notes for Apache 2 on a separate page.
Informacja:
Please read the manual installation steps first!
There are two ways to set up PHP to work with Apache 1.3.x on Windows. One is to use the CGI binary (php.exe for PHP 4 and php-cgi.exe for PHP 5), the other is to use the Apache Module DLL. In either case you need to edit your httpd.conf to configure Apache to work with PHP, and then restart the server.
It is worth noting here that now the SAPI module has been made more stable under Windows, we recommend it's use above the CGI binary, since it is more transparent and secure.
Although there can be a few variations of configuring PHP under Apache, these are simple enough to be used by the newcomer. Please consult the Apache Documentation for further configuration directives.
After changing the configuration file, remember to restart the server, for example, NET STOP APACHE followed by NET START APACHE, if you run Apache as a Windows Service, or use your regular shortcuts.
Informacja: Nalezy pamiętać, że podając ścieżki w plikach konfiguracyjnych Apache w systemie Windows, wszystkie znaki backslash takie jak na przykład w ścieżce c:\directory\file.ext powinny być zamienione na znaki slash, na przykład c:/directory/file.ext. Zamykające znaki slash mogą być także niezbędne dla katalogów.
Installing as an Apache module
You should add the following lines to your Apache httpd.conf file:
Przykład #1 PHP as an Apache 1.3.x module
This assumes PHP is installed to c:\php. Adjust the path if this is not the case.
For PHP 4:
# Add to the end of the LoadModule section # Don't forget to copy this file from the sapi directory! LoadModule php4_module "C:/php/php4apache.dll" # Add to the end of the AddModule section AddModule mod_php4.c
For PHP 5:
# Add to the end of the LoadModule section LoadModule php5_module "C:/php/php5apache.dll" # Add to the end of the AddModule section AddModule mod_php5.c
For both:
# Add this line inside the <IfModule mod_mime.c> conditional brace AddType application/x-httpd-php .php # For syntax highlighted .phps files, also add AddType application/x-httpd-php-source .phps
Installing as a CGI binary
If you unzipped the PHP package to C:\php\ as described in the Manual Installation Steps section, you need to insert these lines to your Apache configuration file to set up the CGI binary:
Przykład #2 PHP and Apache 1.3.x as CGI
ScriptAlias /php/ "c:/php/" AddType application/x-httpd-php .php # For PHP 4 Action application/x-httpd-php "/php/php.exe" # For PHP 5 Action application/x-httpd-php "/php/php-cgi.exe" # specify the directory where php.ini is SetEnv PHPRC C:/php
Używając instalacji CGI, serwer jest podatny na wiele potencjalnych ataków. Sposoby obrony przed nimi zostały opisane w rozdziale o bezpieczeństwie instalacji CGI.
If you would like to present PHP source files syntax highlighted, there is no such convenient option as with the module version of PHP. If you chose to configure Apache to use PHP as a CGI binary, you will need to use the highlight_file() function. To do this simply create a PHP script file and add this code: <?php highlight_file('some_php_script.php'); ?>.
Apache 2.x on Microsoft Windows
This section contains notes and hints specific to Apache 2.x installs of PHP on Microsoft Windows systems. We also have instructions and notes for Apache 1.3.x users on a separate page.
Informacja:
You should read the manual installation steps first!
Informacja: Apache 2.2 Support
Users of Apache 2.2 should note that the DLL file for Apache 2.2 is named php5apache2_2.dll rather than php5apache2.dll and is available only for PHP 5.2.0 and later. See also » http://snaps.php.net/
You are strongly encouraged to consult the » Apache Documentation to get a basic understanding of the Apache 2.x Server. Also consider reading the » Windows specific notes for Apache 2.x before reading on here.
Apache 2.x is designed to run on the Windows version designated as server platforms, such as Windows NT 4.0, Windows 2000, Windows XP, or Windows 7. While Apache 2.x works tolerably well on Windows 9x, support on these platforms is incomplete, and some things will not work correctly. There is no plan to remedy this situation.
Download the most recent version of » Apache 2.x and a fitting PHP version. Follow the Manual Installation Steps and come back to go on with the integration of PHP and Apache.
There are three ways to set up PHP to work with Apache 2.x on Windows. You can run PHP as a handler, as a CGI, or under FastCGI.
Informacja: Nalezy pamiętać, że podając ścieżki w plikach konfiguracyjnych Apache w systemie Windows, wszystkie znaki backslash takie jak na przykład w ścieżce c:\directory\file.ext powinny być zamienione na znaki slash, na przykład c:/directory/file.ext. Zamykające znaki slash mogą być także niezbędne dla katalogów.
Installing as an Apache handler
You need to insert the following lines into your Apache httpd.conf configuration file to load the PHP module for Apache 2.x:
Przykład #1 PHP and Apache 2.x as handler
# LoadModule php5_module "c:/php/php5apache2.dll" AddHandler application/x-httpd-php .php # configure the path to php.ini PHPIniDir "C:/php"
Informacja: Remember to substitute your actual path to PHP for the C:/php/ in the above examples. Take care to use either php5apache2.dll or php5apache2_2.dll in your LoadModule directive and verify that the referenced file is in fact located at the file path that you point to in this directive.
The above configuration will enable PHP handling of any file that has a .php extension, even if there are other file extensions. For example, a file named example.php.txt will be executed by the PHP handler. To ensure that only files that end in .php are executed, use the following configuration instead:
<FilesMatch \.php$>
SetHandler application/x-httpd-php
</FilesMatch>
Running PHP as CGI
You should consult the » Apache CGI documentation for a more complete understanding of running CGI on Apache.
To run PHP as CGI, you'll need to place your php-cgi files in a directory designated as a CGI directory using the ScriptAlias directive.
You will then need to insert a #! line in the PHP files, pointing to the location of your PHP binary:
Przykład #2 PHP and Apache 2.x as CGI
#!C:/php/php.exe <?php phpinfo(); ?>
Używając instalacji CGI, serwer jest podatny na wiele potencjalnych ataków. Sposoby obrony przed nimi zostały opisane w rozdziale o bezpieczeństwie instalacji CGI.
Running PHP under FastCGI
Running PHP under FastCGI has a number of advantages over running it as a CGI. Setting it up this way is fairly straightforward:
Obtain mod_fcgid from » http://httpd.apache.org/mod_fcgid/. Win32 binaries are available for download from that site. Install the module according to the instructions that will come with it.
Configure your web server as shown below, taking care to adjust any paths to reflect your how you have installed things on your particular system:
Przykład #3 Configure Apache to run PHP as FastCGI
LoadModule fcgid_module modules/mod_fcgid.so # Where is your php.ini file? FcgidInitialEnv PHPRC "c:/php" AddHandler fcgid-script .php FcgidWrapper "c:/php/php-cgi.exe" .php
Sun, iPlanet and Netscape servers on Microsoft Windows
This section contains notes and hints specific to Sun Java System Web Server, Sun ONE Web Server, iPlanet and Netscape server installs of PHP on Windows.
From PHP 4.3.3 on you can use PHP scripts with the NSAPI module to generate custom directory listings and error pages. Additional functions for Apache compatibility are also available. For support in current web servers read the note about subrequests.
CGI setup on Sun, iPlanet and Netscape servers
To install PHP as a CGI handler, do the following:
- Copy php4ts.dll to your systemroot (the directory where you installed Windows)
-
Make a file association from the command line. Type the following two lines:
assoc .php=PHPScript ftype PHPScript=c:\php\php.exe %1 %*
- In the Netscape Enterprise Administration Server create a dummy shellcgi directory and remove it just after (this step creates 5 important lines in obj.conf and allow the web server to handle shellcgi scripts).
- In the Netscape Enterprise Administration Server create a new mime type (Category: type, Content-Type: magnus-internal/shellcgi, File Suffix:php).
- Do it for each web server instance you want PHP to run
More details about setting up PHP as a CGI executable can be found here: » http://benoit.noss.free.fr/php/install-php.html
NSAPI setup on Sun, iPlanet and Netscape servers
To install PHP with NSAPI, do the following:
- Copy php4ts.dll to your systemroot (the directory where you installed Windows)
-
Make a file association from the command line. Type the following two lines:
assoc .php=PHPScript ftype PHPScript=c:\php\php.exe %1 %*
- In the Netscape Enterprise Administration Server create a new mime type (Category: type, Content-Type: magnus-internal/x-httpd-php, File Suffix: php).
-
Edit magnus.conf (for servers >= 6) or obj.conf (for servers < 6) and add the following: You should place the lines after mime types init.
(PHP >= 4.3.3) The php_ini parameter is optional but with it you can place your php.ini in your web server configuration directory.Init fn="load-modules" funcs="php4_init,php4_execute,php4_auth_trans" shlib="c:/php/sapi/php4nsapi.dll" Init fn="php4_init" LateInit="yes" errorString="Failed to initialise PHP!" [php_ini="c:/path/to/php.ini"]
-
Configure the default object in obj.conf (for virtual server classes [Sun Web Server 6.0+] in their vserver.obj.conf): In the <Object name="default"> section, place this line necessarily after all 'ObjectType' and before all 'AddLog' lines:
(PHP >= 4.3.3) As additional parameters you can add some special php.ini-values, for example you can set a docroot="/path/to/docroot" specific to the context php4_execute is called. For boolean ini-keys please use 0/1 as value, not "On","Off",... (this will not work correctly), e.g. zlib.output_compression=1 instead of zlib.output_compression="On"Service fn="php4_execute" type="magnus-internal/x-httpd-php" [inikey=value inikey=value ...]
-
This is only needed if you want to configure a directory that only consists of PHP scripts (same like a cgi-bin directory):
After that you can configure a directory in the Administration server and assign it the style x-httpd-php. All files in it will get executed as PHP. This is nice to hide PHP usage by renaming files to .html.<Object name="x-httpd-php"> ObjectType fn="force-type" type="magnus-internal/x-httpd-php" Service fn=php4_execute [inikey=value inikey=value ...] </Object>
- Restart your web service and apply changes
- Do it for each web server instance you want PHP to run
Informacja:
More details about setting up PHP as an NSAPI filter can be found here: » http://benoit.noss.free.fr/php/install-php4.html
Informacja:
The stacksize that PHP uses depends on the configuration of the web server. If you get crashes with very large PHP scripts, it is recommended to raise it with the Admin Server (in the section "MAGNUS EDITOR").
CGI environment and recommended modifications in php.ini
Important when writing PHP scripts is the fact that Sun JSWS/Sun ONE WS/iPlanet/Netscape is a multithreaded web server. Because of that all requests are running in the same process space (the space of the web server itself) and this space has only one environment. If you want to get CGI variables like PATH_INFO, HTTP_HOST etc. it is not the correct way to try this in the old PHP way with getenv() or a similar way (register globals to environment, $_ENV). You would only get the environment of the running web server without any valid CGI variables!
Informacja:
Why are there (invalid) CGI variables in the environment?
Answer: This is because you started the web server process from the admin server which runs the startup script of the web server, you wanted to start, as a CGI script (a CGI script inside of the admin server!). This is why the environment of the started web server has some CGI environment variables in it. You can test this by starting the web server not from the administration server. Use the command line as root user and start it manually - you will see there are no CGI-like environment variables.
Simply change your scripts to get CGI variables in the correct way for PHP 4.x by using the superglobal $_SERVER. If you have older scripts which use $HTTP_HOST, etc., you should turn on register_globals in php.ini and change the variable order too (important: remove "E" from it, because you do not need the environment here):
variables_order = "GPCS" register_globals = On
Special use for error pages or self-made directory listings (PHP >= 4.3.3)
You can use PHP to generate the error pages for "404 Not Found" or similar. Add the following line to the object in obj.conf for every error page you want to overwrite:
Error fn="php4_execute" code=XXX script="/path/to/script.php" [inikey=value inikey=value...]
Another possibility is to generate self-made directory listings. Just create a PHP script which displays a directory listing and replace the corresponding default Service line for type="magnus-internal/directory" in obj.conf with the following:
Service fn="php4_execute" type="magnus-internal/directory" script="/path/to/script.php" [inikey=value inikey=value...]
Note about nsapi_virtual() and subrequests (PHP >= 4.3.3)
The NSAPI module now supports the nsapi_virtual() function (alias: virtual()) to make subrequests on the web server and insert the result in the web page. The problem is, that this function uses some undocumented features from the NSAPI library.
Under Unix this is not a problem, because the module automatically looks for the needed functions and uses them if available. If not, nsapi_virtual() is disabled.
Under Windows limitations in the DLL handling need the use of a automatic detection of the most recent ns-httpdXX.dll file. This is tested for servers till version 6.1. If a newer version of the Sun server is used, the detection fails and nsapi_virtual() is disabled.
If this is the case, try the following: Add the following parameter to php4_init in magnus.conf/obj.conf:
Init fn=php4_init ... server_lib="ns-httpdXX.dll"
You can check the status by using the phpinfo() function.
Informacja:
But be warned: Support for nsapi_virtual() is EXPERIMENTAL!!!
Sambar Server on Microsoft Windows
This section contains notes and hints specific to the » Sambar Server for Windows.
Informacja:
You should read the manual installation steps first!
This list describes how to set up the ISAPI module to work with the Sambar server on Windows.
-
Find the file called mappings.ini (in the config directory) in the Sambar install directory.
-
Open mappings.ini and add the following line under [ISAPI]:
(This line assumes that PHP was installed in c:\php.)Przykład #1 ISAPI configuration of Sambar
#for PHP 4 *.php = c:\php\php4isapi.dll #for PHP 5 *.php = c:\php\php5isapi.dll
-
Now restart the Sambar server for the changes to take effect.
Informacja:
If you intend to use PHP to communicate with resources which are held on a different computer on your network, then you will need to alter the account used by the Sambar Server Service. The default account used for the Sambar Server Service is LocalSystem which will not have access to remote resources. The account can be amended by using the Services option from within the Windows Control Panel Administation Tools.
Xitami on Microsoft Windows
This section contains notes and hints specific to » Xitami on Windows.
Informacja:
You should read the manual installation steps first!
This list describes how to set up the PHP CGI binary to work with Xitami on Windows.
Informacja: Important for CGI users
Read the faq on cgi.force_redirect for important details. This directive needs to be set to 0. If you want to use $_SERVER['PHP_SELF'] you have to enable the cgi.fix_pathinfo directive.
Używając instalacji CGI, serwer jest podatny na wiele potencjalnych ataków. Sposoby obrony przed nimi zostały opisane w rozdziale o bezpieczeństwie instalacji CGI.
-
Make sure the web server is running, and point your browser to xitamis admin console (usually http://127.0.0.1/admin), and click on Configuration.
-
Navigate to the Filters, and put the extension which PHP should parse (i.e. .php) into the field File extensions (.xxx).
-
In Filter command or script put the path and name of your PHP CGI executable i.e. C:\php\php.exe for PHP 4, or C:\php\php-cgi.exe for PHP 5.
-
Press the 'Save' icon.
-
Restart the server to reflect changes.
Building from source
This chapter teaches how to compile PHP from sources on windows, using Microsoft's tools. To compile PHP with cygwin, please refer to Installation on Unix systems.
See the Wiki documentation at: » http://wiki.php.net/internals/windows/stepbystepbuild
Installation of extensions on Windows
After installing PHP and a web server on Windows, you will probably want to install some extensions for added functionality. You can choose which extensions you would like to load when PHP starts by modifying your php.ini. You can also load a module dynamically in your script using dl().
The DLLs for PHP extensions are prefixed with php_.
Many extensions are built into the Windows version of PHP. This means additional DLL files, and the extension directive, are not used to load these extensions. The Windows PHP Extensions table lists extensions that require, or used to require, additional PHP DLL files. Here's a list of built in extensions:
In PHP 4 (updated PHP 4.3.11): BCMath, Caledar, COM, Ctype, FTP, MySQL, ODBC, Overload, PCRE, Session, Tokenizer, WDDX, XML i Zlib
In PHP 5 (updated PHP 5.0.4), the following changes exist. Built in: DOM, LibXML, Iconv, SimpleXML, SPL i SQLite. And the following are no longer built in: MySQL and Overload.
The default location PHP searches for extensions is C:\php4\extensions in PHP 4 and C:\php5 in PHP 5. To change this setting to reflect your setup of PHP edit your php.ini file:
-
You will need to change the extension_dir setting to point to the directory where your extensions lives, or where you have placed your php_*.dll files. For example:
extension_dir = C:\php\extensions
-
Enable the extension(s) in php.ini you want to use by uncommenting the extension=php_*.dll lines in php.ini. This is done by deleting the leading ; from the extension you want to load.
Przykład #1 Enable Bzip2 extension for PHP-Windows
// change the following line from ... ;extension=php_bz2.dll // ... to extension=php_bz2.dll
-
Some of the extensions need extra DLLs to work. Couple of them can be found in the distribution package, in the C:\php\dlls\ folder in PHP 4 or in the main folder in PHP 5, but some, for example Oracle (php_oci8.dll) require DLLs which are not bundled with the distribution package. If you are installing PHP 4, copy the bundled DLLs from C:\php\dlls folder to the main C:\php folder. Don't forget to include C:\php in the system PATH (this process is explained in a separate FAQ entry).
-
Some of these DLLs are not bundled with the PHP distribution. See each extensions documentation page for details. Also, read the manual section titled Installation of PECL extensions for details on PECL. An increasingly large number of PHP extensions are found in PECL, and these extensions require a separate download.
Informacja: If you are running a server module version of PHP remember to restart your web server to reflect your changes to php.ini.
The following table describes some of the extensions available and required additional dlls.
| Extension | Description | Notes |
|---|---|---|
| php_bz2.dll | bzip2 compression functions | None |
| php_calendar.dll | Calendar conversion functions | Built in since PHP 4.0.3 |
| php_crack.dll | Crack functions | None |
| php_ctype.dll | ctype family functions | Built in since PHP 4.3.0 |
| php_curl.dll | CURL, Client URL library functions | Requires: libeay32.dll, ssleay32.dll (bundled) |
| php_dba.dll | DBA: DataBase (dbm-style) Abstraction layer functions | None |
| php_dbase.dll | dBase functions | None |
| php_dbx.dll | dbx functions | |
| php_domxml.dll | DOM XML functions | PHP <= 4.2.0 requires: libxml2.dll (bundled) PHP >= 4.3.0 requires: iconv.dll (bundled) |
| php_dotnet.dll | .NET functions | PHP <= 4.1.1 |
| php_exif.dll | EXIF functions | php_mbstring.dll. And, php_exif.dll must be loaded after php_mbstring.dll in php.ini. |
| php_fbsql.dll | FrontBase functions | PHP <= 4.2.0 |
| php_fdf.dll | FDF: Forms Data Format functions. | Requires: fdftk.dll (bundled) |
| php_filepro.dll | filePro functions | Read-only access |
| php_ftp.dll | FTP functions | Built-in since PHP 4.0.3 |
| php_gd.dll | GD library image functions | Removed in PHP 4.3.2. Also note that truecolor functions are not available in GD1, instead, use php_gd2.dll. |
| php_gd2.dll | GD library image functions | GD2 |
| php_gettext.dll | Gettext functions | PHP <= 4.2.0 requires gnu_gettext.dll (bundled), PHP >= 4.2.3 requires libintl-1.dll, iconv.dll (bundled). |
| php_hyperwave.dll | HyperWave functions | None |
| php_iconv.dll | ICONV characterset conversion | Requires: iconv-1.3.dll (bundled), PHP >=4.2.1 iconv.dll |
| php_ifx.dll | Informix functions | Requires: Informix libraries |
| php_iisfunc.dll | IIS management functions | None |
| php_imap.dll | IMAP POP3 and NNTP functions | None |
| php_ingres.dll | Ingres functions | Requires: Ingres libraries |
| php_interbase.dll | InterBase functions | Requires: gds32.dll (bundled) |
| php_java.dll | Java functions | PHP <= 4.0.6 requires: jvm.dll (bundled) |
| php_ldap.dll | LDAP functions | PHP <= 4.2.0 requires libsasl.dll (bundled), PHP >= 4.3.0 requires libeay32.dll, ssleay32.dll (bundled) |
| php_mbstring.dll | Multi-Byte String functions | None |
| php_mcrypt.dll | Mcrypt Encryption functions | Requires: libmcrypt.dll |
| php_mhash.dll | Mhash functions | PHP >= 4.3.0 requires: libmhash.dll (bundled) |
| php_mime_magic.dll | Mimetype functions | Requires: magic.mime (bundled) |
| php_ming.dll | Ming functions for Flash | None |
| php_msql.dll | mSQL functions | Requires: msql.dll (bundled) |
| php_mssql.dll | MSSQL functions | Requires: ntwdblib.dll (bundled) |
| php_mysql.dll | MySQL functions | PHP >= 5.0.0, requires libmysql.dll (bundled) |
| php_mysqli.dll | MySQLi functions | PHP >= 5.0.0, requires libmysql.dll (libmysqli.dll in PHP <= 5.0.2) (bundled) |
| php_oci8.dll | Oracle 8 functions | Requires: Oracle 8.1+ client libraries |
| php_openssl.dll | OpenSSL functions | Requires: libeay32.dll (bundled) |
| php_overload.dll | Object overloading functions | Built in since PHP 4.3.0 |
| php_pdf.dll | PDF functions | None |
| php_pgsql.dll | PostgreSQL functions | None |
| php_printer.dll | Printer functions | None |
| php_shmop.dll | Shared Memory functions | None |
| php_snmp.dll | SNMP get and walk functions | NT only! |
| php_soap.dll | SOAP functions | PHP >= 5.0.0 |
| php_sockets.dll | Socket functions | None |
| php_sybase_ct.dll | Sybase functions | Requires: Sybase client libraries |
| php_tidy.dll | Tidy functions | PHP >= 5.0.0 |
| php_tokenizer.dll | Tokenizer functions | Built in since PHP 4.3.0 |
| php_w32api.dll | W32api functions | None |
| php_xmlrpc.dll | XML-RPC functions | PHP >= 4.2.1 requires: iconv.dll (bundled) |
| php_xslt.dll | XSLT functions | PHP <= 4.2.0 requires sablot.dll, expat.dll (bundled). PHP >= 4.2.1 requires sablot.dll, expat.dll, iconv.dll (bundled). |
| php_yaz.dll | YAZ functions | Requires: yaz.dll (bundled) |
| php_zip.dll | Zip File functions | Read only access |
| php_zlib.dll | ZLib compression functions | Built in since PHP 4.3.0 |
Command Line PHP on Microsoft Windows
This section contains notes and hints specific to getting PHP running from the command line for Windows.
Informacja:
You should read the manual installation steps first!
Getting PHP to run from the command line can be performed without making any changes to Windows.
C:\PHP5\php.exe -f "C:\PHP Scripts\script.php" -- -arg1 -arg2 -arg3
But there are some easy steps that can be followed to make this simpler. Some of these steps should already have been taken, but are repeated here to be able to provide a complete step-by-step sequence.
-
Add the location of the PHP executable (php.exe, php-win.exe or php-cli.exe depending upon your PHP version and display preferences) to the PATH environment variable. Read more about how to add your PHP directory to PATH in the corresponding FAQ entry.
-
Add the .PHP extension to the PATHEXT environment variable. This can be done at the same time as amending the PATH environment variable. Follow the same steps as described in the FAQ but amend the PATHEXT environment variable rather than the PATH environment variable.
Informacja:
The position in which you place the .PHP will determine which script or program is executed when there are matching filenames. For example, placing .PHP before .BAT will cause your script to run, rather than the batch file, if there is a batch file with the same name.
-
Associate the .PHP extension with a file type. This is done by running the following command:
assoc .php=phpfile
-
Associate the phpfile file type with the appropriate PHP executable. This is done by running the following command:
ftype phpfile="C:\PHP5\php.exe" -f "%1" -- %~2
Following these steps will allow PHP scripts to be run from any directory without the need to type the PHP executable or the .PHP extension and all parameters will be supplied to the script for processing.
The example below details some of the registry changes that can be made manually.
Przykład #1 Registry changes
Windows Registry Editor Version 5.00 [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\.php] @="phpfile" "Content Type"="application/php" [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile] @="PHP Script" "EditFlags"=dword:00000000 "BrowserFlags"=dword:00000008 "AlwaysShowExt"="" [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\DefaultIcon] @="C:\\PHP5\\php-win.exe,0" [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell] @="Open" [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell\Open] @="&Open" [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell\Open\command] @="\"C:\\PHP5\\php.exe\" -f \"%1\" -- %~2"
With these changes the same command can be written as:
"C:\PHP Scripts\script" -arg1 -arg2 -arg3
script -arg1 -arg2 -arg3
Informacja:
There is a small problem if you intend to use this technique and use your PHP scripts as a command line filter, like the example below:
ordir | "C:\PHP Scripts\script" -arg1 -arg2 -arg3You may find that the script simply hangs and nothing is output. To get this operational, you need to make another registry change.dir | script -arg1 -arg2 -arg3Further information regarding this issue can be found in this » Microsoft Knowledgebase Article : 321788.Windows Registry Editor Version 5.00 [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\policies\Explorer] "InheritConsoleHandles"=dword:00000001
Installation on Cloud Computing platforms
Spis treści
PHP installs on the cloud. To the PHP cloud!
FastCGI Process Manager (FPM)
Spis treści
FPM (FastCGI Process Manager) is an alternative PHP FastCGI implementation with some additional features (mostly) useful for heavy-loaded sites.
These features include:
-
advanced process management with graceful stop/start;
-
ability to start workers with different uid/gid/chroot/environment, listening on different ports and using different php.ini (replaces safe_mode);
-
stdout and stderr logging;
-
emergency restart in case of accidental opcode cache destruction;
-
accelerated upload support;
-
"slowlog" - logging scripts (not just their names, but their PHP backtraces too, using ptrace and similar things to read remote process' execute_data) that are executed unusually slow;
-
fastcgi_finish_request() - special function to finish request and flush all data while continuing to do something time-consuming (video converting, stats processing etc.);
-
dynamic/static child spawning;
-
basic SAPI status info (similar to Apache mod_status);
-
php.ini-based config file.
Installation
Compiling from sources
In order to enable FPM in your PHP build you need to add --enable-fpm to your configure line.
There are several other FPM-specific configure options (all of them optional):
-
--with-fpm-user - set FPM user (default - nobody).
-
--with-fpm-group - set FPM group (default - nobody).
Configuration
FPM uses php.ini syntax for its configuration file - php-fpm.conf.
List of global php-fpm.conf directives
-
pidstring -
Path to PID file. Default value: none.
-
error_logstring -
Path to error log file. Default value: #INSTALL_PREFIX#/log/php-fpm.log.
-
log_levelstring -
Error log level. Possible values: alert, error, warning, notice, debug. Default value: notice.
-
emergency_restart_thresholdint -
If this number of child processes exit with SIGSEGV or SIGBUS within the time interval set by emergency_restart_interval then FPM will restart. A value of 0 means 'Off'. Default value: 0 (Off).
-
emergency_restart_intervalmixed -
Interval of time used by emergency_restart_interval to determine when a graceful restart will be initiated. This can be useful to work around accidental corruptions in an accelerator's shared memory. Available Units: s(econds), m(inutes), h(ours), or d(ays). Default Unit: seconds. Default value: 0 (Off).
-
process_control_timeoutmixed -
Time limit for child processes to wait for a reaction on signals from master. Available units: s(econds), m(inutes), h(ours), or d(ays) Default Unit: seconds. Default value: 0.
-
daemonizeboolean -
Send FPM to background. Set to 'no' to keep FPM in foreground for debugging. Default value: yes.
List of pool directives
With FPM you can run several pools of processes with different setting. These are settings that can be tweaked per pool.
-
listenstring -
The address on which to accept FastCGI requests. Valid syntaxes are: 'ip.add.re.ss:port', 'port', '/path/to/unix/socket'. This option is mandatory for each pool.
-
listen.backlogint -
Set listen(2) backlog. A value of '-1' means unlimited. Default value: -1.
-
listen.allowed_clientsstring -
List of ipv4 addresses of FastCGI clients which are allowed to connect. Equivalent to the FCGI_WEB_SERVER_ADDRS environment variable in the original PHP FastCGI (5.2.2+). Makes sense only with a tcp listening socket. Each address must be separated by a comma. If this value is left blank, connections will be accepted from any ip address. Default value: any.
-
listen.ownerstring -
Set permissions for unix socket, if one is used. In Linux, read/write permissions must be set in order to allow connections from a web server. Many BSD-derived systems allow connections regardless of permissions. Default values: user and group are set as the running user, mode is set to 0666.
-
listen.groupstring -
See listen.owner.
-
listen.modestring -
See listen.owner.
-
userstring -
Unix user of FPM processes. This option is mandatory.
-
groupstring -
Unix group of FPM processes. If not set, the default user's group is used.
-
pmstring -
Choose how the process manager will control the number of child processes. Possible values: static, ondemand, dynamic. This option is mandatory.
static - the number of child processes is fixed (pm.max_children).
ondemand - the processes spawn on demand (when requested, as opposed to dynamic, where pm.start_servers are started when the service is started.
dynamic - the number of child processes is set dynamically based on the following directives: pm.max_children, pm.start_servers, pm.min_spare_servers, pm.max_spare_servers.
-
pm.max_childrenint -
The number of child processes to be created when pm is set to static and the maximum number of child processes to be created when pm is set to dynamic. This option is mandatory.
This option sets the limit on the number of simultaneous requests that will be served. Equivalent to the ApacheMaxClients directive with mpm_prefork and to the PHP_FCGI_CHILDREN environment variable in the original PHP FastCGI.
-
pm.start_serversin -
The number of child processes created on startup. Used only when pm is set to dynamic. Default Value: min_spare_servers + (max_spare_servers - min_spare_servers) / 2.
-
pm.min_spare_serversint -
The desired minimum number of idle server processes. Used only when pm is set to dynamic. Also mandatory in this case.
-
pm.max_spare_serversint -
The desired maximum number of idle server processes. Used only when pm is set to dynamic. Also mandatory in this case.
-
pm.max_requestsint -
The number of requests each child process should execute before respawning. This can be useful to work around memory leaks in 3rd party libraries. For endless request processing specify '0'. Equivalent to PHP_FCGI_MAX_REQUESTS. Default value: 0.
-
pm.status_pathstring -
The URI to view the FPM status page. If this value is not set, no URI will be recognized as a status page. Default value: none.
-
ping.pathstring -
The ping URI to call the monitoring page of FPM. If this value is not set, no URI will be recognized as a ping page. This could be used to test from outside that FPM is alive and responding. Please note that the value must start with a leading slash (/).
-
ping.responsestring -
This directive may be used to customize the response to a ping request. The response is formatted as text/plain with a 200 response code. Default value: pong.
-
request_terminate_timeoutmixed -
The timeout for serving a single request after which the worker process will be killed. This option should be used when the 'max_execution_time' ini option does not stop script execution for some reason. A value of '0' means 'Off'. Available units: s(econds)(default), m(inutes), h(ours), or d(ays). Default value: 0.
-
request_slowlog_timeoutmixed -
The timeout for serving a single request after which a PHP backtrace will be dumped to the 'slowlog' file. A value of '0' means 'Off'. Available units: s(econds)(default), m(inutes), h(ours), or d(ays). Default value: 0.
-
slowlogstring -
The log file for slow requests. Default value: #INSTALL_PREFIX#/log/php-fpm.log.slow.
-
rlimit_filesint -
Set open file descriptor rlimit. Default value: system defined value.
-
rlimit_coreint -
Set max core size rlimit. Possible Values: 'unlimited' or an integer greater or equal to 0. Default value: system defined value.
-
chrootstring -
Chroot to this directory at the start. This value must be defined as an absolute path. When this value is not set, chroot is not used.
-
chdirstring -
Chdir to this directory at the start. This value must be an absolute path. Default value: current directory or / when chroot.
-
catch_workers_outputboolean -
Redirect worker stdout and stderr into main error log. If not set, stdout and stderr will be redirected to /dev/null according to FastCGI specs. Default value: no.
It's possible to pass additional environment variables and update PHP settings of a ceratian pool. To do this, you need to add the following options to php-fpm.conf
Przykład #1 Passing environment variables and PHP settings to a pool
env[HOSTNAME] = $HOSTNAME
env[PATH] = /usr/local/bin:/usr/bin:/bin
env[TMP] = /tmp
env[TMPDIR] = /tmp
env[TEMP] = /tmp
php_admin_value[sendmail_path] = /usr/sbin/sendmail -t -i -f www@my.domain.com
php_flag[display_errors] = off
php_admin_value[error_log] = /var/log/fpm-php.www.log
php_admin_flag[log_errors] = on
php_admin_value[memory_limit] = 32M
Settings defined with php_admin_value and php_admin_flag cannot be overriden with ini_set().
Installation of PECL extensions
Spis treści
- Introduction to PECL Installations
- Downloading PECL extensions
- Installing a PHP extension on Windows
- Compiling shared PECL extensions with the pecl command
- Compiling shared PECL extensions with phpize
- php-config
- Compiling PECL extensions statically into PHP
Introduction to PECL Installations
» PECL is a repository of PHP extensions that are made available to you via the » PEAR packaging system. This section of the manual is intended to demonstrate how to obtain and install PECL extensions.
These instructions assume /your/phpsrcdir/ is the path to the PHP source distribution, and that extname is the name of the PECL extension. Adjust accordingly. These instructions also assume a familiarity with the » pear command. The information in the PEAR manual for the pear command also applies to the pecl command.
To be useful, a shared extension must be built, installed, and loaded. The methods described below provide you with various instructions on how to build and install the extensions, but they do not automatically load them. Extensions can be loaded by adding an extension directive. To this php.ini file, or through the use of the dl() function.
When building PHP modules, it's important to have known-good versions of the required tools (autoconf, automake, libtool, etc.) See the » Anonymous SVN Instructions for details on the required tools, and required versions.
Downloading PECL extensions
There are several options for downloading PECL extensions, such as:
- The pecl install extname command downloads the extensions code automatically, so in this case there is no need for a separate download.
- » http://pecl.php.net/ The PECL web site contains information about the different extensions that are offered by the PHP Development Team. The information available here includes: ChangeLog, release notes, requirements and other similar details.
- pecl download extname PECL extensions that have releases listed on the PECL web site are available for download and installation using the » pecl command. Specific revisions may also be specified.
-
SVN
Most PECL extensions also reside in SVN. A web-based view may
be seen at » http://svn.php.net/viewvc/pecl/.
To download straight from SVN, the following
sequence of commands may be used:
$ svn checkout http://svn.php.net/repository/pecl/extname/trunk extname
- Windows downloads At this time the PHP project does not compile Windows binaries for PECL extensions. However, to compile PHP under Windows see the chapter titled building PHP for Windows.
Installing a PHP extension on Windows
On Windows, you have two ways to load a PHP extension: either compile it into PHP, or load the DLL. Loading a pre-compiled extension is the easiest and preferred way.
To load an extension, you need to have it available as a ".dll" file on your system. All the extensions are automatically and periodically compiled by the PHP Group (see next section for the download).
To compile an extension into PHP, please refer to building from source documentation.
To compile a standalone extension (aka a DLL file), please refer to building from source documentation. If the DLL file is available neither with your PHP distribution nor in PECL, you may have to compile it before you can start using the extension.
Where to find an extension?
PHP extensions are usually called "php_*.dll" (where the star represents the name of the extension) and they are located under the "PHP\ext" ("PHP\extensions" in PHP 4) folder.
PHP ships with the extensions most useful to the majority of developers. They are called "core" extensions.
However, if you need functionality not provided by any core extension, you may still be able to find one in PECL. The PHP Extension Community Library (PECL) is a repository for PHP Extensions, providing a directory of all known extensions and hosting facilities for downloading and development of PHP extensions.
If you have developed an extension for your own uses, you might want to think about hosting it on PECL so that others with the same needs can benefit from your time. A nice side effect is that you give them a good chance to give you feedback, (hopefully) thanks, bug reports and even fixes/patches. Before you submit your extension for hosting on PECL, please read http://pecl.php.net/package-new.php.
Which extension to download?
Many times, you will find several versions of each DLL:
- Different version numbers (at least the first two numbers should match)
- Different thread safety settings
- Different processor architecture (x86, x64, ...)
- Different debugging settings
- etc.
You should keep in mind that your extension settings should match all the settings of the PHP executable you are using. The following PHP script will tell you all about your PHP settings:
Przykład #1 phpinfo() call
<?php
phpinfo();
?>
Or from the command line, run:
drive:\\path\to\php\executable\php.exe -i
Loading an extension
The most common way to load a PHP extension is to include it in your php.ini configuration file. Please note that many extensions are already present in your php.ini and that you only need to remove the semicolon to activate them.
;extension=php_extname.dll
extension=php_extname.dll
However, some web servers are confusing because they do not use the php.ini located alongside your PHP executable. To find out where your actual php.ini resides, look for its path in phpinfo():
Configuration File (php.ini) Path C:\WINDOWS
Loaded Configuration File C:\Program Files\PHP\5.2\php.ini
After activating an extension, save php.ini, restart the web server and check phpinfo() again. The new extension should now have its own section.
Resolving problems
If the extension does not appear in phpinfo(), you should check your logs to learn where the problem comes from.
If you are using PHP from the command line (CLI), the extension loading error can be read directly on screen.
If you are using PHP with a web server, the location and format of the logs vary depending on your software. Please read your web server documentation to locate the logs, as it does not have anything to do with PHP itself.
Common problems are the location of the DLL, the value of the " extension_dir" setting inside php.ini and compile-time setting mismatches.
If the problem lies in a compile-time setting mismatch, you probably didn't download the right DLL. Try downloading again the extension with the right settings. Again, phpinfo() can be of great help.
Compiling shared PECL extensions with the pecl command
PECL makes it easy to create shared PHP extensions. Using the » pecl command, do the following:
$ pecl install extname
This will download the source for extname, compile, and install extname.so into your extension_dir. extname.so may then be loaded via php.ini
By default, the pecl command will not install packages that are marked with the alpha or beta state. If no stable packages are available, you may install a beta package using the following command:
$ pecl install extname-beta
You may also install a specific version using this variant:
$ pecl install extname-0.1
Informacja:
After enabling the extension in php.ini, restarting the web service is required for the changes to be picked up.
Compiling shared PECL extensions with phpize
Sometimes, using the pecl installer is not an option. This could be because you're behind a firewall, or it could be because the extension you want to install is not available as a PECL compatible package, such as unreleased extensions from SVN. If you need to build such an extension, you can use the lower-level build tools to perform the build manually.
The phpize command is used to prepare the build environment for a PHP extension. In the following sample, the sources for an extension are in a directory named extname:
$ cd extname $ phpize $ ./configure $ make # make install
A successful install will have created extname.so and put it into the PHP extensions directory. You'll need to and adjust php.ini and add an extension=extname.so line before you can use the extension.
If the system is missing the phpize command, and precompiled packages (like RPM's) are used, be sure to also install the appropriate devel version of the PHP package as they often include the phpize command along with the appropriate header files to build PHP and its extensions.
Execute phpize --help to display additional usage information.
php-config
php-config is a simple shell script for obtaining information about the installed PHP configuration.
When compiling extensions, if you have multiple PHP versions installed, you may specify for which installation you'd like to build by using the --with-php-config option during configuration, specifying the path of the respective php-config script.
The list of command line options provided by the php-config script can be queried anytime by running php-config with the -h switch:
Usage: /usr/local/bin/php-config [OPTION] Options: --prefix [...] --includes [...] --ldflags [...] --libs [...] --extension-dir [...] --include-dir [...] --php-binary [...] --php-sapis [...] --configure-options [...] --version [...] --vernum [...]
| Option | Description |
|---|---|
| --prefix | Directory prefix where PHP is installed, e.g. /usr/local |
| --includes | List of -I options with all include files |
| --ldflags | LD Flags which PHP was compiled with |
| --libs | Extra libraries which PHP was compiled with |
| --extension-dir | Directory where extensions are searched by default |
| --include-dir | Directory prefix where header files are installed by default |
| --php-binary | Full path to php CLI or CGI binary |
| --php-sapis | Show all SAPI modules available |
| --configure-options | Configure options to recreate configuration of current PHP installation |
| --version | PHP version |
| --vernum | PHP version as integer |
Compiling PECL extensions statically into PHP
You might find that you need to build a PECL extension statically into your PHP binary. To do this, you'll need to place the extension source under the php-src/ext/ directory and tell the PHP build system to regenerate its configure script.
$ cd /your/phpsrcdir/ext $ pecl download extname $ gzip -d < extname.tgz | tar -xvf - $ mv extname-x.x.x extname
This will result in the following directory:
/your/phpsrcdir/ext/extname
From here, force PHP to rebuild the configure script, and then build PHP as normal:
$ cd /your/phpsrcdir
$ rm configure
$ ./buildconf --force
$ ./configure --help
$ ./configure --with-extname --enable-someotherext --with-foobar
$ make
$ make install
Informacja: To run the 'buildconf' script you need autoconf 2.13 and automake 1.4+ (newer versions of autoconf may work, but are not supported).
Whether --enable-extname or --with-extname is used depends on the extension. Typically an extension that does not require external libraries uses --enable. To be sure, run the following after buildconf:
$ ./configure --help | grep extname
Problemy?
Spis treści
Przeczytaj FAQ
Niektóre problemy występują częściej niż inne. Tej najczęściej spotykane są wypisane w FAQ PHP, częsci tego podręcznika.
Inne problemy
Jeśli w dalszym ciągu nie wiesz co zrobić, być może ktoś z listy dyskusyjnej poświęconej instalacji PHP będzie mógł ci pomóc. Powinienej sprawdzić najpierw archiwum, bo być może ktoś już odpowiedział na twoje pytanie. Archiwa znajdują się w dziale 'Wspracie' na stronie » http://www.php.net/support.php. Aby zapisać się na listę dyskusyjną dotyczącą instalacji PHP, wyślij pusty list na adres » php-install-subscribe@lists.php.net. Adresem listy dyskusyjnej jest » php-install@lists.php.net.
Jeśli chcesz uzyskać pomoc na liście dyskusyjnej, postaraj się być precyzyjny i podaj niezbędne szczegóły dotyczące Twojego środowiska (system operacyjny, wersja PHP, serwer WWW, czy PHP działa jako CGI czy jako moduł, tryb bezpieczny, itp.), i kod, aby inni mogli odtworzyć i sprawdzić Twój problem.
Raporty o błędach
Jeśli uważasz, że znalazłeś błąd w PHP, zgłoś go. Programiści PHP prawdopodobnie nie wiedzą i nim, więc jeśli go nie zgłosisz, to najprawdopodobniej nie będzie usunięty. Możesz zgłaszać błędy korzystając z systemu zgłaszania błędów znajdującego się pod adresem » http://bugs.php.net/. Nie wysyłaj raportów o błędach na listy dyskusyjne lub bezpośrednio do developerów. System śledzenia błędów ma także opcję zgłaszania pomysłów na nowe możliwości.
Przeczytaj dokument » Jak wysyłać raporty o błędach przed wysłaniem jakiegokolwiek raportu o błędzie!
Runtime Configuration
Spis treści
- The configuration file
- .user.ini files
- Where a configuration setting may be set
- How to change configuration settings
The configuration file
The configuration file (php.ini) is read when PHP starts up. For the server module versions of PHP, this happens only once when the web server is started. For the CGI and CLI versions, it happens on every invocation.
php.ini is searched for in these locations (in order):
- SAPI module specific location (PHPIniDir directive in Apache 2, -c command line option in CGI and CLI, php_ini parameter in NSAPI, PHP_INI_PATH environment variable in THTTPD)
- The PHPRC environment variable. Before PHP 5.2.0, this was checked after the registry key mentioned below.
- As of PHP 5.2.0, the location of the php.ini file can be set for different versions of PHP. The following registry keys are examined in order: [HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y.z], [HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y] and [HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x], where x, y and z mean the PHP major, minor and release versions. If there is a value for IniFilePath in any of these keys, the first one found will be used as the location of the php.ini (Windows only).
- [HKEY_LOCAL_MACHINE\SOFTWARE\PHP], value of IniFilePath (Windows only).
- Current working directory (except CLI).
- The web server's directory (for SAPI modules), or directory of PHP (otherwise in Windows).
- Windows directory (C:\windows or C:\winnt) (for Windows), or --with-config-file-path compile time option.
If php-SAPI.ini exists (where SAPI is the SAPI in use, so, for example, php-cli.ini or php-apache.ini), it is used instead of php.ini. The SAPI name can be determined with php_sapi_name().
Informacja:
The Apache web server changes the directory to root at startup, causing PHP to attempt to read php.ini from the root filesystem if it exists.
The php.ini directives handled by extensions are documented on the respective pages of the extensions themselves. A list of the core directives is available in the appendix. Not all PHP directives are necessarily documented in this manual: for a complete list of directives available in your PHP version, please read your well commented php.ini file. Alternatively, you may find » the latest php.ini from SVN helpful too.
Przykład #1 php.ini example
; any text on a line after an unquoted semicolon (;) is ignored [php] ; section markers (text within square brackets) are also ignored ; Boolean values can be set to either: ; true, on, yes ; or false, off, no, none register_globals = off track_errors = yes ; you can enclose strings in double-quotes include_path = ".:/usr/local/lib/php" ; backslashes are treated the same as any other character include_path = ".;c:\php\lib"
Since PHP 5.1.0, it is possible to refer to existing .ini variables from within .ini files. Example: open_basedir = ${open_basedir} ":/new/dir".
.user.ini files
Since PHP 5.3.0, PHP includes support for .htaccess-style INI files on a per-directory basis. These files are processed only by the CGI/FastCGI SAPI. This functionality obsoletes the PECL htscanner extension. If you are using Apache, use .htaccess files for the same effect.
In addition to the main php.ini file, PHP scans for INI files in each directory, starting with the directory of the requested PHP file, and working its way up to the current document root (as set in $_SERVER['DOCUMENT_ROOT']). In case the PHP file is outside the document root, only its directory is scanned.
Only INI settings with the
modes PHP_INI_PERDIR and
PHP_INI_USER will be recognized in .user.ini-style INI
files.
Two new INI directives, user_ini.filename and user_ini.cache_ttl control the use of user INI files.
user_ini.filename sets the name of the file PHP looks for in each directory; if set to an empty string, PHP doesn't scan at all. The default is .user.ini.
user_ini.cache_ttl controls how often user INI files are re-read. The default is 300 seconds (5 minutes).
Where a configuration setting may be set
These modes determine when and where a PHP directive may or may not be set, and each directive within the manual refers to one of these modes. For example, some settings may be set within a PHP script using ini_set(), whereas others may require php.ini or httpd.conf.
For example, the output_buffering setting is PHP_INI_PERDIR therefore it may not be set using ini_set(). However, the display_errors directive is PHP_INI_ALL therefore it may be set anywhere, including with ini_set().
| Mode | Meaning |
|---|---|
| PHP_INI_USER | Entry can be set in user scripts (like with ini_set()) or in the Windows registry |
| PHP_INI_PERDIR | Entry can be set in php.ini, .htaccess or httpd.conf |
| PHP_INI_SYSTEM | Entry can be set in php.ini or httpd.conf |
| PHP_INI_ALL | Entry can be set anywhere |
How to change configuration settings
Running PHP as an Apache module
When using PHP as an Apache module, you can also change the configuration settings using directives in Apache configuration files (e.g. httpd.conf) and .htaccess files. You will need "AllowOverride Options" or "AllowOverride All" privileges to do so.
There are several Apache directives that allow you
to change the PHP configuration from within the Apache configuration
files. For a listing of which directives are
PHP_INI_ALL, PHP_INI_PERDIR,
or PHP_INI_SYSTEM, have a look at the
List of php.ini directives appendix.
-
php_valuenamevalue -
Sets the value of the specified directive. Can be used only with
PHP_INI_ALLandPHP_INI_PERDIRtype directives. To clear a previously set value use none as the value.Informacja: Don't use
php_valueto set boolean values.php_flag(see below) should be used instead. -
php_flagnameon|off -
Used to set a boolean configuration directive. Can be used only with
PHP_INI_ALLandPHP_INI_PERDIRtype directives. -
php_admin_valuenamevalue -
Sets the value of the specified directive. This can not be used in .htaccess files. Any directive type set with
php_admin_valuecan not be overridden by .htaccess or ini_set(). To clear a previously set value use none as the value. -
php_admin_flagnameon|off -
Used to set a boolean configuration directive. This can not be used in .htaccess files. Any directive type set with
php_admin_flagcan not be overridden by .htaccess or ini_set().
Przykład #1 Apache configuration example
<IfModule mod_php5.c> php_value include_path ".:/usr/local/lib/php" php_admin_flag engine on </IfModule> <IfModule mod_php4.c> php_value include_path ".:/usr/local/lib/php" php_admin_flag engine on </IfModule>
PHP constants do not exist outside of PHP. For example, in
httpd.conf you can not use PHP constants
such as E_ALL or E_NOTICE
to set the error_reporting
directive as they will have no meaning and will evaluate to
0. Use the associated bitmask values instead.
These constants can be used in php.ini
Changing PHP configuration via the Windows registry
When running PHP on Windows, the configuration values can be
modified on a per-directory basis using the Windows registry. The
configuration values are stored in the registry key
HKLM\SOFTWARE\PHP\Per Directory Values,
in the sub-keys corresponding to the path names. For example, configuration
values for the directory c:\inetpub\wwwroot would
be stored in the key HKLM\SOFTWARE\PHP\Per Directory
Values\c\inetpub\wwwroot. The settings for the
directory would be active for any script running from this
directory or any subdirectory of it. The values under the key
should have the name of the PHP configuration directive and the
string value. PHP constants in the values are not parsed.
However, only configuration values changeable in
PHP_INI_USER can be set
this way, PHP_INI_PERDIR values can not.
Other interfaces to PHP
Regardless of how you run PHP, you can change certain values at runtime of your scripts through ini_set(). See the documentation on the ini_set() page for more information.
If you are interested in a complete list of configuration settings on your system with their current values, you can execute the phpinfo() function, and review the resulting page. You can also access the values of individual configuration directives at runtime using ini_get() or get_cfg_var().
- Ogólnie o instalacji
- Installation on Unix systems
- Installation on Mac OS X
- Installation on Windows systems
- Windows Installer (PHP 5.1.0 and earlier)
- Windows Installer (PHP 5.2 and later)
- Manual Installation Steps
- Microsoft IIS
- Microsoft IIS 5.1 and IIS 6.0
- Microsoft IIS 7.0 and later
- Apache 1.3.x on Microsoft Windows
- Apache 2.x on Microsoft Windows
- Sun, iPlanet and Netscape servers on Microsoft Windows
- Sambar Server on Microsoft Windows
- Xitami on Microsoft Windows
- Building from source
- Installation of extensions on Windows
- Command Line PHP on Microsoft Windows
- Installation on Cloud Computing platforms
- FastCGI Process Manager (FPM)
- Installation of PECL extensions
- Problemy?
- Runtime Configuration
Opis języka
Podstawowa składnia
Spis treści
Wyskakiwanie z HTMLa
Kiedy PHP przetwarza plik, szuka otwierających i zamykających znaczników (tagów), które mówią PHP o rozpoczęciu i zakończeniu interpretowania kodu pomiędzy nimi. Przetwarzanie w taki sposób pozwala zagnieżdzać php w dowolnym rodzaju dokumentów, ponieważ wszystko poza parą znaczników, otwierającym i zamykającym jest ignorowane przez parser PHP. Najczęściej zobaczysz php zagnieżdzone w dokumentach HTML, tak jak w tym przykładzie.
<p>To zostanie zignorowane.</p>
<?php echo 'Kiedy to zostanie przetworzone.'; ?>
<p>To również zostanie zignorowane.</p>
Możesz także użyć bardziej zaawansowanej struktury:
Przykład #1 Zaawansowane wyskakiwanie
<?php
if ($wyrazenie) {
?>
<strong>To jest prawda.</strong>
<?php
} else {
?>
<strong>To jest fałsz.</strong>
<?php
}
?>
Mamy cztery różne pary otwierających i zamykających znaczników, które mogą być użyte w php. Dwie z nich, <?php ?> i <script language="php"> </script> są zawsze dostępne. Dwie następne to krótkie znaczniki i znaczniki w stylu ASP, mogą być włączane i wyłączane w pliku konfiguracyjnym php.ini. Część osób postrzega krótkie znaczniki i znaczniki w stylu ASP jako wygodne, jednakże są one mniej przenośne, i zasadniczo nie polecane.
Informacja:
Zauważ również, że jeśli zagnieżdzasz PHP w XML lub XHTML musisz stosować znaczniki <?php ?> aby pozostać w zgodzie ze standardami.
Przykład #2 Znaczniki otwierające i zamykające PHP
1. <?php echo 'jeśli chcesz obsługiwać dokumenty XHTML lub XML, zrób to tak'; ?>
2. <script language="php">
echo 'niektóre edytory (jak FrontPage) nie lubią
instrukcji przetwarzania';
</script>
3. <? echo 'to jest najprostsza instrukcja przetwarzania SGML'; ?>
<?= wyrazenie ?> To jest skrót dla "<? echo wyrazenie ?>"
4. <% echo 'Możesz opcjonalnie użyć znaczników w stylu ASP'; %>
<%= $zmienna; # To jest skrót dla "<% echo . . ." %>
Z pokazanych znaczników, pierwszy i drugi przykład są zawsze dostępne, pierwszy przykład jest najbardziej powszechny i rekomendowany.
Krótkie znaczniki (trzeci przykład) są dostepne jedynie, kiedy są włączone za pomocą dyrektywy konfiguracyjnej short_open_tag w php.ini lub jeśli php zostało skonfigurowane z opcją --enable-short-tags .
Znaczniki w stylu ASP (czwarty przykład) są dostępne jedynie gdy zostaną włączone poprzez dyrektywę konfiguracyjną asp_tags w php.ini
Informacja:
Powinieneś unikać używania krótkich znaczników, kiedy rozwijasz aplikacje lub biblioteki, które są nastawione na rozpowszechnianie lub pracujesz na serwerach PHP, nad którymi nie masz kontroli, ponieważ krótkie znaczniki mogą nie być obsługiwane na docelowym serwerze. Dla przenośnego, rozpowszechnialnego kodu, miej pewność, aby nie użyć krotkich znaczników.
Informacja:
W PHP 5.2 i wcześniejszych, parser nie pozwalał, aby znacznik otwierający <?php był jedynym znakiem w pliku. Dozwolone jest to od PHP 5.3.
Informacja:
Począwszy od PHP 5.4, krótkie znaczniki <?= są zawsze rozpoznawane i ważne, niezależnie od ustawień short_open_tag.
Oddzielanie instrukcji
Podobnie jak C i Perl, PHP wymaga aby instrukcje były zakończone średnikiem, na końcu każdego wyrażenia. Zamykający znacznik bloku kodu PHP automatycznie implikuje średnik; nie musisz mieć średnika zamykającego ostatnią linię z bloku PHP. Zamykający znacznik dla bloku będzie zawierać bezpośrednio następującą nową linie jeśli taka istnieje.
<?php
echo 'To jest test';
?>
<?php echo 'To jest test' ?>
<?php echo 'Pomineliśmy ostatni zamykający znacznik';
Informacja:
Zamykający znacznik bloku PHP na końcu pliku jest opcjonalny, i w niektórych przypadkach pominięcie jego jest pomocne kiedy używamy include() lub require(), tak więc niechciane białe znaki nie będą znajdować się na końcu pliku, i ciągle będzie możliwe dodanie nagłówków do odpowiedzi. To jest także poręczne jeśli używasz buferowania wyjścia, i nie chciałbyś zobaczyć dodanych niechcianych białych znaków na końcu cześci generowanej przez includowany plik.
Komentarze
PHP obsługuje komentarze w stylu 'C', 'C++' i powłoki Unix (styl Perl\'a). Na przykład:
<?php
echo 'To jest test'; // To jest jednoliniowy komentarz w stylu c++
/* To jest wieloliniowy komentarz
jeszcze inna linia komentarza */
echo 'To jest jeszcze jeden test';
echo 'Ostatni test'; # To jest jednoliniowy komentarz w stylu powłoki
?>
"Jednolinijkowy" styl komentarzy obowiązuje jedynie do konca linii lub bieżącego bloku kodu PHP, cokolwiek wystąpi pierwsze. Co oznacza, że kod HTML za // ... ?> lub # ... ?> ZOSTANIE wyświetlony: ?> przerywa tryb PHP i wraca do trybu HTML, i // lub # nie może wpłynąć na to. Jeśli, dyrektywa konfiguracyjna asp_tags jest włączona, to działa tak samo z // %> i # %>. Jednakże, znacznik </script> nie przerywa trybu PHP w jednolinijkowym komentarzu.
<h1>To jest <?php # echo 'prosty';?> przykład</h1>
<p>Nagłowek powyżej będzie mówił 'To jest przykład'.</p>
Komentarze w stylu 'C' kończą się na pierwszym napotkanym */. Upewnij się, że nie zagnieżdzasz komentarzy w stylu 'C'. Łatwo jest popełnić pomyłkę jeśli próbujesz odkomentować duży blok kodu.
<?php
/*
echo 'To jest test'; /* Ten komentarz będzie przyczyną problemów */
*/
?>
Types
Spis treści
- Introduction
- Booleans
- Integers
- Floating point numbers
- Strings
- Arrays
- Objects
- Resources
- NULL
- Callbacks
- Pseudo-types and variables used in this documentation
- Type Juggling
Introduction
PHP supports eight primitive types.
Four scalar types:
Two compound types:
And finally three special types:
This manual also introduces some pseudo-types for readability reasons:
And the pseudo-variable $....
Some references to the type "double" may remain in the manual. Consider double the same as float; the two names exist only for historic reasons.
The type of a variable is not usually set by the programmer; rather, it is decided at runtime by PHP depending on the context in which that variable is used.
Informacja: To check the type and value of an expression, use the var_dump() function.
To get a human-readable representation of a type for debugging, use the gettype() function. To check for a certain type, do not use gettype(), but rather the is_type functions. Some examples:
<?php
$a_bool = TRUE; // a boolean
$a_str = "foo"; // a string
$a_str2 = 'foo'; // a string
$an_int = 12; // an integer
echo gettype($a_bool); // prints out: boolean
echo gettype($a_str); // prints out: string
// If this is an integer, increment it by four
if (is_int($an_int)) {
$an_int += 4;
}
// If $a_bool is a string, print it out
// (does not print out anything)
if (is_string($a_bool)) {
echo "String: $a_bool";
}
?>
To forcibly convert a variable to a certain type, either cast the variable or use the settype() function on it.
Note that a variable may be evaluated with different values in certain situations, depending on what type it is at the time. For more information, see the section on Type Juggling. The type comparison tables may also be useful, as they show examples of various type-related comparisons.
Booleans
This is the simplest type. A boolean expresses a truth value. It
can be either TRUE or FALSE.
Syntax
To specify a boolean literal, use the keywords TRUE or
FALSE. Both are case-insensitive.
<?php
$foo = True; // assign the value TRUE to $foo
?>
Typically, the result of an operator which returns a boolean value is passed on to a control structure.
<?php
// == is an operator which tests
// equality and returns a boolean
if ($action == "show_version") {
echo "The version is 1.23";
}
// this is not necessary...
if ($show_separators == TRUE) {
echo "<hr>\n";
}
// ...because this can be used with exactly the same meaning:
if ($show_separators) {
echo "<hr>\n";
}
?>
Converting to boolean
To explicitly convert a value to boolean, use the (bool) or (boolean) casts. However, in most cases the cast is unnecessary, since a value will be automatically converted if an operator, function or control structure requires a boolean argument.
See also Type Juggling.
When converting to boolean, the following values are considered
FALSE:
-
the boolean
FALSEitself - the integer 0 (zero)
- the float 0.0 (zero)
- the empty string, and the string "0"
- an array with zero elements
- an object with zero member variables (PHP 4 only)
- the special type NULL (including unset variables)
- SimpleXML objects created from empty tags
Every other value is considered TRUE (including any
resource).
-1 is considered TRUE, like any other non-zero
(whether negative or positive) number!
<?php
var_dump((bool) ""); // bool(false)
var_dump((bool) 1); // bool(true)
var_dump((bool) -2); // bool(true)
var_dump((bool) "foo"); // bool(true)
var_dump((bool) 2.3e5); // bool(true)
var_dump((bool) array(12)); // bool(true)
var_dump((bool) array()); // bool(false)
var_dump((bool) "false"); // bool(true)
?>
Integers
An integer is a number of the set ℤ = {..., -2, -1, 0, 1, 2, ...}.
See also:
Syntax
Integers can be specified in decimal (base 10), hexadecimal (base 16), octal (base 8) or binary (base 2) notation, optionally preceded by a sign (- or +).
Binary integer literals are available since PHP 5.4.0.
To use octal notation, precede the number with a 0 (zero). To use hexadecimal notation precede the number with 0x. To use binary notation precede the number with 0b.
Przykład #1 Integer literals
<?php
$a = 1234; // decimal number
$a = -123; // a negative number
$a = 0123; // octal number (equivalent to 83 decimal)
$a = 0x1A; // hexadecimal number (equivalent to 26 decimal)
?>
Formally, the structure for integer literals is:
decimal : [1-9][0-9]*
| 0
hexadecimal : 0[xX][0-9a-fA-F]+
octal : 0[0-7]+
binary : 0b[01]+
integer : [+-]?decimal
| [+-]?hexadecimal
| [+-]?octal
| [+-]?binary
The size of an integer is platform-dependent, although a maximum
value of about two billion is the usual value (that's 32 bits signed).
64-bit platforms usually have a maximum value of about 9E18. PHP
does not support unsigned integers. Integer size
can be determined using the constant PHP_INT_SIZE, and
maximum value using the constant PHP_INT_MAX since
PHP 4.4.0 and PHP 5.0.5.
If an invalid digit is given in an octal integer (i.e. 8 or 9), the rest of the number is ignored.
Przykład #2 Octal weirdness
<?php
var_dump(01090); // 010 octal = 8 decimal
?>
Integer overflow
If PHP encounters a number beyond the bounds of the integer type, it will be interpreted as a float instead. Also, an operation which results in a number beyond the bounds of the integer type will return a float instead.
Przykład #3 Integer overflow on a 32-bit system
<?php
$large_number = 2147483647;
var_dump($large_number); // int(2147483647)
$large_number = 2147483648;
var_dump($large_number); // float(2147483648)
$million = 1000000;
$large_number = 50000 * $million;
var_dump($large_number); // float(50000000000)
?>
Przykład #4 Integer overflow on a 64-bit system
<?php
$large_number = 9223372036854775807;
var_dump($large_number); // int(9223372036854775807)
$large_number = 9223372036854775808;
var_dump($large_number); // float(9.2233720368548E+18)
$million = 1000000;
$large_number = 50000000000000 * $million;
var_dump($large_number); // float(5.0E+19)
?>
There is no integer division operator in PHP. 1/2 yields the float 0.5. The value can be casted to an integer to round it downwards, or the round() function provides finer control over rounding.
<?php
var_dump(25/7); // float(3.5714285714286)
var_dump((int) (25/7)); // int(3)
var_dump(round(25/7)); // float(4)
?>
Converting to integer
To explicitly convert a value to integer, use either the (int) or (integer) casts. However, in most cases the cast is not needed, since a value will be automatically converted if an operator, function or control structure requires an integer argument. A value can also be converted to integer with the intval() function.
See also: type-juggling.
From booleans
FALSE will yield 0 (zero), and TRUE will yield
1 (one).
From floating point numbers
When converting from float to integer, the number will be rounded towards zero.
If the float is beyond the boundaries of integer (usually +/- 2.15e+9 = 2^31 on 32-bit platforms and +/- 9.22e+18 = 2^63 on 64-bit platforms), the result is undefined, since the float doesn't have enough precision to give an exact integer result. No warning, not even a notice will be issued when this happens!
Never cast an unknown fraction to integer, as this can sometimes lead to unexpected results.
<?php
echo (int) ( (0.1+0.7) * 10 ); // echoes 7!
?>
See also the warning about float precision.
From strings
From other types
The behaviour of converting to integer is undefined for other types. Do not rely on any observed behaviour, as it can change without notice.
Floating point numbers
Floating point numbers (also known as "floats", "doubles", or "real numbers") can be specified using any of the following syntaxes:
<?php
$a = 1.234;
$b = 1.2e3;
$c = 7E-10;
?>
Formally:
LNUM [0-9]+
DNUM ([0-9]*[\.]{LNUM}) | ({LNUM}[\.][0-9]*)
EXPONENT_DNUM [+-]?(({LNUM} | {DNUM}) [eE][+-]? {LNUM})
The size of a float is platform-dependent, although a maximum of ~1.8e308 with a precision of roughly 14 decimal digits is a common value (the 64 bit IEEE format).
Floating point precision
Floating point numbers have limited precision. Although it depends on the system, PHP typically uses the IEEE 754 double precision format, which will give a maximum relative error due to rounding in the order of 1.11e-16. Non elementary arithmetic operations may give larger errors, and, of course, error propagation must be considered when several operations are compounded.
Additionally, rational numbers that are exactly representable as floating point numbers in base 10, like 0.1 or 0.7, do not have an exact representation as floating point numbers in base 2, which is used internally, no matter the size of the mantissa. Hence, they cannot be converted into their internal binary counterparts without a small loss of precision. This can lead to confusing results: for example, floor((0.1+0.7)*10) will usually return 7 instead of the expected 8, since the internal representation will be something like 7.9999999999999991118....
So never trust floating number results to the last digit, and do not compare floating point numbers directly for equality. If higher precision is necessary, the arbitrary precision math functions and gmp functions are available.
Converting to float
For information on converting strings to float, see String conversion to numbers. For values of other types, the conversion is performed by converting the value to integer first and then to float. See Converting to integer for more information. As of PHP 5, a notice is thrown if an object is converted to float.
Comparing floats
As noted in the warning above, testing floating point values for equality is problematic, due to the way that they are represented internally. However, there are ways to make comparisons of floating point values that work around these limitations.
To test floating point values for equality, an upper bound on the relative error due to rounding is used. This value is known as the machine epsilon, or unit roundoff, and is the smallest acceptable difference in calculations.
$a and $b are equal to 5 digits of precision.
<?php
$a = 1.23456789;
$b = 1.23456780;
$epsilon = 0.00001;
if(abs($a-$b) < $epsilon) {
echo "true";
}
?>
NaN
Some numeric operations can result in a value represented by the constant
NAN. This result represents an undefined or
unrepresentable value in floating-point calculations. Any loose or strict
comparisons of this value against any other value, including itself, will
have a result of FALSE.
Because NAN represents any number of different values,
NAN should not be compared to other values, including
itself, and instead should be checked for using is_nan().
Strings
A string is series of characters, where a character is the same as a byte. This means that PHP only supports a 256-character set, and hence does not offer native Unicode support. See details of the string type.
Informacja: It is no problem for a string to become very large. PHP imposes no boundary on the size of a string; the only limit is the available memory of the computer on which PHP is running.
Syntax
A string literal can be specified in four different ways:
- single quoted
- double quoted
- heredoc syntax
- nowdoc syntax (since PHP 5.3.0)
Single quoted
The simplest way to specify a string is to enclose it in single quotes (the character ').
To specify a literal single quote, escape it with a backslash (\). To specify a literal backslash, double it (\\). All other instances of backslash will be treated as a literal backslash: this means that the other escape sequences you might be used to, such as \r or \n, will be output literally as specified rather than having any special meaning.
Informacja: Unlike the double-quoted and heredoc syntaxes, variables and escape sequences for special characters will not be expanded when they occur in single quoted strings.
<?php
echo 'this is a simple string';
echo 'You can also have embedded newlines in
strings this way as it is
okay to do';
// Outputs: Arnold once said: "I'll be back"
echo 'Arnold once said: "I\'ll be back"';
// Outputs: You deleted C:\*.*?
echo 'You deleted C:\\*.*?';
// Outputs: You deleted C:\*.*?
echo 'You deleted C:\*.*?';
// Outputs: This will not expand: \n a newline
echo 'This will not expand: \n a newline';
// Outputs: Variables do not $expand $either
echo 'Variables do not $expand $either';
?>
Double quoted
If the string is enclosed in double-quotes ("), PHP will interpret more escape sequences for special characters:
| Sequence | Meaning |
|---|---|
| \n | linefeed (LF or 0x0A (10) in ASCII) |
| \r | carriage return (CR or 0x0D (13) in ASCII) |
| \t | horizontal tab (HT or 0x09 (9) in ASCII) |
| \v | vertical tab (VT or 0x0B (11) in ASCII) (since PHP 5.2.5) |
| \e | escape (ESC or 0x1B (27) in ASCII) (since PHP 5.4.0) |
| \f | form feed (FF or 0x0C (12) in ASCII) (since PHP 5.2.5) |
| \\ | backslash |
| \$ | dollar sign |
| \" | double-quote |
| \[0-7]{1,3} | the sequence of characters matching the regular expression is a character in octal notation |
| \x[0-9A-Fa-f]{1,2} | the sequence of characters matching the regular expression is a character in hexadecimal notation |
As in single quoted strings, escaping any other character will result in the backslash being printed too. Before PHP 5.1.1, the backslash in \{$var} had not been printed.
The most important feature of double-quoted strings is the fact that variable names will be expanded. See string parsing for details.
Heredoc
A third way to delimit strings is the heredoc syntax: <<<. After this operator, an identifier is provided, then a newline. The string itself follows, and then the same identifier again to close the quotation.
The closing identifier must begin in the first column of the line. Also, the identifier must follow the same naming rules as any other label in PHP: it must contain only alphanumeric characters and underscores, and must start with a non-digit character or underscore.
It is very important to note that the line with the closing identifier must contain no other characters, except possibly a semicolon (;). That means especially that the identifier may not be indented, and there may not be any spaces or tabs before or after the semicolon. It's also important to realize that the first character before the closing identifier must be a newline as defined by the local operating system. This is \n on UNIX systems, including Mac OS X. The closing delimiter (possibly followed by a semicolon) must also be followed by a newline.
If this rule is broken and the closing identifier is not "clean", it will not be considered a closing identifier, and PHP will continue looking for one. If a proper closing identifier is not found before the end of the current file, a parse error will result at the last line.
Heredocs can not be used for initializing class properties. Since PHP 5.3, this limitation is valid only for heredocs containing variables.
Przykład #1 Invalid example
<?php
class foo {
public $bar = <<<EOT
bar
EOT;
}
?>
Heredoc text behaves just like a double-quoted string, without the double quotes. This means that quotes in a heredoc do not need to be escaped, but the escape codes listed above can still be used. Variables are expanded, but the same care must be taken when expressing complex variables inside a heredoc as with strings.
Przykład #2 Heredoc string quoting example
<?php
$str = <<<EOD
Example of string
spanning multiple lines
using heredoc syntax.
EOD;
/* More complex example, with variables. */
class foo
{
var $foo;
var $bar;
function foo()
{
$this->foo = 'Foo';
$this->bar = array('Bar1', 'Bar2', 'Bar3');
}
}
$foo = new foo();
$name = 'MyName';
echo <<<EOT
My name is "$name". I am printing some $foo->foo.
Now, I am printing some {$foo->bar[1]}.
This should print a capital 'A': \x41
EOT;
?>
Powyższy przykład wyświetli:
My name is "MyName". I am printing some Foo. Now, I am printing some Bar2. This should print a capital 'A': A
It is also possible to use the Heredoc syntax to pass data to function arguments:
Przykład #3 Heredoc in arguments example
<?php
var_dump(array(<<<EOD
foobar!
EOD
));
?>
As of PHP 5.3.0, it's possible to initialize static variables and class properties/constants using the Heredoc syntax:
Przykład #4 Using Heredoc to initialize static values
<?php
// Static variables
function foo()
{
static $bar = <<<LABEL
Nothing in here...
LABEL;
}
// Class properties/constants
class foo
{
const BAR = <<<FOOBAR
Constant example
FOOBAR;
public $baz = <<<FOOBAR
Property example
FOOBAR;
}
?>
Starting with PHP 5.3.0, the opening Heredoc identifier may optionally be enclosed in double quotes:
Przykład #5 Using double quotes in Heredoc
<?php
echo <<<"FOOBAR"
Hello World!
FOOBAR;
?>
Nowdoc
Nowdocs are to single-quoted strings what heredocs are to double-quoted strings. A nowdoc is specified similarly to a heredoc, but no parsing is done inside a nowdoc. The construct is ideal for embedding PHP code or other large blocks of text without the need for escaping. It shares some features in common with the SGML <![CDATA[ ]]> construct, in that it declares a block of text which is not for parsing.
A nowdoc is identified with the same <<< sequence used for heredocs, but the identifier which follows is enclosed in single quotes, e.g. <<<'EOT'. All the rules for heredoc identifiers also apply to nowdoc identifiers, especially those regarding the appearance of the closing identifier.
Przykład #6 Nowdoc string quoting example
<?php
$str = <<<'EOD'
Example of string
spanning multiple lines
using nowdoc syntax.
EOD;
/* More complex example, with variables. */
class foo
{
public $foo;
public $bar;
function foo()
{
$this->foo = 'Foo';
$this->bar = array('Bar1', 'Bar2', 'Bar3');
}
}
$foo = new foo();
$name = 'MyName';
echo <<<'EOT'
My name is "$name". I am printing some $foo->foo.
Now, I am printing some {$foo->bar[1]}.
This should not print a capital 'A': \x41
EOT;
?>
Powyższy przykład wyświetli:
My name is "$name". I am printing some $foo->foo.
Now, I am printing some {$foo->bar[1]}.
This should not print a capital 'A': \x41Informacja:
Unlike heredocs, nowdocs can be used in any static data context. The typical example is initializing class properties or constants:
Przykład #7 Static data example
<?php
class foo {
public $bar = <<<'EOT'
bar
EOT;
}
?>
Informacja:
Nowdoc support was added in PHP 5.3.0.
Variable parsing
When a string is specified in double quotes or with heredoc, variables are parsed within it.
There are two types of syntax: a simple one and a complex one. The simple syntax is the most common and convenient. It provides a way to embed a variable, an array value, or an object property in a string with a minimum of effort.
The complex syntax can be recognised by the curly braces surrounding the expression.
Simple syntax
If a dollar sign ($) is encountered, the parser will greedily take as many tokens as possible to form a valid variable name. Enclose the variable name in curly braces to explicitly specify the end of the name.
<?php
$juice = "apple";
echo "He drank some $juice juice.".PHP_EOL;
// Invalid. "s" is a valid character for a variable name, but the variable is $juice.
echo "He drank some juice made of $juices.";
?>
Powyższy przykład wyświetli:
He drank some apple juice. He drank some juice made of .
Similarly, an array index or an object property can be parsed. With array indices, the closing square bracket (]) marks the end of the index. The same rules apply to object properties as to simple variables.
Przykład #8 Simple syntax example
<?php
$juices = array("apple", "orange", "koolaid1" => "purple");
echo "He drank some $juices[0] juice.".PHP_EOL;
echo "He drank some $juices[1] juice.".PHP_EOL;
echo "He drank some juice made of $juice[0]s.".PHP_EOL; // Won't work
echo "He drank some $juices[koolaid1] juice.".PHP_EOL;
class people {
public $john = "John Smith";
public $jane = "Jane Smith";
public $robert = "Robert Paulsen";
public $smith = "Smith";
}
$people = new people();
echo "$people->john drank some $juices[0] juice.".PHP_EOL;
echo "$people->john then said hello to $people->jane.".PHP_EOL;
echo "$people->john's wife greeted $people->robert.".PHP_EOL;
echo "$people->robert greeted the two $people->smiths."; // Won't work
?>
Powyższy przykład wyświetli:
He drank some apple juice. He drank some orange juice. He drank some juice made of s. He drank some purple juice. John Smith drank some apple juice. John Smith then said hello to Jane Smith. John Smith's wife greeted Robert Paulsen. Robert Paulsen greeted the two .
For anything more complex, you should use the complex syntax.
Complex (curly) syntax
This isn't called complex because the syntax is complex, but because it allows for the use of complex expressions.
Any scalar variable, array element or object property with a string representation can be included via this syntax. Simply write the expression the same way as it would appear outside the string, and then wrap it in { and }. Since { can not be escaped, this syntax will only be recognised when the $ immediately follows the {. Use {\$ to get a literal {$. Some examples to make it clear:
<?php
// Show all errors
error_reporting(E_ALL);
$great = 'fantastic';
// Won't work, outputs: This is { fantastic}
echo "This is { $great}";
// Works, outputs: This is fantastic
echo "This is {$great}";
echo "This is ${great}";
// Works
echo "This square is {$square->width}00 centimeters broad.";
// Works, quoted keys only work using the curly brace syntax
echo "This works: {$arr['key']}";
// Works
echo "This works: {$arr[4][3]}";
// This is wrong for the same reason as $foo[bar] is wrong outside a string.
// In other words, it will still work, but only because PHP first looks for a
// constant named foo; an error of level E_NOTICE (undefined constant) will be
// thrown.
echo "This is wrong: {$arr[foo][3]}";
// Works. When using multi-dimensional arrays, always use braces around arrays
// when inside of strings
echo "This works: {$arr['foo'][3]}";
// Works.
echo "This works: " . $arr['foo'][3];
echo "This works too: {$obj->values[3]->name}";
echo "This is the value of the var named $name: {${$name}}";
echo "This is the value of the var named by the return value of getName(): {${getName()}}";
echo "This is the value of the var named by the return value of \$object->getName(): {${$object->getName()}}";
// Won't work, outputs: This is the return value of getName(): {getName()}
echo "This is the return value of getName(): {getName()}";
?>
It is also possible to access class properties using variables within strings using this syntax.
<?php
class foo {
var $bar = 'I am bar.';
}
$foo = new foo();
$bar = 'bar';
$baz = array('foo', 'bar', 'baz', 'quux');
echo "{$foo->$bar}\n";
echo "{$foo->$baz[1]}\n";
?>
Powyższy przykład wyświetli:
I am bar. I am bar.
Informacja:
Functions, method calls, static class variables, and class constants inside {$} work since PHP 5. However, the value accessed will be interpreted as the name of a variable in the scope in which the string is defined. Using single curly braces ({}) will not work for accessing the return values of functions or methods or the values of class constants or static class variables.
<?php
// Show all errors.
error_reporting(E_ALL);
class beers {
const softdrink = 'rootbeer';
public static $ale = 'ipa';
}
$rootbeer = 'A & W';
$ipa = 'Alexander Keith\'s';
// This works; outputs: I'd like an A & W
echo "I'd like an {${beers::softdrink}}\n";
// This works too; outputs: I'd like an Alexander Keith's
echo "I'd like an {${beers::$ale}}\n";
?>
String access and modification by character
Characters within strings may be accessed and modified by specifying the zero-based offset of the desired character after the string using square array brackets, as in $str[42]. Think of a string as an array of characters for this purpose. The functions substr() and substr_replace() can be used when you want to extract or replace more than 1 character.
Informacja: Strings may also be accessed using braces, as in $str{42}, for the same purpose.
Writing to an out of range offset pads the string with spaces.
Non-integer types are converted to integer.
Illegal offset type emits E_NOTICE.
Negative offset emits E_NOTICE in write but reads empty string.
Only the first character of an assigned string is used.
Assigning empty string assigns NULL byte.
Przykład #9 Some string examples
<?php
// Get the first character of a string
$str = 'This is a test.';
$first = $str[0];
// Get the third character of a string
$third = $str[2];
// Get the last character of a string.
$str = 'This is still a test.';
$last = $str[strlen($str)-1];
// Modify the last character of a string
$str = 'Look at the sea';
$str[strlen($str)-1] = 'e';
?>
Informacja:
Accessing variables of other types (not including arrays or objects implementing the appropriate interfaces) using [] or {} silently returns
NULL.
Useful functions and operators
Strings may be concatenated using the '.' (dot) operator. Note that the '+' (addition) operator will not work for this. See String operators for more information.
There are a number of useful functions for string manipulation.
See the string functions section for general functions, and the regular expression functions or the Perl-compatible regular expression functions for advanced find & replace functionality.
There are also functions for URL strings, and functions to encrypt/decrypt strings (mcrypt and mhash).
Finally, see also the character type functions.
Converting to string
A value can be converted to a string using the (string) cast or the strval() function. String conversion is automatically done in the scope of an expression where a string is needed. This happens when using the echo() or print() functions, or when a variable is compared to a string. The sections on Types and Type Juggling will make the following clearer. See also the settype() function.
A boolean TRUE value is converted to the string
"1". Boolean FALSE is converted to
"" (the empty string). This allows conversion back and
forth between boolean and string values.
An integer or float is converted to a string representing the number textually (including the exponent part for floats). Floating point numbers can be converted using exponential notation (4.1E+6).
Informacja:
The decimal point character is defined in the script's locale (category LC_NUMERIC). See the setlocale() function.
Arrays are always converted to the string "Array"; because of this, echo() and print() can not by themselves show the contents of an array. To view a single element, use a construction such as echo $arr['foo']. See below for tips on viewing the entire contents.
Objects in PHP 4 are always converted to the string "Object". To print the values of object properties for debugging reasons, read the paragraphs below. To get an object's class name, use the get_class() function. As of PHP 5, the __toString method is used when applicable.
Resources are always converted to strings with the structure "Resource id #1", where 1 is the unique number assigned to the resource by PHP at runtime. Do not rely upon this structure; it is subject to change. To get a resource's type, use the get_resource_type() function.
NULL is always converted to an empty string.
As stated above, directly converting an array, object, or resource to a string does not provide any useful information about the value beyond its type. See the functions print_r() and var_dump() for more effective means of inspecting the contents of these types.
Most PHP values can also be converted to strings for permanent storage. This method is called serialization, and is performed by the serialize() function. If the PHP engine was built with WDDX support, PHP values can also be serialized as well-formed XML text.
String conversion to numbers
When a string is evaluated in a numeric context, the resulting value and type are determined as follows.
If the string does not contain any of the characters '.', 'e',
or 'E' and the numeric value fits into integer type limits (as defined by
PHP_INT_MAX), the string will be evaluated
as an integer. In all other cases it will be evaluated as a
float.
The value is given by the initial portion of the string. If the string starts with valid numeric data, this will be the value used. Otherwise, the value will be 0 (zero). Valid numeric data is an optional sign, followed by one or more digits (optionally containing a decimal point), followed by an optional exponent. The exponent is an 'e' or 'E' followed by one or more digits.
<?php
$foo = 1 + "10.5"; // $foo is float (11.5)
$foo = 1 + "-1.3e3"; // $foo is float (-1299)
$foo = 1 + "bob-1.3e3"; // $foo is integer (1)
$foo = 1 + "bob3"; // $foo is integer (1)
$foo = 1 + "10 Small Pigs"; // $foo is integer (11)
$foo = 4 + "10.2 Little Piggies"; // $foo is float (14.2)
$foo = "10.0 pigs " + 1; // $foo is float (11)
$foo = "10.0 pigs " + 1.0; // $foo is float (11)
?>
For more information on this conversion, see the Unix manual page for strtod(3).
To test any of the examples in this section, cut and paste the examples and insert the following line to see what's going on:
<?php
echo "\$foo==$foo; type is " . gettype ($foo) . "<br />\n";
?>
Do not expect to get the code of one character by converting it to integer, as is done in C. Use the ord() and chr() functions to convert between ASCII codes and characters.
Details of the String Type
The string in PHP is implemented as an array of bytes and an integer indicating the length of the buffer. It has no information about how those bytes translate to characters, leaving that task to the programmer. There are no limitations on the values the string can be composed of; in particular, bytes with value 0 (“NUL bytes”) are allowed anywhere in the string (however, a few functions, said in this manual not to be “binary safe”, may hand off the strings to libraries that ignore data after a NUL byte.)
This nature of the string type explains why there is no separate “byte” type in PHP – strings take this role. Functions that return no textual data – for instance, arbitrary data read from a network socket – will still return strings.
Given that PHP does not dictate a specific encoding for strings, one might wonder how string literals are encoded. For instance, is the string "á" equivalent to "\xE1" (ISO-8859-1), "\xC3\xA1" (UTF-8, C form), "\x61\xCC\x81" (UTF-8, D form) or any other possible representation? The answer is that string will be encoded in whatever fashion it is encoded in the script file. Thus, if the script is written in ISO-8859-1, the string will be encoded in ISO-8859-1 and so on. However, this does not apply if Zend Multibyte is enabled; in that case, the script may be written in an arbitrary encoding (which is explicity declared or is detected) and then converted to a certain internal encoding, which is then the encoding that will be used for the string literals. Note that there are some constraints on the encoding of the script (or on the internal encoding, should Zend Multibyte be enabled) – this almost always means that this encoding should be a compatible superset of ASCII, such as UTF-8 or ISO-8859-1. Note, however, that state-dependent encodings where the same byte values can be used in initial and non-initial shift states may be problematic.
Of course, in order to useful, functions that operate on text may have to make some assumptions about how the string is encoded. Unfortunately, there is much variation on this matter throughout PHP’s functions:
- Some functions assume that the string is encoded in some (any) single-byte encoding, but they do not need to interpret those bytes as specific characters. This is case of, for instance, substr(), strpos(), strlen() or strcmp(). Another way to think of these functions is that operate on memory buffers, i.e., they work with bytes and byte offsets.
- Other functions are passed the encoding of the string, possibly they also assume a default if no such information is given. This is the case of htmlentities() and the majority of the functions in the mbstring extension.
- Others use the current locale (see setlocale()), but operate byte-by-byte. This is the case of strcasecmp(), strtoupper() and ucfirst(). This means they can be used only with single-byte encodings, as long as the encoding is matched by the locale. For instance strtoupper("á") may return "Á" if the locale is correctly set and á is encoded with a single byte. If it is encoded in UTF-8, the correct result will not be returned and the resulting string may or may not be returned corrupted, depending on the current locale.
- Finally, they may just assume the string is using a specific encoding, usually UTF-8. This is the case of most functions in the intl extension and in the PCRE extension (in the last case, only when the u modifier is used). Although this is due to their special purpose, the function utf8_decode() assumes a UTF-8 encoding and the function utf8_encode() assumes an ISO-8859-1 encoding.
Ultimately, this means writing correct programs using Unicode depends on carefully avoiding functions that will not work and that most likely will corrupt the data and using instead the functions that do behave correctly, generally from the intl and mbstring extensions. However, using functions that can handle Unicode encodings is just the beginning. No matter the functions the language provides, it is essential to know the Unicode specification. For instance, a program that assumes there is only uppercase and lowercase is making a wrong assumption.
Arrays
An array in PHP is actually an ordered map. A map is a type that associates values to keys. This type is optimized for several different uses; it can be treated as an array, list (vector), hash table (an implementation of a map), dictionary, collection, stack, queue, and probably more. As array values can be other arrays, trees and multidimensional arrays are also possible.
Explanation of those data structures is beyond the scope of this manual, but at least one example is provided for each of them. For more information, look towards the considerable literature that exists about this broad topic.
Syntax
Specifying with array()
An array can be created using the array() language construct. It takes any number of comma-separated key => value pairs as arguments.
array(
key => value,
key2 => value2,
key3 => value3,
...
)
It is possible to write a comma after last element or omit it. Result is the same, array(1, 2) === array(1, 2,). Writing comma after last element is useful mainly when formatting array definition on multiple lines (see next example).
As of PHP 5.4 you can also use the short array syntax, which replaces array() with [].
Przykład #1 A simple array
<?php
$array = array(
"foo" => "bar",
"bar" => "foo",
);
// as of PHP 5.4
$array = [
"foo" => "bar",
"bar" => "foo",
];
?>
The key can either be an integer or a string. The value can be of any type.
Additionally the following key casts will occur:
- Strings containing valid integers will be cast to the integer type. E.g. the key "8" will actually be stored under 8. On the other hand "08" will not be cast, as it isn't a valid decimal integer.
- Floats are also cast to integers, which means that the fractional part will be truncated. E.g. the key 8.7 will actually be stored under 8.
- Bools are cast to integers, too, i.e. the key true will actually be stored under 1 and the key false under 0.
- Null will be cast to the empty string, i.e. the key null will actually be stored under "".
- Arrays and objects can not be used as keys. Doing so will result in a warning: Illegal offset type.
If multiple elements in the array declaration use the same key, only the last one will be used as all others are overwritten.
Przykład #2 Type Casting and Overwriting example
<?php
$array = array(
1 => "a",
"1" => "b",
1.5 => "c",
true => "d",
);
var_dump($array);
?>
Powyższy przykład wyświetli:
array(1) {
[1]=>
string(1) "d"
}
As all the keys in the above example are cast to 1, the value will be overwritten on every new element and the last assined value "d" is the only one left over.
PHP arrays can contain integer and string keys at the same time as PHP does not distinguish between indexed and associative arrays.
Przykład #3 Mixed integer and string keys
<?php
$array = array(
"foo" => "bar",
"bar" => "foo",
100 => -100,
-100 => 100,
);
var_dump($array);
?>
Powyższy przykład wyświetli:
array(4) {
["foo"]=>
string(3) "bar"
["bar"]=>
string(3) "foo"
[100]=>
int(-100)
[-100]=>
int(100)
}
The key is optional. If it is not specified, PHP will use the increment of the largest previously used integer key.
Przykład #4 Indexed arrays without key
<?php
$array = array("foo", "bar", "hallo", "world");
var_dump($array);
?>
Powyższy przykład wyświetli:
array(4) {
[0]=>
string(3) "foo"
[1]=>
string(3) "bar"
[2]=>
string(5) "hallo"
[3]=>
string(5) "world"
}
It is possible to specify the key only for some elements and leave it out for others:
Przykład #5 Keys not on all elements
<?php
$array = array(
"a",
"b",
6 => "c",
"d",
);
var_dump($array);
?>
Powyższy przykład wyświetli:
array(4) {
[0]=>
string(1) "a"
[1]=>
string(1) "b"
[6]=>
string(1) "c"
[7]=>
string(1) "d"
}
As you can see the last value "d" was assigned the key 7. This is because the largest integer key before that was 6.
Accessing array elements with square bracket syntax
Array elements can be accessed using the array[key] syntax.
Przykład #6 Accessing array elements
<?php
$array = array(
"foo" => "bar",
42 => 24,
"multi" => array(
"dimensional" => array(
"array" => "foo"
)
)
);
var_dump($array["foo"]);
var_dump($array[42]);
var_dump($array["multi"]["dimensional"]["array"]);
?>
Powyższy przykład wyświetli:
string(3) "bar" int(24) string(3) "foo"
As of PHP 5.4 it is possible to array dereference the result of a function or method call directly. Before it was only possible using a temporary variable.
Przykład #7 Array dereferencing
<?php
function getArray() {
return array(1, 2, 3);
}
// on PHP 5.4
$secondElement = getArray()[1];
// previously
$tmp = getArray();
$secondElement = $tmp[1];
// or
list(, $secondElement) = getArray();
?>
Informacja:
Attempting to access an array key which has not been defined is the same as accessing any other undefined variable: an
E_NOTICE-level error message will be issued, and the result will beNULL.
Creating/modifying with square bracket syntax
An existing array can be modified by explicitly setting values in it.
This is done by assigning values to the array, specifying the key in brackets. The key can also be omitted, resulting in an empty pair of brackets ([]).
$arr[key] = value; $arr[] = value; // key may be an integer or string // value may be any value of any type
If $arr doesn't exist yet, it will be created, so this is also an alternative way to create an array. This practice is however discouraged because if $arr already contains some value (e.g. string from request variable) then this value will stay in the place and [] may actually stand for string access operator. It is always better to initialize variable by a direct assignment.
To change a certain value, assign a new value to that element using its key. To remove a key/value pair, call the unset() function on it.
<?php
$arr = array(5 => 1, 12 => 2);
$arr[] = 56; // This is the same as $arr[13] = 56;
// at this point of the script
$arr["x"] = 42; // This adds a new element to
// the array with key "x"
unset($arr[5]); // This removes the element from the array
unset($arr); // This deletes the whole array
?>
Informacja:
As mentioned above, if no key is specified, the maximum of the existing integer indices is taken, and the new key will be that maximum value plus 1 (but at least 0). If no integer indices exist yet, the key will be 0 (zero).
Note that the maximum integer key used for this need not currently exist in the array. It need only have existed in the array at some time since the last time the array was re-indexed. The following example illustrates:
<?php
// Create a simple array.
$array = array(1, 2, 3, 4, 5);
print_r($array);
// Now delete every item, but leave the array itself intact:
foreach ($array as $i => $value) {
unset($array[$i]);
}
print_r($array);
// Append an item (note that the new key is 5, instead of 0).
$array[] = 6;
print_r($array);
// Re-index:
$array = array_values($array);
$array[] = 7;
print_r($array);
?>Powyższy przykład wyświetli:
Array ( [0] => 1 [1] => 2 [2] => 3 [3] => 4 [4] => 5 ) Array ( ) Array ( [5] => 6 ) Array ( [0] => 6 [1] => 7 )
Useful functions
There are quite a few useful functions for working with arrays. See the array functions section.
Informacja:
The unset() function allows removing keys from an array. Be aware that the array will not be reindexed. If a true "remove and shift" behavior is desired, the array can be reindexed using the array_values() function.
<?php
$a = array(1 => 'one', 2 => 'two', 3 => 'three');
unset($a[2]);
/* will produce an array that would have been defined as
$a = array(1 => 'one', 3 => 'three');
and NOT
$a = array(1 => 'one', 2 =>'three');
*/
$b = array_values($a);
// Now $b is array(0 => 'one', 1 =>'three')
?>
The foreach control structure exists specifically for arrays. It provides an easy way to traverse an array.
Array do's and don'ts
Why is $foo[bar] wrong?
Always use quotes around a string literal array index. For example, $foo['bar'] is correct, while $foo[bar] is not. But why? It is common to encounter this kind of syntax in old scripts:
<?php
$foo[bar] = 'enemy';
echo $foo[bar];
// etc
?>
This is wrong, but it works. The reason is that this code has an undefined
constant (bar) rather than a string ('bar' - notice the
quotes). PHP may in future define constants which, unfortunately for such
code, have the same name. It works because PHP automatically converts a
bare string (an unquoted string which does
not correspond to any known symbol) into a string which
contains the bare string. For instance, if there is no defined
constant named bar, then PHP will substitute in the
string 'bar' and use that.
Informacja: This does not mean to always quote the key. Do not quote keys which are constants or variables, as this will prevent PHP from interpreting them.
<?php
error_reporting(E_ALL);
ini_set('display_errors', true);
ini_set('html_errors', false);
// Simple array:
$array = array(1, 2);
$count = count($array);
for ($i = 0; $i < $count; $i++) {
echo "\nChecking $i: \n";
echo "Bad: " . $array['$i'] . "\n";
echo "Good: " . $array[$i] . "\n";
echo "Bad: {$array['$i']}\n";
echo "Good: {$array[$i]}\n";
}
?>Powyższy przykład wyświetli:
Checking 0: Notice: Undefined index: $i in /path/to/script.html on line 9 Bad: Good: 1 Notice: Undefined index: $i in /path/to/script.html on line 11 Bad: Good: 1 Checking 1: Notice: Undefined index: $i in /path/to/script.html on line 9 Bad: Good: 2 Notice: Undefined index: $i in /path/to/script.html on line 11 Bad: Good: 2
More examples to demonstrate this behaviour:
<?php
// Show all errors
error_reporting(E_ALL);
$arr = array('fruit' => 'apple', 'veggie' => 'carrot');
// Correct
print $arr['fruit']; // apple
print $arr['veggie']; // carrot
// Incorrect. This works but also throws a PHP error of level E_NOTICE because
// of an undefined constant named fruit
//
// Notice: Use of undefined constant fruit - assumed 'fruit' in...
print $arr[fruit]; // apple
// This defines a constant to demonstrate what's going on. The value 'veggie'
// is assigned to a constant named fruit.
define('fruit', 'veggie');
// Notice the difference now
print $arr['fruit']; // apple
print $arr[fruit]; // carrot
// The following is okay, as it's inside a string. Constants are not looked for
// within strings, so no E_NOTICE occurs here
print "Hello $arr[fruit]"; // Hello apple
// With one exception: braces surrounding arrays within strings allows constants
// to be interpreted
print "Hello {$arr[fruit]}"; // Hello carrot
print "Hello {$arr['fruit']}"; // Hello apple
// This will not work, and will result in a parse error, such as:
// Parse error: parse error, expecting T_STRING' or T_VARIABLE' or T_NUM_STRING'
// This of course applies to using superglobals in strings as well
print "Hello $arr['fruit']";
print "Hello $_GET['foo']";
// Concatenation is another option
print "Hello " . $arr['fruit']; // Hello apple
?>
When error_reporting is set to
show E_NOTICE level errors (by setting it to
E_ALL, for example), such uses will become immediately
visible. By default,
error_reporting is set not to
show notices.
As stated in the syntax section, what's inside the square brackets ('[' and ']') must be an expression. This means that code like this works:
<?php
echo $arr[somefunc($bar)];
?>
This is an example of using a function return value as the array index. PHP also knows about constants:
<?php
$error_descriptions[E_ERROR] = "A fatal error has occured";
$error_descriptions[E_WARNING] = "PHP issued a warning";
$error_descriptions[E_NOTICE] = "This is just an informal notice";
?>
Note that E_ERROR is also a valid identifier, just like
bar in the first example. But the last example is in fact
the same as writing:
<?php
$error_descriptions[1] = "A fatal error has occured";
$error_descriptions[2] = "PHP issued a warning";
$error_descriptions[8] = "This is just an informal notice";
?>
because E_ERROR equals 1, etc.
So why is it bad then?
At some point in the future, the PHP team might want to add another constant or keyword, or a constant in other code may interfere. For example, it is already wrong to use the words empty and default this way, since they are reserved keywords.
Informacja: To reiterate, inside a double-quoted string, it's valid to not surround array indexes with quotes so "$foo[bar]" is valid. See the above examples for details on why as well as the section on variable parsing in strings.
Converting to array
For any of the types: integer, float, string, boolean and resource, converting a value to an array results in an array with a single element with index zero and the value of the scalar which was converted. In other words, (array)$scalarValue is exactly the same as array($scalarValue).
If an object is converted to an array, the result is an array whose elements are the object's properties. The keys are the member variable names, with a few notable exceptions: integer properties are unaccessible; private variables have the class name prepended to the variable name; protected variables have a '*' prepended to the variable name. These prepended values have null bytes on either side. This can result in some unexpected behaviour:
<?php
class A {
private $A; // This will become '\0A\0A'
}
class B extends A {
private $A; // This will become '\0B\0A'
public $AA; // This will become 'AA'
}
var_dump((array) new B());
?>
The above will appear to have two keys named 'AA', although one of them is actually named '\0A\0A'.
Comparing
It is possible to compare arrays with the array_diff() function and with array operators.
Examples
The array type in PHP is very versatile. Here are some examples:
<?php
// This:
$a = array( 'color' => 'red',
'taste' => 'sweet',
'shape' => 'round',
'name' => 'apple',
4 // key will be 0
);
$b = array('a', 'b', 'c');
// . . .is completely equivalent with this:
$a = array();
$a['color'] = 'red';
$a['taste'] = 'sweet';
$a['shape'] = 'round';
$a['name'] = 'apple';
$a[] = 4; // key will be 0
$b = array();
$b[] = 'a';
$b[] = 'b';
$b[] = 'c';
// After the above code is executed, $a will be the array
// array('color' => 'red', 'taste' => 'sweet', 'shape' => 'round',
// 'name' => 'apple', 0 => 4), and $b will be the array
// array(0 => 'a', 1 => 'b', 2 => 'c'), or simply array('a', 'b', 'c').
?>
Przykład #8 Using array()
<?php
// Array as (property-)map
$map = array( 'version' => 4,
'OS' => 'Linux',
'lang' => 'english',
'short_tags' => true
);
// strictly numerical keys
$array = array( 7,
8,
0,
156,
-10
);
// this is the same as array(0 => 7, 1 => 8, ...)
$switching = array( 10, // key = 0
5 => 6,
3 => 7,
'a' => 4,
11, // key = 6 (maximum of integer-indices was 5)
'8' => 2, // key = 8 (integer!)
'02' => 77, // key = '02'
0 => 12 // the value 10 will be overwritten by 12
);
// empty array
$empty = array();
?>
Przykład #9 Collection
<?php
$colors = array('red', 'blue', 'green', 'yellow');
foreach ($colors as $color) {
echo "Do you like $color?\n";
}
?>
Powyższy przykład wyświetli:
Do you like red? Do you like blue? Do you like green? Do you like yellow?
Changing the values of the array directly is possible since PHP 5 by passing them by reference. Before that, a workaround is necessary:
Przykład #10 Changing element in the loop
<?php
// PHP 5
foreach ($colors as &$color) {
$color = strtoupper($color);
}
unset($color); /* ensure that following writes to
$color will not modify the last array element */
// Workaround for older versions
foreach ($colors as $key => $color) {
$colors[$key] = strtoupper($color);
}
print_r($colors);
?>
Powyższy przykład wyświetli:
Array
(
[0] => RED
[1] => BLUE
[2] => GREEN
[3] => YELLOW
)
This example creates a one-based array.
Przykład #11 One-based index
<?php
$firstquarter = array(1 => 'January', 'February', 'March');
print_r($firstquarter);
?>
Powyższy przykład wyświetli:
Array
(
[1] => 'January'
[2] => 'February'
[3] => 'March'
)
Przykład #12 Filling an array
<?php
// fill an array with all items from a directory
$handle = opendir('.');
while (false !== ($file = readdir($handle))) {
$files[] = $file;
}
closedir($handle);
?>
Arrays are ordered. The order can be changed using various sorting functions. See the array functions section for more information. The count() function can be used to count the number of items in an array.
Przykład #13 Sorting an array
<?php
sort($files);
print_r($files);
?>
Because the value of an array can be anything, it can also be another array. This enables the creation of recursive and multi-dimensional arrays.
Przykład #14 Recursive and multi-dimensional arrays
<?php
$fruits = array ( "fruits" => array ( "a" => "orange",
"b" => "banana",
"c" => "apple"
),
"numbers" => array ( 1,
2,
3,
4,
5,
6
),
"holes" => array ( "first",
5 => "second",
"third"
)
);
// Some examples to address values in the array above
echo $fruits["holes"][5]; // prints "second"
echo $fruits["fruits"]["a"]; // prints "orange"
unset($fruits["holes"][0]); // remove "first"
// Create a new multi-dimensional array
$juices["apple"]["green"] = "good";
?>
Array assignment always involves value copying. Use the reference operator to copy an array by reference.
<?php
$arr1 = array(2, 3);
$arr2 = $arr1;
$arr2[] = 4; // $arr2 is changed,
// $arr1 is still array(2, 3)
$arr3 = &$arr1;
$arr3[] = 4; // now $arr1 and $arr3 are the same
?>
Objects
Object Initialization
To create a new object, use the new statement to instantiate a class:
<?php
class foo
{
function do_foo()
{
echo "Doing foo.";
}
}
$bar = new foo;
$bar->do_foo();
?>
For a full discussion, see the Classes and Objects chapter.
Converting to object
If an object is converted to an object, it is not
modified. If a value of any other type is converted to an
object, a new instance of the stdClass
built-in class is created. If the value was NULL, the new instance will be
empty. Arrays convert to an object with properties
named by keys, and corresponding values. For any other value, a member
variable named scalar will contain the value.
<?php
$obj = (object) 'ciao';
echo $obj->scalar; // outputs 'ciao'
?>
Resources
A resource is a special variable, holding a reference to an external resource. Resources are created and used by special functions. See the appendix for a listing of all these functions and the corresponding resource types.
See also the get_resource_type() function.
Converting to resource
As resource variables hold special handlers to opened files, database connections, image canvas areas and the like, converting to a resource makes no sense.
Freeing resources
Thanks to the reference-counting system introduced with PHP 4's Zend Engine, a resource with no more references to it is detected automatically, and it is freed by the garbage collector. For this reason, it is rarely necessary to free the memory manually.
Informacja: Persistent database links are an exception to this rule. They are not destroyed by the garbage collector. See the persistent connections section for more information.
NULL
The special NULL value represents a variable with no value. NULL is the
only possible value of type NULL.
A variable is considered to be null if:
-
it has been assigned the constant
NULL. -
it has not been set to any value yet.
-
it has been unset().
Syntax
There is only one value of type null, and that is the
case-insensitive constant NULL.
<?php
$var = NULL;
?>
Casting to NULL
Casting a variable to null using (unset) $var
will not remove the variable or unset its value.
It will only return a NULL value.
Callbacks
Callbacks can be denoted by callable type hint as of PHP 5.4. This documentation used callback type information for the same purpose.
Some functions like call_user_func() or usort() accept user-defined callback functions as a parameter. Callback functions can not only be simple functions, but also object methods, including static class methods.
Passing
A PHP function is passed by its name as a string. Any built-in or user-defined function can be used, except language constructs such as: array(), echo(), empty(), eval(), exit(), isset(), list(), print() or unset().
A method of an instantiated object is passed as an array containing an object at index 0 and the method name at index 1.
Static class methods can also be passed without instantiating an object of that class by passing the class name instead of an object at index 0. As of PHP 5.2.3, it is also possible to pass 'ClassName::methodName'.
Apart from common user-defined function, create_function() can also be used to create an anonymous callback function. As of PHP 5.3.0 it is possible to also pass a closure to a callback parameter.
Przykład #1 Callback function examples
<?php
// An example callback function
function my_callback_function() {
echo 'hello world!';
}
// An example callback method
class MyClass {
static function myCallbackMethod() {
echo 'Hello World!';
}
}
// Type 1: Simple callback
call_user_func('my_callback_function');
// Type 2: Static class method call
call_user_func(array('MyClass', 'myCallbackMethod'));
// Type 3: Object method call
$obj = new MyClass();
call_user_func(array($obj, 'myCallbackMethod'));
// Type 4: Static class method call (As of PHP 5.2.3)
call_user_func('MyClass::myCallbackMethod');
// Type 5: Relative static class method call (As of PHP 5.3.0)
class A {
public static function who() {
echo "A\n";
}
}
class B extends A {
public static function who() {
echo "B\n";
}
}
call_user_func(array('B', 'parent::who')); // A
?>
Przykład #2 Callback example using a Closure
<?php
// Our closure
$double = function($a) {
return $a * 2;
};
// This is our range of numbers
$numbers = range(1, 5);
// Use the closure as a callback here to
// double the size of each element in our
// range
$new_numbers = array_map($double, $numbers);
print implode(' ', $new_numbers);
?>
Powyższy przykład wyświetli:
2 4 6 8 10
Informacja: In PHP 4, it was necessary to use a reference to create a callback that points to the actual object, and not a copy of it. For more details, see References Explained.
Informacja:
Wywołania zwrotne zdefiniowane za pomocą takich funkcji jak call_user_func() i call_user_func_array() nie zostaną aktywowane jeśli w poprzednim wywołaniu zostanie wygenerowany nieobsłużony wyjątek.
Pseudo-types and variables used in this documentation
mixed
mixed indicates that a parameter may accept multiple (but not necessarily all) types.
gettype() for example will accept all PHP types, while str_replace() will accept strings and arrays.
callback
callback pseudo-types was used in this documentation before callable type hint was introduced by PHP 5.4. It means exactly the same.
void
void as a return type means that the return value is useless. void in a parameter list means that the function doesn't accept any parameters.
...
$... in function prototypes means
and so on. This variable name is used when a function can
take an endless number of arguments.
Type Juggling
PHP does not require (or support) explicit type definition in variable declaration; a variable's type is determined by the context in which the variable is used. That is to say, if a string value is assigned to variable $var, $var becomes a string. If an integer value is then assigned to $var, it becomes an integer.
An example of PHP's automatic type conversion is the addition operator '+'. If either operand is a float, then both operands are evaluated as floats, and the result will be a float. Otherwise, the operands will be interpreted as integers, and the result will also be an integer. Note that this does not change the types of the operands themselves; the only change is in how the operands are evaluated and what the type of the expression itself is.
<?php
$foo = "0"; // $foo is string (ASCII 48)
$foo += 2; // $foo is now an integer (2)
$foo = $foo + 1.3; // $foo is now a float (3.3)
$foo = 5 + "10 Little Piggies"; // $foo is integer (15)
$foo = 5 + "10 Small Pigs"; // $foo is integer (15)
?>
If the last two examples above seem odd, see String conversion to numbers.
To force a variable to be evaluated as a certain type, see the section on Type casting. To change the type of a variable, see the settype() function.
To test any of the examples in this section, use the var_dump() function.
Informacja:
The behaviour of an automatic conversion to array is currently undefined.
Also, because PHP supports indexing into strings via offsets using the same syntax as array indexing, the following example holds true for all PHP versions:
<?php
$a = 'car'; // $a is a string
$a[0] = 'b'; // $a is still a string
echo $a; // bar
?>See the section titled String access by character for more information.
Type Casting
Type casting in PHP works much as it does in C: the name of the desired type is written in parentheses before the variable which is to be cast.
<?php
$foo = 10; // $foo is an integer
$bar = (boolean) $foo; // $bar is a boolean
?>
The casts allowed are:
- (int), (integer) - cast to integer
- (bool), (boolean) - cast to boolean
- (float), (double), (real) - cast to float
- (string) - cast to string
- (array) - cast to array
- (object) - cast to object
- (unset) - cast to NULL (PHP 5)
(binary) casting and b prefix forward support was added in PHP 5.2.1
Note that tabs and spaces are allowed inside the parentheses, so the following are functionally equivalent:
<?php
$foo = (int) $bar;
$foo = ( int ) $bar;
?>
Casting literal strings and variables to binary strings:
<?php
$binary = (binary) $string;
$binary = b"binary string";
?>
Informacja:
Instead of casting a variable to a string, it is also possible to enclose the variable in double quotes.
<?php
$foo = 10; // $foo is an integer
$str = "$foo"; // $str is a string
$fst = (string) $foo; // $fst is also a string
// This prints out that "they are the same"
if ($fst === $str) {
echo "they are the same";
}
?>
It may not be obvious exactly what will happen when casting between certain types. For more information, see these sections:
Zmienne
Spis treści
Podstawy
Każdą zmienną w PHP zapisuje się, poprzedzając jej nazwę znakiem dolara "$". Wielkość liter w nazwie zmiennej jest rozróżniana.
Nazw zmiennych dotyczą te same reguły, co innych rodzajów nazw w PHP. Poprawna nazwa zmiennej zaczyna się od litery lub znaku podkreślenia "_", po których może wystąpić dowolna ilość liter, cyfr lub znaków podkreślenia. Jako wyrażenie regularne, można to zapisać tak: '[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*'
Informacja: W naszym rozumieniu, litery to znaki a-z, A-Z i bajty od 127 do 255 (0x7f-0xff).
Informacja: $this to specialna zmienna, której nie można definiować.
Zobacz także Userland Naming Guide.
Aby uzyskać więcej informacji na temat funkcji powiązanych ze zmiennymi, zobacz Funkcje Obsługi Zmiennych.
<?php
$zmienna = 'Pan';
$Zmienna = 'Jan';
echo "$zmienna, $Zmienna"; // wyświetla "Pan, Jan"
$7dni = 'tydzień'; // niepoprawna nazwa - zaczyna się od cyfry
$_7dni = 'tydzień'; // poprawna nazwa - zaczyna się znakiem podkreślenia
$jaźń = 'osobowość'; // poprawna nazwa - "ń" i "ź" należą do ASCII 127-255
?>
Domyślnie, zmienne zawsze są zawsze przypisywane przez wartość. Innymi słowy, jeśli przypiszesz do zmiennej jakieś wyrażenie, wartość tego wyrażenia zostanie skopiowana do zmiennej. Oznacza to, że po przypisaniu wartości jednej zmiennej do drugiej, późniejsza zmiana wartości jednej z nich nie spowoduje zmiany wartości drugiej. Więcej informacji na ten temat w rozdziale Wyrażenia.
PHP oferuje jeszcze jeden sposób przypisywania wartości do zmiennych: przypisanie przez referencję. Oznacza to, że nowa zmienna tylko odnosi się (innymi słowy, "staje się aliasem" lub "wskazuje na") do pierwotnej zmiennej. Zmiany wykonane na nowej zmiennej oddziałują także na pierwotną zmienną i vice versa.
Aby przypisać przez referencję, postaw znak ampersand (&) przed nazwą zmiennej przypisywanej (zmiennej od której pobierasz wartość). Na przykład poniższy kod wyświetla "To jest PHP" dwa razy:
<?php
$foo = "PHP"; // Przypisz wartość "PHP" do $foo.
$bar = &$foo; // Przypisz referencyjnie $foo do $bar.
$bar = "To jest $bar"; // Zmień $bar...
echo $bar;
echo $foo; // $foo też się zmieniło.
?>
Należy pamiętać, że tylko wyrażenia posiadające nazwę mogą być przypisane przez referencję.
<?php
$foo = 25;
$bar = &$foo; // Przypisanie poprawne.
$bar = &(24 * 7); // Przypisanie niepoprawne - do nienazwanego wyrażenia.
function test()
{
return 25;
}
$bar = &test(); // Niepoprawne.
?>
W PHP nie jest konieczne inicjowanie zmiennych, jednak jest to bardzo
dobry nawyk. Niezainicjowane zmienne mają domyślne wartości dla ich typu, zależnie od kontekstu, w jaki zmienne te zostały użyte
- zmienne logiczne typu boolean domyślnie przyjmują wartość FALSE, zmiennym całkowitym typu integer domyślnie nadawane jest zero, łańcuchom tekstowym
(np. użytym wewnątrz echo()) nadany jest łańcuch pusty, natomiast tablice zostają pustymi tablicami.
Przykład #1 Domyślne wartości niezainicjowanych zmiennych
<?php
// Zmienna bez nadanej wartości ORAZ bez odwołań do niej (brak kontekstu, w jakim została użyta); zwróci NULL
var_dump($zmienna_bez_kontekstu_uzycia);
// Używanie zmiennej logicznej typu boolean; zwróci 'false' (Zobacz informacje o operatorach trójparametrowych, by poznać tę składnię)
echo($nieinicjowana_zmiena_bool ? "true\n" : "false\n");
// Używanie łańcuchów; zwróci 'string(3) "abc"'
$nieinicjowany_lancuch .= 'abc';
var_dump($nieinicjowany_lancuch);
// Używanie zmiennych całkowitych; zwróci 'int(25)'
$nieinicjowana_zmienna_int += 25; // 0 + 25 => 25
var_dump($nieinicjowana_zmienna_int);
// Używanie zmiennych typu float/double; zwróci 'float(1.25)'
$nieinicjowana_zmienna_float += 1.25;
var_dump($nieinicjowana_zmienna_float);
// Używanie tablicy; zwróci array(1) { [3]=> string(3) "def" }
$nieinicjowana_tablica[3] = "def"; // array() + array(3 => "def") => array(3 => "def")
var_dump($nieinicjowana_tablica);
// Używanie obiektu; stworzy nowy obiekt stdClass (zobacz http://www.php.net/manual/pl/reserved.classes.php)
// Zwróci: object(stdClass)#1 (1) { ["foo"]=> string(3) "bar" }
$nieinicjowany_obiekt->foo = 'bar';
var_dump($nieinicjowany_obiekt);
?>
Poleganie na domyślnej wartości niezainicjowanej zmiennej jest problematyczne, w razie zawarcia jednego pliku wewnątrz innego, posiadającego tak samo nazwane zmienne. Jest to również poważne zagrożenie dla bezpieczeństwa przy włączonej opcji register_globals. Ostrzeżenie klasy E_NOTICE pojawi się podczas pracy z niezainicjowanymi zmiennymi, jednak w przypadku przypisywania elentów do niezainicjowanych tablic - już nie. Funkcja isset() może zostać użyta w celu wykrycia, czy zmienna została już zainicjowana.
Zmienne Predefiniowane
PHP udostępnia dla każdego pracującego skryptu dużą ilość predefiniowanych zmiennych. Jednakże wiele spośród tych zmiennych nie może być w pełni objaśnionych, gdyż są zależne od rodzaju serwera, jego wersji, ustawień i innych czynników. Niektóre z tych zmiennych nie będą dostępne dla skryptów PHP uruchomionych z Linii Poleceń. Lista tych zmiennych znajduje się w rozdziale Predefiniowane Zmienne.
W PHP 4.2.0 i późniejszych, domyślne ustawienie dla instrukcji PHP register_globals jest wyłączone. Jest to bardzo istotna zmiana w PHP. Mając opcję register_globals wyłączoną wpływamy na ustawienie zmiennych predefiniowanych, dostępnych globalnie. Na przykład, aby poznać wartość DOCUMENT_ROOT użyjesz $_SERVER['DOCUMENT_ROOT'] zamiast $DOCUMENT_ROOT, lub $_GET['id'] z adresu URL http://www.example.com/test.php?id=3 zamiast $id, albo $_ENV['HOME'] a nie $HOME.
Aby uzyskać informacje powiązane z tą zmianą, przeczytaj część o konfiguracji register_globals, rozdziału o bezpieczeństwie Używanie Register Globals , oraz w informacjach o wydaniu (ang. Release Announcements) PHP » 4.1.0 jak i » 4.2.0
Używanie dostępnych zmiennych predefiniowanych, jak tablice superglobalne, jest zalecane.
Począwszy od wersji 4.1.0, PHP udostępnia dodatkowo zestaw predefiniowanych tablic, które zawierają zmienne serwera, zmienne środowiskowe oraz zmienne użytkownika. Tablice te są dość specyficzne, gdyż są one automatycznie globalne, tzn. automatycznie dostępne w każdym miejscu. Dlatego nazywa się je "superglobalami". (W PHP nie ma mechanizmu pozwalającego użytkownikowi na definiowanie własnych superglobali.) Superglobale PHP wymienione są poniżej; jednakże wykaz ich zawartości i głębsze omówienie prefiniowanych zmiennych PHP oraz ich natury znajduje się w rozdziale predefiniowane zmienne. Zauważ także, że starsze zmienne predefiniowane ($HTTP_*_VARS) wciąż funkcjonują. Od PHP 5.0.0, długie tablice zmiennych predefiniowanych mogą być wyłączone dyrektywą konfiguracji register_long_arrays.
Informacja: Zmienne zmienne
Zmienne superglobale nie mogą być użyte jako zmienne zmienne wewnątrz funkcji, ani jako metody klasy.
Informacja:
Nawet pomimo tego, że zmienne superglobalne i HTTP_*_VARS mogą istnieć w tym samym czasie; nie są one tożsame, czyli zmiana jednej nie zmieni drugiej.
Jeśli pewne zmienne w variables_order nie są ustawione, to ich odpowiedniki zmiennych predefiniowanych PHP również są puste.
Zasięg zmiennych
Zasięg zmiennej zależy od miejsca, w jakim ją zdefiniowano. Najczęściej zmienne PHP widoczne są tylko w jednym zasięgu. Taki zasięg obejmuje również pliki dołączone funkcjami include i require. Na przykład:
<?php
$a = 1;
include 'b.inc';
?>
Tutaj zmienna $a będzie dostępna także wewnątrz dołączonego funkcją include pliku b.inc w skrypcie. Jednakże wewnątrz funkcji zdefiniowanych samodzielnie zmienne mają zasięg lokalny. Każda zmienna użyta wewnątrz funkcji jest domyślnie ograniczona do zasięgu lokalnego funkcji. Na przykład:
<?php
$a = 1; /* zasięg globalny */
function test()
{
echo $a; /* odwołanie do zmiennej o zasięgu lokalnym */
}
test();
?>
Ten skrypt nie wyświetli niczego, ponieważ instrukcja echo odwołuje się do zmiennej lokalnej $a, której jak dotąd nie została przypisana żadna wartość. Można tu zauważyć różnicę w stosunku do języka C, gdzie zmienne globalne są zawsze dostępne wewnątrz definicji funkcji, o ile nie zostały nadpisane przez lokalną definicję zmiennej. Może to spowodować problem, że ktoś może nieodwracalnie zmienić wartość zmiennej globalnej. W PHP zmienne globalne muszą być jawnie określone jako globalne wewnątrz funkcji, w której mają być użyte, do czego używamy słowa kluczowego global.
polecenie global
Najpierw, przykład użycia global:
Przykład #1 Używanie polecenia global
<?php
$a = 1;
$b = 2;
function Suma()
{
global $a, $b;
$b = $a + $b;
}
Suma();
echo $b;
?>
Powyższy skrypt wyświetli wynik "3". Przez zadeklarowanie wewnątrz funkcji globalności zmiennych $a i $b, wszystkie odwołania do tych zmiennych będą odnosiły się do ich globalnych wersji. Nie ma żadnych ograniczeń w ilości zmiennych globalnych, na których chcemy operować wewnątrz funkcji.
Drugim sposobem uzyskania dostępu do zmiennych globalnych wewnątrz funkcji jest użycie specjalnej, zdefiniowanej przez PHP tablicy $GLOBALS. Powyższy przykład można zatem przepisać tak:
Przykład #2 Używanie $GLOBALS zamiast polecenia global
<?php
$a = 1;
$b = 2;
function Suma()
{
$GLOBALS['b'] = $GLOBALS['a'] + $GLOBALS['b'];
}
Suma();
echo $b;
?>
Tablica $GLOBALS jest asocjacyjną tablicą, w której nazwa zmiennej jest kluczem, a zawartość zmiennej wartością komórki tablicy. Zauważ, że $GLOBALS jest dostępna z każdego miejsca, ponieważ $GLOBALS jest tablicą superglobalną. Poniżej przykład demonstrujący moc superglobali:
Przykład #3 Przykład demonstrujący superglobale i zasięg zmiennych
<?php
function test_global()
{
// Większość predefiniowanych zmiennych nie jest "super i wymaga
// 'global', by być dostępnymi w zasięgu lokalnym funkcji.
global $HTTP_POST_VARS;
echo $HTTP_POST_VARS['name'];
// Superglobale są dostępne z każdego miejsca
// i nie wymagają 'global'. Superglobale udostępniono
// wraz z PHP 4.1.0, a HTTP_POST_VARS jest
// uważane za przestarzałe.
echo $_POST['name'];
}
?>
Używanie zmiennych statycznych
Jeszcze jedną ważną rzeczą, związaną z zasięgiem zmiennych jest zmienna statyczna (ang. static variable). Zmienna statyczna może mieć wyłącznie zasięg lokalny, ale nie traci swojej wartości, kiedy program opuści ten zasięg lokalny, w którym dana zmienna statyczna się znajduje. Rozważmy poniższy przykład:
Przykład #4 Przykład ukazujący przydatność zmiennych statycznych
<?php
function test()
{
$a = 0;
echo $a;
$a++;
}
?>
Ta funkcja jest bezużyteczna, gdyż przy każdym jej wywołaniu zmienna $a otrzymuje wartość 0, w związku z czym funkcja stale wyświetla "0". Występująca potem inkrementacja $a++ nie ma żadnego znaczenia, gdyż funkcja się kończy i zmienna $a znika. Aby powyższa funkcja miała jakiś sens, należy zapobiec gubieniu wartości $a, do czego używamy słowa kluczowego static:
Przykład #5 Przykład użycia zmiennych statycznych
<?php
function Test()
{
static $a = 0;
echo $a;
$a++;
}
?>
Teraz, $a jest inicjowana tylko pry pierwszym wywołaniu funkcji a, przy każdym wywołaniu funkcji test(), zostanie wyświetlona wartość zmiennej $a, po czym ta zmienna zostanie inkrementowana.
Zmienne statyczne pozwalają też na wykorzystanie funkcji rekurencyjnych, czyli takich, które wywołują same siebie. Funkcje rekurencyjne należy pisać ostrożnie, gdyż łatwo jest wywołać nieskończoną rekurencję. Musisz być pewny, że masz odpowiednie mechanizmy do zatrzymania rekurencji w jakimś momencie. Poniższa, prosta funkcja rekurencyjnie liczy do 10, używając zmiennej statycznej $licznik, aby wiedzieć, kiedy się zatrzymać:
Przykład #6 Zmienne statyczne w funkcjach rekurencyjnych
<?php
function test()
{
static $licznik = 0;
$licznik++;
echo $licznik;
if ($licznik < 10) {
test();
}
$licznik--;
}
?>
Informacja:
Zmienne statyczne mogą być deklarowane, tak jak w powyższym przykładzie. Próba przypisania wartości do tego typu zmiennych, poprzez wynik jakiegoś wyrażenia, spowoduje błąd składni (ang. Parse error).
Przykład #7 Deklaracja zmiennych statycznych
<?php
function foo(){
static $int = 0; // prawidłowo
static $int = 1+2; // błąd (w rzeczywistości to jest wyrażenie)
static $int = sqrt(121); // błąd (to również jest wyrażenie)
$int++;
echo $int;
}
?>
Referencje do zmiennych statycznych i globalnych
Silnik Zend 1 (ang. Zend Engine 1) napędzający PHP4, implementuje modyfikatory statyczny oraz globalny dla zmiennych, pod względem referencji. Na przykład, w rzeczywistości globalna zmienna wprowadzona wewnątrz zasięgu funkcji z wyrażeniem global na dziś dzień tworzy referencję do zmiennej globalnej. Takie zachowanie może prowadzić do nieoczekiwanych sytuacji, czego dowodzi poniższy przykład:
<?php
function test_global_ref() {
global $obj;
$obj = &new stdclass;
}
function test_global_noref() {
global $obj;
$obj = new stdclass;
}
test_global_ref();
var_dump($obj);
test_global_noref();
var_dump($obj);
?>
Wykonanie tego przykładu da następujące wyniki:
NULL
object(stdClass)(0) {
}
Podobna sytuacja dotyczy deklaracji static. Referencje nie są magazynowane statycznie:
<?php
function &get_instance_ref() {
static $obj;
echo 'Obiekt statyczny: ';
var_dump($obj);
if (!isset($obj)) {
// Przypisanie referencji do zmiennej statycznej.
$obj = &new stdclass;
}
$obj->property++;
return $obj;
}
function &get_instance_noref() {
static $obj;
echo 'Obiekt statyczny: ';
var_dump($obj);
if (!isset($obj)) {
// Przypisanie do obiektu zmiennej statycznej
$obj = new stdclass;
}
$obj->property++;
return $obj;
}
$obj1 = get_instance_ref();
$still_obj1 = get_instance_ref();
echo "\n";
$obj2 = get_instance_noref();
$still_obj2 = get_instance_noref();
?>
Wykonanie tego przykładu da następujące wyniki:
Obiekt statyczny: NULL
Obiekt statyczny: NULL
Obiekt statyczny: NULL
Obiekt statyczny: object(stdClass)(1) {
["property"]=>
int(1)
}
Ten przykład pokazuje, że podczas przypisywania referencji do zmiennej statycznej, nie następuje zapamiętanie, gdy wywołasz funkcję &get_instance_ref() po raz drugi.
Zmienne zmienne
W niektórych przypadkach jest wygodne, by móc użyć zmiennej o zmiennej nazwie. To znaczy zmiennej, której nazwa może być zmieniana dynamicznie. Zwykła zmienna jest ustawiana wyrażeniem jak poniżej:
<?php
$a = "witaj";
?>
Zmienna zmienna pobiera wartość jednej zmiennej i traktuje ją jako nazwę innej. W powyższym przykładzie, witaj, może stać się nazwą zmiennej, dzięki użyciu dwóch znaków dolara, tzn.
<?php
$$a = "świecie";
?>
W tym momencie dwie zmienne zostały zdefiniowane i umieszczone w drzewie symbolicznym PHP: $a zawierająca "witaj" i $witaj zawierająca "świecie". Zatem poniższy zapis:
<?php
echo "$a ${$a}";
?>
znaczy to samo, co:
<?php
echo "$a $witaj";
?>
tzn. obydwa wyświetlą: witaj świecie.
Aby używać zmiennych zmiennych jako tablic, trzeba wyjaśnić pewną niejasność. Mianowicie, jeśli napiszesz $$a[1], parser musi wiedzieć, czy chesz użyć $a[1] jako nazwy zmiennej, czy $$a jako nazwy tablicy, której rekord [1] cię interesuje. W tym przypadku należy zastosować odrębną składnię: ${$a[1]} dla pierwszego przypadku a ${$a}[1] dla drugiego.
Zauważ, że zmienne zmienne nie mogą być używane z Tablicami superglobalnymi PHP, wewnątrz funkcji, czy metod klas. Zmienna $this jest także specjalną zmienną, dla której referencje dynamiczne nie są dozwolone.
Zmienne ze źródeł zewnętrznych
Formularze HTML (GET i POST)
Kiedy do skryptu PHP zostanie wysłany formularz, informacja z niego jest automatycznie dostępna w skrypcie. Istnieje wiele sposobów na uzyskanie tych informacji, dla przykładu:
Przykład #1 Prosty formularz HTML
<form action="foo.php" method="post">
Imie: <input type="text" name="imie" /><br />
Email: <input type="text" name="email" /><br />
<input type="submit" name="submit" value="Wyslij!" />
</form>
W zależności od twoich szczególnych ustawień i osobistych upodobań, istnieje wiele sposobów dostępu do danych z twoich formularzy HTML. Oto kilka przykładów:
Przykład #2 Dostęp do informacji z prostego formularza HTML (wysłanego metodą POST)
<?php
// Możliwe od PHP 4.1.0
echo $_POST['imie'];
echo $_REQUEST['imie'];
import_request_variables('p', 'p_');
echo $p_imie;
// Niedostępne od PHP 6. Od PHP 5.0.0, te długie predefiniowane
// zmienne mogą być niedostępne z włączoną opcją register_long_arrays.
echo $HTTP_POST_VARS['imie'];
// Dostępne, jeśli opcja register_globals jest włączona - "on". Począwszy od
// PHP 4.2.0 domyślna wartość opcji register_globals to off.
// Nie jest zalecane poleganie na tej metodzie.
echo $imie;
?>
Przesyłanie danych z formularza metodą GET jest podobne, z takim wyjątkiem, że użyjesz zmienną predefiniowaną odpowiednią dla tej metody, zamiast poprzedniej. GET także odnosi się do tzw. QUERY_STRING (informacje w adresie URL, po znaku '?'). Tak więc, dla przykładu, http://www.example.com/test.php?id=3 zawiera dane dla metody GET, dostępne poprzez $_GET['id']. Zobacz także $_REQUEST oraz import_request_variables().
Informacja:
Tablice superglobalne, takie jak $_POST i $_GET, zostały udostępnione w PHP 4.1.0
Jak widać, przed PHP 4.2.0 domyślną wartością opcji register_globals było on. Społeczność PHP jest całkowiie przekonana, by nie polegać na tej opcji; i rzeczywiście najlepiej jest nadać jej wartość off, oraz przystosować do tego kod.
Informacja:
Dyrektywa konfiguracyjna magic_quotes_gpc oddziałuje na zmienne z Get, Post i Cookie. Jeśli jest włączona, tekst (It's "PHP!") automagicznie zmieni się w (It\'s \"PHP!\"). Jest to potrzebne przy wpisywaniu danych do baz danych. Zobacz także addslashes(), stripslashes() i magic_quotes_sybase.
PHP obsługuje także tablice w kontekście zmiennych z formularzy (zajrzyj do FAQ). Można na przykład pogrupować razem powiązane zmienne lub użyć tej możliwości do pobrania wartości z pola wyboru (select). Na przykład, wyślijmy formularz z pliku metodą POST do samego siebie i wyświetlmy te dane:
Przykład #3 Bardziej złożone zmienne w formularzach
<?php
if ($_POST) {
echo '<pre>';
echo htmlspecialchars(print_r($_POST, true));
echo '</pre>';
}
?>
<form action="" method="post">
Nazwisko: <input type="text" name="personal[nazwisko]"><br />
Email: <input type="text" name="personal[email]"><br />
Piwo: <br />
<select multiple name="piwo[]">
<option value="zywiec">Żywiec</option>
<option value="tyskie">Tyskie</option>
<option value="lech">Lech</option>
</select><br />
<input type="submit" value="Wyślij mnie!" />
</form>
Nazwy zmiennych dla SUBMIT w postaci obrazka
Przy tworzeniu formularza, można użyć obrazka, zamiast standardowego przycisku Wyślij, za pomocą takiego znacznika:
<input type="image" src="obrazek.gif" name="sub" />
Kiedy użytkownik kliknie gdzieś na obrazku, formularz, którego to dotyczy, zostanie wysłany do serwera z dwiema dodatkowymi zmiennymi, sub_x i sub_y. Zawierają one współrzędne miejsca kliknięcia na obrazek. Można przy tym zauważyć, że na razie w nazwach zmiennych znajduje się kropka zamiast podkreślnika, ale PHP konwertuje kropkę na podkreślnik automatycznie.
Ciasteczka HTTP
PHP bez problemu obsługuje ciasteczka HTTP, takie jak zdefiniowano w » Specyfikacji Netscape'a. Ciasteczka są mechanizmem przechowywania informacji w przeglądarce klienta w celu śledzenia lub identyfikowania stałych bywalców strony. Ciasteczka ustawia się za pomocą funkcji setcookie(). Ciasteczka są częścią nagłówka HTTP, więc funkcja SetCookie musi być wywołana zanim jakakolwiek inna informacja zostanie wysłana do przeglądarki. Takie samo ograniczenie dotyczy funkcji header(). Dane z ciasteczek są wówczas dostępne w odpowiednich tablicach danych cookies, takich jak $_COOKIE, $HTTP_COOKIE_VARS jak również $_REQUEST. Zobacz także stronę dotyczącą funkcji setcookie() aby poznać więcej informacji i przykładów.
Jeśli chcesz przypisać wiele wartości do jednego ciasteczka, możesz po prostu złączyć je w tablicę. Na przykład:
<?php
setcookie("MojeCiasteczko[foo]", 'Test 1', time()+3600);
setcookie("MojeCiasteczko[bar]", 'Test 2', time()+3600);
?>
Spowoduje to stworzenie dwóch oddzielnych ciasteczek, mimo, iż MojeCiasteczko będzie teraz pojedynczą tablicą w twoim skrypcie. Jeśli chcesz ustawić tylko jedno ciasteczko z wieloma wartościami, rozważ możliwość użycia przedtem funkcji serialize() lub explode() na wartości.
Pamiętaj, że wysłane ciasteczko zastąpi wcześniejsze ciasteczko o tej nazwie, o ile ścieżka lub domena nie są różne. Na przykład dla koszyka do zakupów możesz potrzebować licznika a jego wartość stale przekazywać dalej, tzn.
Przykład #4 Przykład użycia funkcji setcookie()
<?php
if (isset($_COOKIE['ile'])) {
$ile = $_COOKIE['ile'] + 1;
} else {
$ile = 1;
}
setcookie('ile', $ile, time()+3600);
setcookie("Cart[$ile]", $pozycja, time()+3600);
?>
Kropki w nazwach odbieranych zmiennych
PHP normalnie nie zmienia nazw zmiennych podczas przekazywania ich do skryptu. Jednakże należy pamiętać, że kropka "." nie jest poprawnym znakiem w nazwie zmiennej PHP. Dlaczego? Proszę spojrzeć na to:
<?php
$varname.ext; /* niepoprawna nazwa zmiennej */
?>
Warto zatem wiedzieć, że PHP automatycznie zastąpi podkreślnikiem "_" każdą kropkę w nazwie każdej odebranej zmiennej.
Określanie typów zmiennych
Ponieważ PHP samodzielnie określa typy zmiennych i konwertuje je (zasadniczo) jak potrzeba, nie zawsze jest jasne, jakiego typu jest dana zmienna w danym momencie. PHP zawiera kilka funkcji do określania typów zmiennych, takich jak: gettype(), is_array(), is_float(), is_int(), is_object() i is_string(). Zobacz także rozdział o Typach.
Stałe
Spis treści
Stałe są to nazwy, identyfikujące proste wartości. Jak sama nazwa wskazuje, nie mogą się one zmieniać w trakcie wykonywania skryptu (wyjątkiem są magiczne stałe, które własciwie nie sa stałymi). W nazwach stałych domyślnie rozróżniana jest wielkość liter. Zgodnie z ogólnie przyjętą konwencją, nazwy stałych zawsze pisane sa wielkimi literami.
Nazwy stałych obowiązują identyczne zasady, jak w przypadku wszystkich innych etykiet. Poprawna nazwa stałej zaczyna się od litery lub podkreślnika, po których następuje dowolna ilość liter, cyfr i podkreślników. Jako wyrażenie regularne, określone zostałoby to następująco: [a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*
Zobacz także Userland Naming Guide.
Przykład #1 Poprawne i niepoprawne nazwy stałych
<?php
// Poprawne nazwy stałych
define("FOO", "something");
define("FOO2", "something else");
define("FOO_BAR", "something more");
// Niepoprawne nazwy stałych
define("2FOO", "something");
// Pomimo tego, że poniższy zapis jest poprawny, powinno się go unikać:
// PHP może kiedyś zawierać magiczną stałą,
// która zepsuje Twój skrypt
define("__FOO__", "something");
?>
Informacja: Dla naszych celów, literami są a-z, A-Z, oraz znaki ASCII z przedziału od 127 do 255 (0x7f-0xff).
Podobnie jak superglobals, zasięg stałych jest globalny. Można sie odwoływać do nich w każdym miejscu pliku, nie przejmując sie zasięgiem. Więcej informacji na ten temat znajdziesz w rozdziale pt. zasięg zmiennych.
Składnia
Możesz zdefiniować stałą, używając funkcji define(). Raz zdefiniowana stała nie może byc zmieniona ani usunięta.
Stałe mogą zawierać jedynie dane skalarne (boolean, integer, float oraz string) Stałe nie mogą być typu resource.
Wartość stałej otrzymujemy, używając jej nazwy. W przeciwieństwie do zmiennych, nazw stałych nie poprzedzamy znakiem $. Możesz także użyć funkcji constant() do odczytania wartości stałej, jeśli chcesz wygenerować jej nazwę dynamicznie. Aby uzyskać listę wszystkich zdefiniowanych stałych, użyj get_defined_constants().
Informacja: Stałe i zmienne globalne operują w różnych przestrzeniach nazw. Oznacza to, że na przykład
TRUEi $TRUE oznaczają co innego.
Jeśli używasz niezdefiniowanej stałej, PHP traktuje to, jak gdybyś chciał użyć nazwy stałej jako wartości typu string (STAŁA a "STAŁA"). Błąd typu E_NOTICE zostanie wywołany, kiedy to się stanie. Przeczytaj także, dlaczego $foo[bar] jest niepoprawne (jeśli nie zdefiniujesz bar jako stałej). Chcąc sprawdzić, czy dana stała istnieje, użyj funkcji defined().
Oto różnice pomiędzy stałymi i zmiennymi:
- Nazwy stałych nie są poprzedzone znakiem dolara ($);
- Stałe mogą zostać zdefiniowane jedynie przy użyciu funkcji define() a nie poprzez zwykłe przypisanie;
- Stałe mogą być definiowane i używane wszędzie, niezależnie od zasięgu zmiennych;
- Stałe nie mogą być zmieniane ani usuwane jeśli raz zostały ustawione ; oraz
- Stałe mogą zawierać jedynie wartości skalarne.
Przykład #1 Definiowanie stałych
<?php
define("CONSTANT", "Hello world.");
echo CONSTANT; // wypisuje "Hello world."
echo Constant; // wypisuje "Constant" i wywoułuje ostrzeżenie.
?>
Zobacz także Stałe Klas.
Magiczne stałe
PHP zapewnia szeroki zakres predefiniowanych stałych każdemu skryptowi, który jest uruchamiany. Wiele z tych stałych jest jednak dostępnych dzieki różnym rozszerzeniom i można z nich korzystać jedynie, kiedy te rozszerzenia sa dostępne przez dynamiczne załadowanie, badź też zostały wkompilowane.
Istnieje siedem magicznych stałych, które zmieniają sie w zależności
od tego, gdzie są użyte. Na przykład, wartość
__LINE__ zależy od linii, w której ta
stała została użyta. Nazwy tych magicznych stałych
są niezależne od wielkości liter:
| Nazwa | Opis |
|---|---|
__LINE__ |
Aktualna linia pliku. |
__FILE__ |
Pełna scieżka i nazwa pliku. Jeśli użyta wewnątrz dołączonego pliku,
jego nazwa jest zwracana.
Od PHP 4.0.2, __FILE__zawsze zawiera
bezwzględną scieżkę z rozwiązanymi dowiązaniami symbolicznymi, podczas kiedy w starszych wersjach
czasem zawierała scieżkę względną.
|
__DIR__ |
Nazwa katalogu pliku. Jeśli użyta wewnątrz dołączonego pliku, zwraca nazwę jego katalogu. Odpowiada dirname(__FILE__). Zwracana nazwa nie zawiera końcowego ukośnika, chyba że jest to katalog root. (Dodano w PHP 5.3.0.) |
__FUNCTION__ |
Nazwa funkcji. (Dodano w PHP 4.3.0) W PHP 5 ta stała zwraca nazwę funkcji tak jak ją zadeklarowano (z uwzględnieniem wielkości liter), podczas kiedy w PHP 4 zwracana wartość zawiera jedynie małe litery. |
__CLASS__ |
Nazwa klasy. (Dodano w PHP 4.3.0) W PHP 5 ta stała zwraca nazwę klasy tak jak ją zadeklarowano (z uwzględnieniem wielkości liter), podczas kiedy w PHP 4 zwracana wartość zawiera jedynie małe litery. |
__METHOD__ |
Nazwa metody. (Dodano w PHP 5.0.0) Nazwa metody zwracana jest tak jak ją zadeklarowano (z uwzględnieniem wielkości liter). |
__NAMESPACE__ |
Nazwa aktualnej przestrzeni nazw (z uwzględnieniem wielkości liter). Ta stała definiowana jest w czasie kompilacji (Dodano w PHP 5.3.0). |
Zobacz także get_class(), get_object_vars(), file_exists() i function_exists().
Wyrażenia
Wyrażenia są naważniejszymi elementami składowymi PHP. W PHP prawie wszystko co napiszesz jest wyrażeniem. Najprostszą i najdokładniejszą definicją wyrażenia jest "wszystko co ma wartość".
Najbardziej podstawową formą wyrażeń są stałe i zmienna. Jeśli napiszesz "$a = 5" przypisujesz '5' do '$a'. '5' ma oczywiście wartość 5, lub innymi słowy '5' jest wyrażeniem o wartości 5 (w tym przypadku, '5' jest stałą liczbą całkowitą).
Po tym przypisaniu możesz się spodziwać, że wartością $a jest także 5, więc jeśli napiszesz "$b = $a" możesz się spodziewać, że będzie to równoznaczne z napisaniem "$b = 5". Innymi słowy, $a jest wyrażeniem o wartości 5. Jeśli wszystko działa prawidłowo, wszystko będzie się dziać tak jak napisano wyżej.
Trochę bardziej złożonymi przykładami wyrażeń są funkcje. Przyjrzyj się poniższej funkcji:
<?php
function foo ()
{
return 5;
}
?>
Zakładając, że zapoznałeś się z koncepcją funkcji (jeśli nie, przejrzyj najpierw rozdział o funkcjach), możesz założyć, że napisanie $c = foo() jest równoznaczne z napisaniem $c = 5, i masz racię. Funkcje są wyrażeniami o wartości którą zwracają. Ponieważ foo() zwraca 5, wartością wyrażenia 'foo()' jest 5. Zazwyczaj funkcje nie zwracają statycznej wartości, ale coś obliczają.
Oczywiście wartości w PHP nie muszą być liczbami całkowitymi, i bardzo często nie są nimi. PHP obsługuje 3 skalarne warotści danych: wartości całkowite (integer), wartości rzeczywiste (float i ciągi znaków (string) (wartości skalarne to takie, których nie możesz 'rozbić' na mniejsze kawałki, w przeciwieństwie do np. tablic). PHP obsługuje także dwa złożone (nieskalarne) typy danych: tablice i obiekty. Każdą z tych wartości można przypisać do zmiennych lub może być zwrócona przez funkcję.
PHP rozwija wyrażenia prawdopodobnie znacznie bardziej, niż wiele innych języków programowania. PHP jest językiem wyrażeń, co oznacza że prawie wszystko w nim jest wyrażeniem. Przyjrzyj się przykładowi, który już analizowaliśmy, '$a = 5'. Łatwo jest zauważyć, że są tu dwie wartości. Wartość stałej całkowitej '5', a także wartość $a, która zostanie zamieniona na 5. Ale tak naprawdę jest tu jeszcze jedna wartość, którą jest wartość operacji przypisania. Przypisanie przyjmuje wartość przypisywanej wartości, w tym przypadku 5. W praktyce oznacza to, że '$a = 5', niezależnie co to robi, jest wyrażeniem o wartości 5. Wynika z tego, że napisanie '$b = ($a = 5)' jest równoznaczne napisaniu '$a = 5; $b = 5;' (średnik oznacza koniec instrukcji). Ponieważ przypisania są przetwarzane od prawej do lewej, możesz także napisać '$b = $a = 5'.
Kolejnym dobrym przykładem korzystania z wyrażeń jest pre- i postinkrementacja, a także dekrementacja. Użytkownicy PHP i wielu innych języków mogą być już zaznajomieni z notacją zmienna++ i zmienna--. Są to operatory inkrementacji i dekrementacji. W PHP/FI 2 instrukcja '$a++' nie ma wartości (nie jest wyrażeniem), więc nie możesz jej przypisać lub użyć w jakikolwiek sposób. PHP rozszerza możliwości inkrementacji/dekrementacji robiąc także z nich wyrażenia, podobnie jak w C. W PHP, tak jak w C, sa dwa typy inkrementacji: preinkrementacja i postinkrementacja. I pre- i postinkrementacja zwiększają wartość zmiannej, więc efekt w stosunku do zmiennej jest taki sam. Różnica jest w wartości wyrażenia inkrementacji. Preinkrementacja, która jest oznaczana jako '++$zmienna', zwraca zwiększoną wartość (PHP zwiększa zmienną przed odczytaniem wartości, dlatego nazywa się to 'pre-inkrementacją'). Postinkrementacja, która jest oznaczana jako '$zmienna++', zwraca orginalną wartość $zmienna przed zwiększeniem jej wartości (PHP zwiększa wartość po odczytaniu jej wartości, stąd nazwa 'post-inkrementacja').
Popularnym typem wyrażeń są porównania. Wyrażenia te
zwracają wartość FALSE lub TRUE. PHP
obsługuje > (większy), >= (większy lub równy), == (równy), != (nie
równy), < (mniejszy) i <= (mniejszy lub równy). Język obsługuje
także zbiór operatorów ścisłego porównania: === (równy i tego samego typu)
i !== (nie równy lub różnego typu). Wyrażenia te są powszechnie używane
przy sprawdzaniu warunków, jak na przykład instrukcje
if.
Ostatnim przykładem, którym będziemy się tu zajmować są połączone wyrażenia operacji i przypisania. Już wiesz, że jeśli chcesz zwiększyć wartość zmiennej $a o 1, możesz po prostu napisać '$a++' lub '++$a'. Ale co jeśli chcesz dodać do niej więcej niż jeden, na przykład 3? Mógłbyś napisać wielokrotnie '$a++', ale nie jest to sposób ani efektywny ani wygodny. Częściej spotykane jest używanie instrukcji '$a = $a + 3'. '$a + 4' zwraca wartość zmiennej $a plus 3, która jest przypisywana z powrotem do $a, co oznacza zwiększenie wartości zmiennej $a o 3. W PHP, tak jak kilku innych językach jak na przykład C, możesz napisać to krócej, co z czasem stanie się także bardziej przejrzyste i łatwiejsze do zrozumienia. Dodanie 4 do bieżącej wartości $a może być zapisane jako '$a += 4'. Oznacza to dokładnie "weź wartość $a, dodaj do niej 3 i przypisz ją z powrotem do $a". Oprócz bycia krótszą i bardziej przejrzystą, instrukcja ta jest także szybsza w wykonaniu. Wartość '$a += 5', tak jak wartość zwykłego przypisania, jest przypisywaną wartością. Zauważ, że NIE jest to 4, ale połączona warotść $a i 4 (jest to wartość która jest przypisywana do $a). Dowolne dwuoperandowe operatory mogą być użyte w trybie operacji-przypisania, na przykład '$a -= 5' (odejmij 5 od wartości $a), '$b *= 7' (pomnóż wartość $b przez 7), itp.
Jest jeszcze jedno wyrażenie, które może się wydać dziwne jeśli nie widziałeś go w innych językac, trójoperandowy operator warunkowy:
<?php
$pierwsze ? $drugie : $trzecie
?>
Jeśli wartością pierwszego podwyrażenia jest TRUE (rózna od zera), to
zwracany jest drugie podwyrażanie, i jest to wynik wyrażenia warunkowego.
W przeciwnym wypadku, zwracana jest wartość trzeciego podwyrażenia.
Poniższy przykład powinien pomóc w lepszym zrozumieniu pre- i postinkrementacji i ogólnie koncepcji wyrażeń:
<?php
function double($i)
{
return $i*2;
}
$b = $a = 5; /* przypisz wartość pięc do zmiennej $a i $b */
$c = $a++; /* postinkrementuj, przypisz początkową wartość
$a (5) do $c */
$e = $d = ++$b; /* preinkrementuj, przypisz zwiększoną wartość
$b (6) to $d i $e */
/* w tym momencie i $d i $e są równe 6 */
$f = double($d++); /* przypisz podwojoną wartość $d przed
inkrementacji, 2*6 = 12 do $f */
$g = double(++$e); /* przypisz podwojoną wartość $e po
inkrementacji, 2*7 = 14 do $g */
$h = $g += 10; /* na początku $g jest zwiększane o 10 i przyjmuje
wartość 24; wartość przypisania (24) jest później
przypisywana do $h, które przyjmuje wartość 24. */
?>
Na początku rozdziału powiedzieliśmy, że będziemy opisywać różne typy instrukcji, i tak jak obiecywaliśmy, wyrażenia mogą być instrukcjami. Jednakże nie każde wyrażenie jest instrukcją. Niektóre wyrażenia mogą być instrukcjami. Ten przypadek ma postać 'wyrażenie' ';', czyli wyrażenie a po nim średnik. W '$b=$a=5;', $a=5 jest poprawnym wyrażeniem, ale nie jest instrukcją. Jednakże '$b=$a=$b;' jest poprawną intrukcją.
Ostatnią rzeczą wartą uwagi jest wartość prawdy wyrażeń. W wielu
przypadkach, głównie przy sprawdzaniu warunkow i w pętlach, nie interesuje
cię wartość wyrażenia, ale tylko czy oznacza TRUE czy FALSE.
Stałe TRUE i FALSE (niezależne od wielkości znaków) są dwiema
możliwymi wartościami logicznymi. Kiedy to konieczne, wyrażenie jest
automatycznie konwertowane na typ boolean. Zobacz
rozdział o rzutowaniu typów
jeśli interesują cię szczegóły jak to jest przeprowadzane.
PHP dostarcza pełnej i potężnej implementacji wyrażeń i całkowita ich dokumentacja przekracza ramy tego podręcznika. Powyższe przykłady powinny dać ci ogólne pojęcie czym są wyrażenia i jak możesz konstruować przydatne wyrażenia. Przez resztę podręcznika będziemy pisać expr aby oznaczyć dowolne poprawne wyrażenie PHP.
Operators
Spis treści
- Operator Precedence
- Arithmetic Operators
- Assignment Operators
- Bitwise Operators
- Comparison Operators
- Error Control Operators
- Execution Operators
- Incrementing/Decrementing Operators
- Logical Operators
- String Operators
- Array Operators
- Type Operators
An operator is something that takes one or more values (or expressions, in programming jargon) and yields another value (so that the construction itself becomes an expression).
Operators can be grouped according to the number of values they take. Unary operators take only one value, for example ! (the logical not operator) or ++ (the increment operator). Binary operators take two values, such as the familiar arithmetical operators + (plus) and - (minus), and the majority of PHP operators fall into this category. Finally, there is a single ternary operator, ? :, which takes three values; this is usually referred to simply as "the ternary operator" (although it could perhaps more properly be called the conditional operator).
A full list of PHP operators follows in the section Operator Precedence. This also explains operator Presedence and Associativity, which govern exactly how expressions containing several different operators are evaluated.
Operator Precedence
The precedence of an operator specifies how "tightly" it binds two expressions together. For example, in the expression 1 + 5 * 3, the answer is 16 and not 18 because the multiplication ("*") operator has a higher precedence than the addition ("+") operator. Parentheses may be used to force precedence, if necessary. For instance: (1 + 5) * 3 evaluates to 18.
When operators have equal precedence, their associativity decides whether they are evaluated starting from the right, or starting from the left - see the examples below.
The following table lists the operators in order of precedence, with the highest-precedence ones at the top. Operators on the same line have equal precedence, in which case associativity decides the order of evaluation.
| Associativity | Operators | Additional Information |
|---|---|---|
| non-associative | clone new | clone and new |
| left | [ | array() |
| non-associative | ++ -- | increment/decrement |
| right | ~ - (int) (float) (string) (array) (object) (bool) @ | types |
| non-associative | instanceof | types |
| right | ! | logical |
| left | * / % | arithmetic |
| left | + - . | arithmetic i string |
| left | << >> | bitwise |
| non-associative | < <= > >= <> | comparison |
| non-associative | == != === !== | comparison |
| left | & | bitwise i references |
| left | ^ | bitwise |
| left | | | bitwise |
| left | && | logical |
| left | || | logical |
| left | ? : | ternary |
| right | = += -= *= /= .= %= &= |= ^= <<= >>= => | assignment |
| left | and | logical |
| left | xor | logical |
| left | or | logical |
| left | , | many uses |
For operators of equal precedence, left associativity means that evaluation proceeds from left to right, and right associativity means the opposite.
Przykład #1 Associativity
<?php
$a = 3 * 3 % 5; // (3 * 3) % 5 = 4
$a = true ? 0 : true ? 1 : 2; // (true ? 0 : true) ? 1 : 2 = 2
$a = 1;
$b = 2;
$a = $b += 3; // $a = ($b += 3) -> $a = 5, $b = 5
// mixing ++ and + produces undefined behavior
$a = 1;
echo ++$a + $a++; // may print 4 or 5
?>
Informacja:
Although = has a lower precedence than most other operators, PHP will still allow expressions similar to the following: if (!$a = foo()), in which case the return value of foo() is put into $a.
Arithmetic Operators
Remember basic arithmetic from school? These work just like those.
| Example | Name | Result |
|---|---|---|
| -$a | Negation | Opposite of $a. |
| $a + $b | Addition | Sum of $a and $b. |
| $a - $b | Subtraction | Difference of $a and $b. |
| $a * $b | Multiplication | Product of $a and $b. |
| $a / $b | Division | Quotient of $a and $b. |
| $a % $b | Modulus | Remainder of $a divided by $b. |
The division operator ("/") returns a float value unless the two operands are integers (or strings that get converted to integers) and the numbers are evenly divisible, in which case an integer value will be returned.
Operands of modulus are converted to integers (by stripping the decimal part) before processing.
The result of the modulus operator % has the same sign as the dividend — that is, the result of $a % $b will have the same sign as $a. For example:
<?php
echo (5 % 3)."\n"; // prints 2
echo (5 % -3)."\n"; // prints 2
echo (-5 % 3)."\n"; // prints -2
echo (-5 % -3)."\n"; // prints -2
?>
See also the manual page on Math functions.
Assignment Operators
The basic assignment operator is "=". Your first inclination might be to think of this as "equal to". Don't. It really means that the left operand gets set to the value of the expression on the right (that is, "gets set to").
The value of an assignment expression is the value assigned. That is, the value of "$a = 3" is 3. This allows you to do some tricky things:
<?php
$a = ($b = 4) + 5; // $a is equal to 9 now, and $b has been set to 4.
?>
For arrays, assigning a value to a named key is performed using the "=>" operator. The precedence of this operator is the same as other assignment operators.
In addition to the basic assignment operator, there are "combined operators" for all of the binary arithmetic, array union and string operators that allow you to use a value in an expression and then set its value to the result of that expression. For example:
<?php
$a = 3;
$a += 5; // sets $a to 8, as if we had said: $a = $a + 5;
$b = "Hello ";
$b .= "There!"; // sets $b to "Hello There!", just like $b = $b . "There!";
?>
Note that the assignment copies the original variable to the new one (assignment by value), so changes to one will not affect the other. This may also have relevance if you need to copy something like a large array inside a tight loop.
An exception to the usual assignment by value behaviour within PHP occurs with objects, which are assigned by reference in PHP 5. Objects may be explicitly copied via the clone keyword.
Assignment by Reference
Assignment by reference is also supported, using the "$var = &$othervar;" syntax. Assignment by reference means that both variables end up pointing at the same data, and nothing is copied anywhere.
Przykład #1 Assigning by reference
<?php
$a = 3;
$b = &$a; // $b is a reference to $a
print "$a\n"; // prints 3
print "$b\n"; // prints 3
$a = 4; // change $a
print "$a\n"; // prints 4
print "$b\n"; // prints 4 as well, since $b is a reference to $a, which has
// been changed
?>
As of PHP 5, the new
operator returns a reference automatically, so assigning the result of
new by reference results
in an E_DEPRECATED message in PHP 5.3 and later, and
an E_STRICT message in earlier versions.
For example, this code will result in a warning:
<?php
class C {}
/* The following line generates the following error message:
* Deprecated: Assigning the return value of new by reference is deprecated in...
*/
$o = &new C;
?>
More information on references and their potential uses can be found in the References Explained section of the manual.
Bitwise Operators
Bitwise operators allow evaluation and manipulation of specific bits within an integer.
| Example | Name | Result |
|---|---|---|
$a & $b |
And | Bits that are set in both $a and $b are set. |
$a | $b |
Or (inclusive or) | Bits that are set in either $a or $b are set. |
$a ^ $b |
Xor (exclusive or) | Bits that are set in $a or $b but not both are set. |
~ $a |
Not | Bits that are set in $a are not set, and vice versa. |
$a << $b |
Shift left | Shift the bits of $a $b steps to the left (each step means "multiply by two") |
$a >> $b |
Shift right | Shift the bits of $a $b steps to the right (each step means "divide by two") |
Bit shifting in PHP is arithmetic. Bits shifted off either end are discarded. Left shifts have zeros shifted in on the right while the sign bit is shifted out on the left, meaning the sign of an operand is not preserved. Right shifts have copies of the sign bit shifted in on the left, meaning the sign of an operand is preserved.
Use parentheses to ensure the desired precedence. For example, $a & $b == true evaluates the equivalency then the bitwise and; while ($a & $b) == true evaluates the bitwise and then the equivalency.
Be aware of data type conversions. If both the left-hand and right-hand parameters are strings, the bitwise operator will operate on the characters' ASCII values.
PHP's error_reporting ini setting uses bitwise values,
providing a real-world demonstration of turning
bits off. To show all errors, except for notices,
the php.ini file instructions say to use:
E_ALL & ~E_NOTICE
This works by starting with E_ALL: 00000000000000000111011111111111 Then taking the value of E_NOTICE... 00000000000000000000000000001000 ... and inverting it via ~: 11111111111111111111111111110111 Finally, it uses AND (&) to find the bits turned on in both values: 00000000000000000111011111110111
Another way to accomplish that is using XOR (^)
to find bits that are on in only one value or the other:
E_ALL ^ E_NOTICE
error_reporting can also be used to demonstrate turning bits on.
The way to show just errors and recoverable errors is:
E_ERROR | E_RECOVERABLE_ERROR
This process combines E_ERROR 00000000000000000000000000000001 and 00000000000000000001000000000000 using the OR (|) operator to get the bits turned on in either value: 00000000000000000001000000000001
Przykład #1 Bitwise AND, OR and XOR operations on integers
<?php
/*
* Ignore the top section,
* it is just formatting to make output clearer.
*/
$format = '(%1$2d = %1$04b) = (%2$2d = %2$04b)'
. ' %3$s (%4$2d = %4$04b)' . "\n";
echo <<<EOH
--------- --------- -- ---------
result value op test
--------- --------- -- ---------
EOH;
/*
* Here are the examples.
*/
$values = array(0, 1, 2, 4, 8);
$test = 1 + 4;
echo "\n Bitwise AND \n";
foreach ($values as $value) {
$result = $value & $test;
printf($format, $result, $value, '&', $test);
}
echo "\n Bitwise Inclusive OR \n";
foreach ($values as $value) {
$result = $value | $test;
printf($format, $result, $value, '|', $test);
}
echo "\n Bitwise Exclusive OR (XOR) \n";
foreach ($values as $value) {
$result = $value ^ $test;
printf($format, $result, $value, '^', $test);
}
?>
Powyższy przykład wyświetli:
--------- --------- -- --------- result value op test --------- --------- -- --------- Bitwise AND ( 0 = 0000) = ( 0 = 0000) & ( 5 = 0101) ( 1 = 0001) = ( 1 = 0001) & ( 5 = 0101) ( 0 = 0000) = ( 2 = 0010) & ( 5 = 0101) ( 4 = 0100) = ( 4 = 0100) & ( 5 = 0101) ( 0 = 0000) = ( 8 = 1000) & ( 5 = 0101) Bitwise Inclusive OR ( 5 = 0101) = ( 0 = 0000) | ( 5 = 0101) ( 5 = 0101) = ( 1 = 0001) | ( 5 = 0101) ( 7 = 0111) = ( 2 = 0010) | ( 5 = 0101) ( 5 = 0101) = ( 4 = 0100) | ( 5 = 0101) (13 = 1101) = ( 8 = 1000) | ( 5 = 0101) Bitwise Exclusive OR (XOR) ( 5 = 0101) = ( 0 = 0000) ^ ( 5 = 0101) ( 4 = 0100) = ( 1 = 0001) ^ ( 5 = 0101) ( 7 = 0111) = ( 2 = 0010) ^ ( 5 = 0101) ( 1 = 0001) = ( 4 = 0100) ^ ( 5 = 0101) (13 = 1101) = ( 8 = 1000) ^ ( 5 = 0101)
Przykład #2 Bitwise XOR operations on strings
<?php
echo 12 ^ 9; // Outputs '5'
echo "12" ^ "9"; // Outputs the Backspace character (ascii 8)
// ('1' (ascii 49)) ^ ('9' (ascii 57)) = #8
echo "hallo" ^ "hello"; // Outputs the ascii values #0 #4 #0 #0 #0
// 'a' ^ 'e' = #4
echo 2 ^ "3"; // Outputs 1
// 2 ^ ((int)"3") == 1
echo "2" ^ 3; // Outputs 1
// ((int)"2") ^ 3 == 1
?>
Przykład #3 Bit shifting on integers
<?php
/*
* Here are the examples.
*/
echo "\n--- BIT SHIFT RIGHT ON POSITIVE INTEGERS ---\n";
$val = 4;
$places = 1;
$res = $val >> $places;
p($res, $val, '>>', $places, 'copy of sign bit shifted into left side');
$val = 4;
$places = 2;
$res = $val >> $places;
p($res, $val, '>>', $places);
$val = 4;
$places = 3;
$res = $val >> $places;
p($res, $val, '>>', $places, 'bits shift out right side');
$val = 4;
$places = 4;
$res = $val >> $places;
p($res, $val, '>>', $places, 'same result as above; can not shift beyond 0');
echo "\n--- BIT SHIFT RIGHT ON NEGATIVE INTEGERS ---\n";
$val = -4;
$places = 1;
$res = $val >> $places;
p($res, $val, '>>', $places, 'copy of sign bit shifted into left side');
$val = -4;
$places = 2;
$res = $val >> $places;
p($res, $val, '>>', $places, 'bits shift out right side');
$val = -4;
$places = 3;
$res = $val >> $places;
p($res, $val, '>>', $places, 'same result as above; can not shift beyond -1');
echo "\n--- BIT SHIFT LEFT ON POSITIVE INTEGERS ---\n";
$val = 4;
$places = 1;
$res = $val << $places;
p($res, $val, '<<', $places, 'zeros fill in right side');
$val = 4;
$places = (PHP_INT_SIZE * 8) - 4;
$res = $val << $places;
p($res, $val, '<<', $places);
$val = 4;
$places = (PHP_INT_SIZE * 8) - 3;
$res = $val << $places;
p($res, $val, '<<', $places, 'sign bits get shifted out');
$val = 4;
$places = (PHP_INT_SIZE * 8) - 2;
$res = $val << $places;
p($res, $val, '<<', $places, 'bits shift out left side');
echo "\n--- BIT SHIFT LEFT ON NEGATIVE INTEGERS ---\n";
$val = -4;
$places = 1;
$res = $val << $places;
p($res, $val, '<<', $places, 'zeros fill in right side');
$val = -4;
$places = (PHP_INT_SIZE * 8) - 3;
$res = $val << $places;
p($res, $val, '<<', $places);
$val = -4;
$places = (PHP_INT_SIZE * 8) - 2;
$res = $val << $places;
p($res, $val, '<<', $places, 'bits shift out left side, including sign bit');
/*
* Ignore this bottom section,
* it is just formatting to make output clearer.
*/
function p($res, $val, $op, $places, $note = '') {
$format = '%0' . (PHP_INT_SIZE * 8) . "b\n";
printf("Expression: %d = %d %s %d\n", $res, $val, $op, $places);
echo " Decimal:\n";
printf(" val=%d\n", $val);
printf(" res=%d\n", $res);
echo " Binary:\n";
printf(' val=' . $format, $val);
printf(' res=' . $format, $res);
if ($note) {
echo " NOTE: $note\n";
}
echo "\n";
}
?>
Wyświetla następujący przykład na systemach 32 bitowych:
--- BIT SHIFT RIGHT ON POSITIVE INTEGERS --- Expression: 2 = 4 >> 1 Decimal: val=4 res=2 Binary: val=00000000000000000000000000000100 res=00000000000000000000000000000010 NOTE: copy of sign bit shifted into left side Expression: 1 = 4 >> 2 Decimal: val=4 res=1 Binary: val=00000000000000000000000000000100 res=00000000000000000000000000000001 Expression: 0 = 4 >> 3 Decimal: val=4 res=0 Binary: val=00000000000000000000000000000100 res=00000000000000000000000000000000 NOTE: bits shift out right side Expression: 0 = 4 >> 4 Decimal: val=4 res=0 Binary: val=00000000000000000000000000000100 res=00000000000000000000000000000000 NOTE: same result as above; can not shift beyond 0 --- BIT SHIFT RIGHT ON NEGATIVE INTEGERS --- Expression: -2 = -4 >> 1 Decimal: val=-4 res=-2 Binary: val=11111111111111111111111111111100 res=11111111111111111111111111111110 NOTE: copy of sign bit shifted into left side Expression: -1 = -4 >> 2 Decimal: val=-4 res=-1 Binary: val=11111111111111111111111111111100 res=11111111111111111111111111111111 NOTE: bits shift out right side Expression: -1 = -4 >> 3 Decimal: val=-4 res=-1 Binary: val=11111111111111111111111111111100 res=11111111111111111111111111111111 NOTE: same result as above; can not shift beyond -1 --- BIT SHIFT LEFT ON POSITIVE INTEGERS --- Expression: 8 = 4 << 1 Decimal: val=4 res=8 Binary: val=00000000000000000000000000000100 res=00000000000000000000000000001000 NOTE: zeros fill in right side Expression: 1073741824 = 4 << 28 Decimal: val=4 res=1073741824 Binary: val=00000000000000000000000000000100 res=01000000000000000000000000000000 Expression: -2147483648 = 4 << 29 Decimal: val=4 res=-2147483648 Binary: val=00000000000000000000000000000100 res=10000000000000000000000000000000 NOTE: sign bits get shifted out Expression: 0 = 4 << 30 Decimal: val=4 res=0 Binary: val=00000000000000000000000000000100 res=00000000000000000000000000000000 NOTE: bits shift out left side --- BIT SHIFT LEFT ON NEGATIVE INTEGERS --- Expression: -8 = -4 << 1 Decimal: val=-4 res=-8 Binary: val=11111111111111111111111111111100 res=11111111111111111111111111111000 NOTE: zeros fill in right side Expression: -2147483648 = -4 << 29 Decimal: val=-4 res=-2147483648 Binary: val=11111111111111111111111111111100 res=10000000000000000000000000000000 Expression: 0 = -4 << 30 Decimal: val=-4 res=0 Binary: val=11111111111111111111111111111100 res=00000000000000000000000000000000 NOTE: bits shift out left side, including sign bit
Wyświetla następujący przykład na systemach 64 bitowych:
--- BIT SHIFT RIGHT ON POSITIVE INTEGERS --- Expression: 2 = 4 >> 1 Decimal: val=4 res=2 Binary: val=0000000000000000000000000000000000000000000000000000000000000100 res=0000000000000000000000000000000000000000000000000000000000000010 NOTE: copy of sign bit shifted into left side Expression: 1 = 4 >> 2 Decimal: val=4 res=1 Binary: val=0000000000000000000000000000000000000000000000000000000000000100 res=0000000000000000000000000000000000000000000000000000000000000001 Expression: 0 = 4 >> 3 Decimal: val=4 res=0 Binary: val=0000000000000000000000000000000000000000000000000000000000000100 res=0000000000000000000000000000000000000000000000000000000000000000 NOTE: bits shift out right side Expression: 0 = 4 >> 4 Decimal: val=4 res=0 Binary: val=0000000000000000000000000000000000000000000000000000000000000100 res=0000000000000000000000000000000000000000000000000000000000000000 NOTE: same result as above; can not shift beyond 0 --- BIT SHIFT RIGHT ON NEGATIVE INTEGERS --- Expression: -2 = -4 >> 1 Decimal: val=-4 res=-2 Binary: val=1111111111111111111111111111111111111111111111111111111111111100 res=1111111111111111111111111111111111111111111111111111111111111110 NOTE: copy of sign bit shifted into left side Expression: -1 = -4 >> 2 Decimal: val=-4 res=-1 Binary: val=1111111111111111111111111111111111111111111111111111111111111100 res=1111111111111111111111111111111111111111111111111111111111111111 NOTE: bits shift out right side Expression: -1 = -4 >> 3 Decimal: val=-4 res=-1 Binary: val=1111111111111111111111111111111111111111111111111111111111111100 res=1111111111111111111111111111111111111111111111111111111111111111 NOTE: same result as above; can not shift beyond -1 --- BIT SHIFT LEFT ON POSITIVE INTEGERS --- Expression: 8 = 4 << 1 Decimal: val=4 res=8 Binary: val=0000000000000000000000000000000000000000000000000000000000000100 res=0000000000000000000000000000000000000000000000000000000000001000 NOTE: zeros fill in right side Expression: 4611686018427387904 = 4 << 60 Decimal: val=4 res=4611686018427387904 Binary: val=0000000000000000000000000000000000000000000000000000000000000100 res=0100000000000000000000000000000000000000000000000000000000000000 Expression: -9223372036854775808 = 4 << 61 Decimal: val=4 res=-9223372036854775808 Binary: val=0000000000000000000000000000000000000000000000000000000000000100 res=1000000000000000000000000000000000000000000000000000000000000000 NOTE: sign bits get shifted out Expression: 0 = 4 << 62 Decimal: val=4 res=0 Binary: val=0000000000000000000000000000000000000000000000000000000000000100 res=0000000000000000000000000000000000000000000000000000000000000000 NOTE: bits shift out left side --- BIT SHIFT LEFT ON NEGATIVE INTEGERS --- Expression: -8 = -4 << 1 Decimal: val=-4 res=-8 Binary: val=1111111111111111111111111111111111111111111111111111111111111100 res=1111111111111111111111111111111111111111111111111111111111111000 NOTE: zeros fill in right side Expression: -9223372036854775808 = -4 << 61 Decimal: val=-4 res=-9223372036854775808 Binary: val=1111111111111111111111111111111111111111111111111111111111111100 res=1000000000000000000000000000000000000000000000000000000000000000 Expression: 0 = -4 << 62 Decimal: val=-4 res=0 Binary: val=1111111111111111111111111111111111111111111111111111111111111100 res=0000000000000000000000000000000000000000000000000000000000000000 NOTE: bits shift out left side, including sign bit
Don't right shift for more than 32 bits on 32 bits systems. Don't left shift in case it results to number longer than 32 bits. Use functions from the gmp extension for bitwise manipulation on numbers beyond PHP_INT_MAX.
See also pack(), unpack(), gmp_and(), gmp_or(), gmp_xor(), gmp_testbit(), gmp_clrbit()
Comparison Operators
Comparison operators, as their name implies, allow you to compare two values. You may also be interested in viewing the type comparison tables, as they show examples of various type related comparisons.
| Example | Name | Result |
|---|---|---|
| $a == $b | Equal | TRUE if $a is equal to $b after type juggling. |
| $a === $b | Identical |
TRUE if $a is equal to $b, and they are of the same
type.
|
| $a != $b | Not equal | TRUE if $a is not equal to $b after type juggling. |
| $a <> $b | Not equal | TRUE if $a is not equal to $b after type juggling. |
| $a !== $b | Not identical |
TRUE if $a is not equal to $b, or they are not of the same
type.
|
| $a < $b | Less than | TRUE if $a is strictly less than $b. |
| $a > $b | Greater than | TRUE if $a is strictly greater than $b. |
| $a <= $b | Less than or equal to | TRUE if $a is less than or equal to $b. |
| $a >= $b | Greater than or equal to | TRUE if $a is greater than or equal to $b. |
If you compare a number with a string or the comparison involves numerical strings, then each string is converted to a number and the comparison performed numerically. These rules also apply to the switch statement. The type conversion does not take place when the comparison is === or !== as this involves comparing the type as well as the value.
<?php
var_dump(0 == "a"); // 0 == 0 -> true
var_dump("1" == "01"); // 1 == 1 -> true
var_dump("10" == "1e1"); // 10 == 10 -> true
var_dump(100 == "1e2"); // 100 == 100 -> true
switch ("a") {
case 0:
echo "0";
break;
case "a": // never reached because "a" is already matched with 0
echo "a";
break;
}
?>
For various types, comparison is done according to the following table (in order).
| Type of Operand 1 | Type of Operand 2 | Result |
|---|---|---|
| null or string | string | Convert NULL to "", numerical or lexical comparison |
| bool or null | anything | Convert to bool, FALSE < TRUE |
| object | object | Built-in classes can define its own comparison, different classes are uncomparable, same class - compare properties the same way as arrays (PHP 4), PHP 5 has its own explanation |
| string, resource or number | string, resource or number | Translate strings and resources to numbers, usual math |
| array | array | Array with fewer members is smaller, if key from operand 1 is not found in operand 2 then arrays are uncomparable, otherwise - compare value by value (see following example) |
| array | anything | array is always greater |
| object | anything | object is always greater |
Przykład #1 Transcription of standard array comparison
<?php
// Arrays are compared like this with standard comparison operators
function standard_array_compare($op1, $op2)
{
if (count($op1) < count($op2)) {
return -1; // $op1 < $op2
} elseif (count($op1) > count($op2)) {
return 1; // $op1 > $op2
}
foreach ($op1 as $key => $val) {
if (!array_key_exists($key, $op2)) {
return null; // uncomparable
} elseif ($val < $op2[$key]) {
return -1;
} elseif ($val > $op2[$key]) {
return 1;
}
}
return 0; // $op1 == $op2
}
?>
See also strcasecmp(), strcmp(), Array operators, and the manual section on Types.
Comparison of floating point numbers
Because of the way floats are represented internally, you should not test two floats for equality.
See the documentation for float for more information.
Ternary Operator
Another conditional operator is the "?:" (or ternary) operator.
Przykład #2 Assigning a default value
<?php
// Example usage for: Ternary Operator
$action = (empty($_POST['action'])) ? 'default' : $_POST['action'];
// The above is identical to this if/else statement
if (empty($_POST['action'])) {
$action = 'default';
} else {
$action = $_POST['action'];
}
?>
TRUE, and
expr3 if
expr1 evaluates to FALSE.
Since PHP 5.3, it is possible to leave out the middle part of the ternary
operator. Expression expr1 ?: expr3 returns
expr1 if expr1
evaluates to TRUE, and expr3 otherwise.
Informacja: Please note that the ternary operator is a statement, and that it doesn't evaluate to a variable, but to the result of a statement. This is important to know if you want to return a variable by reference. The statement return $var == 42 ? $a : $b; in a return-by-reference function will therefore not work and a warning is issued in later PHP versions.
Informacja:
It is recommended that you avoid "stacking" ternary expressions. PHP's behaviour when using more than one ternary operator within a single statement is non-obvious:
Przykład #3 Non-obvious Ternary Behaviour
<?php
// on first glance, the following appears to output 'true'
echo (true?'true':false?'t':'f');
// however, the actual output of the above is 't'
// this is because ternary expressions are evaluated from left to right
// the following is a more obvious version of the same code as above
echo ((true ? 'true' : false) ? 't' : 'f');
// here, you can see that the first expression is evaluated to 'true', which
// in turn evaluates to (bool)true, thus returning the true branch of the
// second ternary expression.
?>
Error Control Operators
PHP supports one error control operator: the at sign (@). When prepended to an expression in PHP, any error messages that might be generated by that expression will be ignored.
If you have set a custom error handler function with set_error_handler() then it will still get called, but this custom error handler can (and should) call error_reporting() which will return 0 when the call that triggered the error was preceded by an @.
If the track_errors feature is enabled, any error message generated by the expression will be saved in the variable $php_errormsg. This variable will be overwritten on each error, so check early if you want to use it.
<?php
/* Intentional file error */
$my_file = @file ('non_existent_file') or
die ("Failed opening file: error was '$php_errormsg'");
// this works for any expression, not just functions:
$value = @$cache[$key];
// will not issue a notice if the index $key doesn't exist.
?>
Informacja: The @-operator works only on expressions. A simple rule of thumb is: if you can take the value of something, you can prepend the @ operator to it. For instance, you can prepend it to variables, function and include() calls, constants, and so forth. You cannot prepend it to function or class definitions, or conditional structures such as if and foreach, and so forth.
See also error_reporting() and the manual section for Error Handling and Logging functions.
Currently the "@" error-control operator prefix will even disable error reporting for critical errors that will terminate script execution. Among other things, this means that if you use "@" to suppress errors from a certain function and either it isn't available or has been mistyped, the script will die right there with no indication as to why.
Execution Operators
PHP supports one execution operator: backticks (``). Note that these are not single-quotes! PHP will attempt to execute the contents of the backticks as a shell command; the output will be returned (i.e., it won't simply be dumped to output; it can be assigned to a variable). Use of the backtick operator is identical to shell_exec().
<?php
$output = `ls -al`;
echo "<pre>$output</pre>";
?>
Informacja:
The backtick operator is disabled when tryb bezpieczny is enabled or shell_exec() is disabled.
Informacja:
Unlike some other languages, backticks cannot be used within double-quoted strings.
See also the manual section on Program Execution functions, popen() proc_open(), and Using PHP from the commandline.
Incrementing/Decrementing Operators
PHP supports C-style pre- and post-increment and decrement operators.
Informacja: The increment/decrement operators do not affect boolean values. Decrementing
NULLvalues has no effect too, but incrementing them results in 1.
| Example | Name | Effect |
|---|---|---|
| ++$a | Pre-increment | Increments $a by one, then returns $a. |
| $a++ | Post-increment | Returns $a, then increments $a by one. |
| --$a | Pre-decrement | Decrements $a by one, then returns $a. |
| $a-- | Post-decrement | Returns $a, then decrements $a by one. |
Here's a simple example script:
<?php
echo "<h3>Postincrement</h3>";
$a = 5;
echo "Should be 5: " . $a++ . "<br />\n";
echo "Should be 6: " . $a . "<br />\n";
echo "<h3>Preincrement</h3>";
$a = 5;
echo "Should be 6: " . ++$a . "<br />\n";
echo "Should be 6: " . $a . "<br />\n";
echo "<h3>Postdecrement</h3>";
$a = 5;
echo "Should be 5: " . $a-- . "<br />\n";
echo "Should be 4: " . $a . "<br />\n";
echo "<h3>Predecrement</h3>";
$a = 5;
echo "Should be 4: " . --$a . "<br />\n";
echo "Should be 4: " . $a . "<br />\n";
?>
PHP follows Perl's convention when dealing with arithmetic operations on character variables and not C's. For example, in PHP and Perl $a = 'Z'; $a++; turns $a into 'AA', while in C a = 'Z'; a++; turns a into '[' (ASCII value of 'Z' is 90, ASCII value of '[' is 91). Note that character variables can be incremented but not decremented and even so only plain ASCII characters (a-z and A-Z) are supported. Incrementing/decrementing other character variables has no effect, the original string is unchanged.
Przykład #1 Arithmetic Operations on Character Variables
<?php
$i = 'W';
for ($n=0; $n<6; $n++) {
echo ++$i . "\n";
}
?>
Powyższy przykład wyświetli:
X Y Z AA AB AC
Incrementing or decrementing booleans has no effect.
Logical Operators
| Example | Name | Result |
|---|---|---|
| $a and $b | And | TRUE if both $a and $b are TRUE. |
| $a or $b | Or | TRUE if either $a or $b is TRUE. |
| $a xor $b | Xor | TRUE if either $a or $b is TRUE, but not both. |
| ! $a | Not | TRUE if $a is not TRUE. |
| $a && $b | And | TRUE if both $a and $b are TRUE. |
| $a || $b | Or | TRUE if either $a or $b is TRUE. |
The reason for the two different variations of "and" and "or" operators is that they operate at different precedences. (See Operator Precedence.)
Przykład #1 Logical operators illustrated
<?php
// --------------------
// foo() will never get called as those operators are short-circuit
$a = (false && foo());
$b = (true || foo());
$c = (false and foo());
$d = (true or foo());
// --------------------
// "||" has a greater precedence than "or"
// The result of the expression (false || true) is assigned to $e
// Acts like: ($e = (false || true))
$e = false || true;
// The constant false is assigned to $f and then true is ignored
// Acts like: (($f = false) or true)
$f = false or true;
var_dump($e, $f);
// --------------------
// "&&" has a greater precedence than "and"
// The result of the expression (true && false) is assigned to $g
// Acts like: ($g = (true && false))
$g = true && false;
// The constant true is assigned to $h and then false is ignored
// Acts like: (($h = true) and false)
$h = true and false;
var_dump($g, $h);
?>
Powyższy przykład wyświetli coś podobnego do:
bool(true) bool(false) bool(false) bool(true)
String Operators
There are two string operators. The first is the concatenation operator ('.'), which returns the concatenation of its right and left arguments. The second is the concatenating assignment operator ('.='), which appends the argument on the right side to the argument on the left side. Please read Assignment Operators for more information.
<?php
$a = "Hello ";
$b = $a . "World!"; // now $b contains "Hello World!"
$a = "Hello ";
$a .= "World!"; // now $a contains "Hello World!"
?>
See also the manual sections on the String type and String functions.
Array Operators
| Example | Name | Result |
|---|---|---|
| $a + $b | Union | Union of $a and $b. |
| $a == $b | Equality | TRUE if $a and $b have the same key/value pairs. |
| $a === $b | Identity | TRUE if $a and $b have the same key/value pairs in the same
order and of the same types. |
| $a != $b | Inequality | TRUE if $a is not equal to $b. |
| $a <> $b | Inequality | TRUE if $a is not equal to $b. |
| $a !== $b | Non-identity | TRUE if $a is not identical to $b. |
The + operator returns the right-hand array appended to the left-hand array; for keys that exist in both arrays, the elements from the left-hand array will be used, and the matching elements from the right-hand array will be ignored.
<?php
$a = array("a" => "apple", "b" => "banana");
$b = array("a" => "pear", "b" => "strawberry", "c" => "cherry");
$c = $a + $b; // Union of $a and $b
echo "Union of \$a and \$b: \n";
var_dump($c);
$c = $b + $a; // Union of $b and $a
echo "Union of \$b and \$a: \n";
var_dump($c);
?>
Union of $a and $b:
array(3) {
["a"]=>
string(5) "apple"
["b"]=>
string(6) "banana"
["c"]=>
string(6) "cherry"
}
Union of $b and $a:
array(3) {
["a"]=>
string(4) "pear"
["b"]=>
string(10) "strawberry"
["c"]=>
string(6) "cherry"
}
Elements of arrays are equal for the comparison if they have the same key and value.
Przykład #1 Comparing arrays
<?php
$a = array("apple", "banana");
$b = array(1 => "banana", "0" => "apple");
var_dump($a == $b); // bool(true)
var_dump($a === $b); // bool(false)
?>
See also the manual sections on the Array type and Array functions.
Type Operators
instanceof is used to determine whether a PHP variable is an instantiated object of a certain class:
Przykład #1 Using instanceof with classes
<?php
class MyClass
{
}
class NotMyClass
{
}
$a = new MyClass;
var_dump($a instanceof MyClass);
var_dump($a instanceof NotMyClass);
?>
Powyższy przykład wyświetli:
bool(true) bool(false)
instanceof can also be used to determine whether a variable is an instantiated object of a class that inherits from a parent class:
Przykład #2 Using instanceof with inherited classes
<?php
class ParentClass
{
}
class MyClass extends ParentClass
{
}
$a = new MyClass;
var_dump($a instanceof MyClass);
var_dump($a instanceof ParentClass);
?>
Powyższy przykład wyświetli:
bool(true) bool(true)
To check if an object is not an instanceof a class, the logical not operator can be used.
Przykład #3 Using instanceof to check if object is not an instanceof a class
<?php
class MyClass
{
}
$a = new MyClass;
var_dump(!($a instanceof stdClass));
?>
Powyższy przykład wyświetli:
bool(true)
Lastly, instanceof can also be used to determine whether a variable is an instantiated object of a class that implements an interface:
Przykład #4 Using instanceof for class
<?php
interface MyInterface
{
}
class MyClass implements MyInterface
{
}
$a = new MyClass;
var_dump($a instanceof MyClass);
var_dump($a instanceof MyInterface);
?>
Powyższy przykład wyświetli:
bool(true) bool(true)
Although instanceof is usually used with a literal classname, it can also be used with another object or a string variable:
Przykład #5 Using instanceof with other variables
<?php
interface MyInterface
{
}
class MyClass implements MyInterface
{
}
$a = new MyClass;
$b = new MyClass;
$c = 'MyClass';
$d = 'NotMyClass';
var_dump($a instanceof $b); // $b is an object of class MyClass
var_dump($a instanceof $c); // $c is a string 'MyClass'
var_dump($a instanceof $d); // $d is a string 'NotMyClass'
?>
Powyższy przykład wyświetli:
bool(true) bool(true) bool(false)
There are a few pitfalls to be aware of. Before PHP version 5.1.0, instanceof would call __autoload() if the class name did not exist. In addition, if the class was not loaded, a fatal error would occur. This can be worked around by using a dynamic class reference, or a string variable containing the class name:
Przykład #6 Avoiding classname lookups and fatal errors with instanceof in PHP 5.0
<?php
$d = 'NotMyClass';
var_dump($a instanceof $d); // no fatal error here
?>
Powyższy przykład wyświetli:
bool(false)
The instanceof operator was introduced in PHP 5. Before this time is_a() was used but is_a() has since been deprecated in favor of instanceof. Note that as of PHP 5.3.0, is_a() is no longer deprecated.
See also get_class() and is_a().
Control Structures
Spis treści
- Introduction
- if
- else
- elseif/else if
- Alternative syntax for control structures
- while
- do-while
- for
- foreach
- break
- continue
- switch
- declare
- return
- require
- include
- require_once
- include_once
- goto
Introduction
Any PHP script is built out of a series of statements. A statement can be an assignment, a function call, a loop, a conditional statement or even a statement that does nothing (an empty statement). Statements usually end with a semicolon. In addition, statements can be grouped into a statement-group by encapsulating a group of statements with curly braces. A statement-group is a statement by itself as well. The various statement types are described in this chapter.
if
(PHP 4, PHP 5)
The if construct is one of the most important features of many languages, PHP included. It allows for conditional execution of code fragments. PHP features an if structure that is similar to that of C:
if (expr) statement
As described in the section about
expressions, expression is evaluated to its
Boolean value. If expression evaluates to TRUE,
PHP will execute statement, and if it evaluates
to FALSE - it'll ignore it. More information about what values evaluate
to FALSE can be found in the 'Converting to boolean'
section.
The following example would display a is bigger than b if $a is bigger than $b:
<?php
if ($a > $b)
echo "a is bigger than b";
?>
Often you'd want to have more than one statement to be executed conditionally. Of course, there's no need to wrap each statement with an if clause. Instead, you can group several statements into a statement group. For example, this code would display a is bigger than b if $a is bigger than $b, and would then assign the value of $a into $b:
<?php
if ($a > $b) {
echo "a is bigger than b";
$b = $a;
}
?>
If statements can be nested infinitely within other if statements, which provides you with complete flexibility for conditional execution of the various parts of your program.
else
(PHP 4, PHP 5)
Often you'd want to execute a statement if a certain condition is
met, and a different statement if the condition is not met. This
is what else is for. else
extends an if statement to execute a statement
in case the expression in the if statement
evaluates to FALSE. For example, the following
code would display a is greater than
b if $a is greater than
$b, and a is NOT greater
than b otherwise:
<?php
if ($a > $b) {
echo "a is greater than b";
} else {
echo "a is NOT greater than b";
}
?>
FALSE, and if there were any
elseif expressions - only if they evaluated to
FALSE as well (see elseif).
elseif/else if
(PHP 4, PHP 5)
elseif, as its name suggests, is a combination
of if and else. Like
else, it extends an if
statement to execute a different statement in case the original
if expression evaluates to
FALSE. However, unlike
else, it will execute that alternative
expression only if the elseif conditional
expression evaluates to TRUE. For example, the
following code would display a is bigger than
b, a equal to b
or a is smaller than b:
<?php
if ($a > $b) {
echo "a is bigger than b";
} elseif ($a == $b) {
echo "a is equal to b";
} else {
echo "a is smaller than b";
}
?>
There may be several elseifs within the same
if statement. The first
elseif expression (if any) that evaluates to
TRUE would be executed. In PHP, you can also
write 'else if' (in two words) and the behavior would be identical
to the one of 'elseif' (in a single word). The syntactic meaning
is slightly different (if you're familiar with C, this is the same
behavior) but the bottom line is that both would result in exactly
the same behavior.
The elseif statement is only executed if the
preceding if expression and any preceding
elseif expressions evaluated to
FALSE, and the current
elseif expression evaluated to
TRUE.
Informacja: Note that elseif and else if will only be considered exactly the same when using curly brackets as in the above example. When using a colon to define your if/elseif conditions, you must not separate else if into two words, or PHP will fail with a parse error.
<?php
/* Incorrect Method: */
if($a > $b):
echo $a." is greater than ".$b;
else if($a == $b): // Will not compile.
echo "The above line causes a parse error.";
endif;
/* Correct Method: */
if($a > $b):
echo $a." is greater than ".$b;
elseif($a == $b): // Note the combination of the words.
echo $a." equals ".$b;
else:
echo $a." is neither greater than or equal to ".$b;
endif;
?>
Alternative syntax for control structures
(PHP 4, PHP 5)
PHP offers an alternative syntax for some of its control structures; namely, if, while, for, foreach, and switch. In each case, the basic form of the alternate syntax is to change the opening brace to a colon (:) and the closing brace to endif;, endwhile;, endfor;, endforeach;, or endswitch;, respectively.
<?php if ($a == 5): ?>
A is equal to 5
<?php endif; ?>
In the above example, the HTML block "A is equal to 5" is nested within an if statement written in the alternative syntax. The HTML block would be displayed only if $a is equal to 5.
The alternative syntax applies to else and elseif as well. The following is an if structure with elseif and else in the alternative format:
<?php
if ($a == 5):
echo "a equals 5";
echo "...";
elseif ($a == 6):
echo "a equals 6";
echo "!!!";
else:
echo "a is neither 5 nor 6";
endif;
?>
Informacja:
Mixing syntaxes in the same control block is not supported.
while
(PHP 4, PHP 5)
while loops are the simplest type of loop in PHP. They behave just like their C counterparts. The basic form of a while statement is:
while (expr)
statement
The meaning of a while statement is simple. It
tells PHP to execute the nested statement(s) repeatedly, as long
as the while expression evaluates to
TRUE. The value of the expression is checked
each time at the beginning of the loop, so even if this value
changes during the execution of the nested statement(s), execution
will not stop until the end of the iteration (each time PHP runs
the statements in the loop is one iteration). Sometimes, if the
while expression evaluates to
FALSE from the very beginning, the nested
statement(s) won't even be run once.
Like with the if statement, you can group multiple statements within the same while loop by surrounding a group of statements with curly braces, or by using the alternate syntax:
while (expr):
statement
...
endwhile;
The following examples are identical, and both print the numbers 1 through 10:
<?php
/* example 1 */
$i = 1;
while ($i <= 10) {
echo $i++; /* the printed value would be
$i before the increment
(post-increment) */
}
/* example 2 */
$i = 1;
while ($i <= 10):
echo $i;
$i++;
endwhile;
?>
do-while
(PHP 4, PHP 5)
do-while loops are very similar to
while loops, except the truth expression is
checked at the end of each iteration instead of in the beginning.
The main difference from regular while loops is
that the first iteration of a do-while loop is
guaranteed to run (the truth expression is only checked at the end
of the iteration), whereas it may not necessarily run with a
regular while loop (the truth expression is
checked at the beginning of each iteration, if it evaluates to
FALSE right from the beginning, the loop
execution would end immediately).
There is just one syntax for do-while loops:
<?php
$i = 0;
do {
echo $i;
} while ($i > 0);
?>
The above loop would run one time exactly, since after the first
iteration, when truth expression is checked, it evaluates to
FALSE ($i is not bigger than 0) and the loop
execution ends.
Advanced C users may be familiar with a different usage of the do-while loop, to allow stopping execution in the middle of code blocks, by encapsulating them with do-while (0), and using the break statement. The following code fragment demonstrates this:
<?php
do {
if ($i < 5) {
echo "i is not big enough";
break;
}
$i *= $factor;
if ($i < $minimum_limit) {
break;
}
echo "i is ok";
/* process i */
} while (0);
?>
Don't worry if you don't understand this right away or at all. You can code scripts and even powerful scripts without using this 'feature'. Since PHP 5.3.0, it is possible to use goto operator instead of this hack.
for
(PHP 4, PHP 5)
for loops are the most complex loops in PHP. They behave like their C counterparts. The syntax of a for loop is:
for (expr1; expr2; expr3)
statement
The first expression (expr1) is evaluated (executed) once unconditionally at the beginning of the loop.
In the beginning of each iteration,
expr2 is evaluated. If it evaluates to
TRUE, the loop continues and the nested
statement(s) are executed. If it evaluates to
FALSE, the execution of the loop ends.
At the end of each iteration, expr3 is evaluated (executed).
Each of the expressions can be empty or contain multiple
expressions separated by commas. In expr2, all
expressions separated by a comma are evaluated but the result is taken
from the last part.
expr2 being empty means the loop should
be run indefinitely (PHP implicitly considers it as
TRUE, like C). This may not be as useless as
you might think, since often you'd want to end the loop using a
conditional break
statement instead of using the for truth
expression.
Consider the following examples. All of them display the numbers 1 through 10:
<?php
/* example 1 */
for ($i = 1; $i <= 10; $i++) {
echo $i;
}
/* example 2 */
for ($i = 1; ; $i++) {
if ($i > 10) {
break;
}
echo $i;
}
/* example 3 */
$i = 1;
for (; ; ) {
if ($i > 10) {
break;
}
echo $i;
$i++;
}
/* example 4 */
for ($i = 1, $j = 0; $i <= 10; $j += $i, print $i, $i++);
?>
Of course, the first example appears to be the nicest one (or perhaps the fourth), but you may find that being able to use empty expressions in for loops comes in handy in many occasions.
PHP also supports the alternate "colon syntax" for for loops.
for (expr1; expr2; expr3):
statement
...
endfor;
Its a common thing to many users to iterate though arrays like in the example below.
<?php
/*
* This is an array with some data we want to modify
* when running through the for loop.
*/
$people = Array(
Array('name' => 'Kalle', 'salt' => 856412),
Array('name' => 'Pierre', 'salt' => 215863)
);
for($i = 0; $i < sizeof($people); ++$i)
{
$people[$i]['salt'] = rand(000000, 999999);
}
?>
The problem lies in the second for expression. This code can be slow because it has to calculate the size of the array on each iteration. Since the size never change, it can be optimized easily using an intermediate variable to store the size and use in the loop instead of sizeof. The example below illustrates this:
<?php
$people = Array(
Array('name' => 'Kalle', 'salt' => 856412),
Array('name' => 'Pierre', 'salt' => 215863)
);
for($i = 0, $size = sizeof($people); $i < $size; ++$i)
{
$people[$i]['salt'] = rand(000000, 999999);
}
?>
foreach
(PHP 4, PHP 5)
The foreach construct provides an easy way to iterate over arrays. foreach works only on arrays and objects, and will issue an error when you try to use it on a variable with a different data type or an uninitialized variable. There are two syntaxes:
foreach (array_expression as $value)
statement
foreach (array_expression as $key => $value)
statement
The first form loops over the array given by array_expression. On each iteration, the value of the current element is assigned to $value and the internal array pointer is advanced by one (so on the next iteration, you'll be looking at the next element).
The second form will additionally assign the current element's key to the $key variable on each iteration.
It is possible to customize object iteration.
Informacja:
When foreach first starts executing, the internal array pointer is automatically reset to the first element of the array. This means that you do not need to call reset() before a foreach loop.
As foreach relies on the internal array pointer changing it within the loop may lead to unexpected behavior.
In order to be able to directly modify array elements within the loop precede $value with &. In that case the value will be assigned by reference.
<?php
$arr = array(1, 2, 3, 4);
foreach ($arr as &$value) {
$value = $value * 2;
}
// $arr is now array(2, 4, 6, 8)
unset($value); // break the reference with the last element
?>
Referencing $value is only possible if the iterated array can be referenced (i.e. if it is a variable). The following code won't work:
<?php
foreach (array(1, 2, 3, 4) as &$value) {
$value = $value * 2;
}
?>
Reference of a $value and the last array element remain even after the foreach loop. It is recommended to destroy it by unset().
Informacja:
foreach does not support the ability to suppress error messages using '@'.
You may have noticed that the following are functionally identical:
<?php
$arr = array("one", "two", "three");
reset($arr);
while (list(, $value) = each($arr)) {
echo "Value: $value<br />\n";
}
foreach ($arr as $value) {
echo "Value: $value<br />\n";
}
?>
The following are also functionally identical:
<?php
$arr = array("one", "two", "three");
reset($arr);
while (list($key, $value) = each($arr)) {
echo "Key: $key; Value: $value<br />\n";
}
foreach ($arr as $key => $value) {
echo "Key: $key; Value: $value<br />\n";
}
?>
Some more examples to demonstrate usages:
<?php
/* foreach example 1: value only */
$a = array(1, 2, 3, 17);
foreach ($a as $v) {
echo "Current value of \$a: $v.\n";
}
/* foreach example 2: value (with its manual access notation printed for illustration) */
$a = array(1, 2, 3, 17);
$i = 0; /* for illustrative purposes only */
foreach ($a as $v) {
echo "\$a[$i] => $v.\n";
$i++;
}
/* foreach example 3: key and value */
$a = array(
"one" => 1,
"two" => 2,
"three" => 3,
"seventeen" => 17
);
foreach ($a as $k => $v) {
echo "\$a[$k] => $v.\n";
}
/* foreach example 4: multi-dimensional arrays */
$a = array();
$a[0][0] = "a";
$a[0][1] = "b";
$a[1][0] = "y";
$a[1][1] = "z";
foreach ($a as $v1) {
foreach ($v1 as $v2) {
echo "$v2\n";
}
}
/* foreach example 5: dynamic arrays */
foreach (array(1, 2, 3, 4, 5) as $v) {
echo "$v\n";
}
?>
break
(PHP 4, PHP 5)
break ends execution of the current for, foreach, while, do-while or switch structure.
break accepts an optional numeric argument which tells it how many nested enclosing structures are to be broken out of.
<?php
$arr = array('one', 'two', 'three', 'four', 'stop', 'five');
while (list(, $val) = each($arr)) {
if ($val == 'stop') {
break; /* You could also write 'break 1;' here. */
}
echo "$val<br />\n";
}
/* Using the optional argument. */
$i = 0;
while (++$i) {
switch ($i) {
case 5:
echo "At 5<br />\n";
break 1; /* Exit only the switch. */
case 10:
echo "At 10; quitting<br />\n";
break 2; /* Exit the switch and the while. */
default:
break;
}
}
?>
| Wersja | Opis |
|---|---|
| 5.4.0 | Removed the ability to pass in variables (e.g., $num = 2; break $num;) as the numerical argument. |
continue
(PHP 4, PHP 5)
continue is used within looping structures to skip the rest of the current loop iteration and continue execution at the condition evaluation and then the beginning of the next iteration.
Informacja: Note that in PHP the switch statement is considered a looping structure for the purposes of continue.
continue accepts an optional numeric argument which tells it how many levels of enclosing loops it should skip to the end of.
Informacja:
continue 0; and continue 1; is the same as running continue;.
<?php
while (list($key, $value) = each($arr)) {
if (!($key % 2)) { // skip odd members
continue;
}
do_something_odd($value);
}
$i = 0;
while ($i++ < 5) {
echo "Outer<br />\n";
while (1) {
echo " Middle<br />\n";
while (1) {
echo " Inner<br />\n";
continue 3;
}
echo "This never gets output.<br />\n";
}
echo "Neither does this.<br />\n";
}
?>
Omitting the semicolon after continue can lead to confusion. Here's an example of what you shouldn't do.
<?php
for ($i = 0; $i < 5; ++$i) {
if ($i == 2)
continue
print "$i\n";
}
?>
One can expect the result to be:
0 1 3 4
but this script will output:
2
because the entire continue print "$i\n"; is evaluated as a single expression, and so print() is called only when $i == 2 is true. (The return value of print is passed to continue as the numeric argument.)
| Wersja | Opis |
|---|---|
| 5.4.0 | Removed the ability to pass in variables (e.g., $num = 2; continue $num;) as the numerical argument. |
switch
(PHP 4, PHP 5)
The switch statement is similar to a series of IF statements on the same expression. In many occasions, you may want to compare the same variable (or expression) with many different values, and execute a different piece of code depending on which value it equals to. This is exactly what the switch statement is for.
Informacja: Note that unlike some other languages, the continue statement applies to switch and acts similar to break. If you have a switch inside a loop and wish to continue to the next iteration of the outer loop, use continue 2.
Informacja:
Note that switch/case does loose comparision.
The following two examples are two different ways to write the same thing, one using a series of if and elseif statements, and the other using the switch statement:
Przykład #1 switch structure
<?php
if ($i == 0) {
echo "i equals 0";
} elseif ($i == 1) {
echo "i equals 1";
} elseif ($i == 2) {
echo "i equals 2";
}
switch ($i) {
case 0:
echo "i equals 0";
break;
case 1:
echo "i equals 1";
break;
case 2:
echo "i equals 2";
break;
}
?>
Przykład #2 switch structure allows usage of strings
<?php
switch ($i) {
case "apple":
echo "i is apple";
break;
case "bar":
echo "i is bar";
break;
case "cake":
echo "i is cake";
break;
}
?>
It is important to understand how the switch statement is executed in order to avoid mistakes. The switch statement executes line by line (actually, statement by statement). In the beginning, no code is executed. Only when a case statement is found with a value that matches the value of the switch expression does PHP begin to execute the statements. PHP continues to execute the statements until the end of the switch block, or the first time it sees a break statement. If you don't write a break statement at the end of a case's statement list, PHP will go on executing the statements of the following case. For example:
<?php
switch ($i) {
case 0:
echo "i equals 0";
case 1:
echo "i equals 1";
case 2:
echo "i equals 2";
}
?>
Here, if $i is equal to 0, PHP would execute all of the echo statements! If $i is equal to 1, PHP would execute the last two echo statements. You would get the expected behavior ('i equals 2' would be displayed) only if $i is equal to 2. Thus, it is important not to forget break statements (even though you may want to avoid supplying them on purpose under certain circumstances).
In a switch statement, the condition is evaluated only once and the result is compared to each case statement. In an elseif statement, the condition is evaluated again. If your condition is more complicated than a simple compare and/or is in a tight loop, a switch may be faster.
The statement list for a case can also be empty, which simply passes control into the statement list for the next case.
<?php
switch ($i) {
case 0:
case 1:
case 2:
echo "i is less than 3 but not negative";
break;
case 3:
echo "i is 3";
}
?>
A special case is the default case. This case matches anything that wasn't matched by the other cases. For example:
<?php
switch ($i) {
case 0:
echo "i equals 0";
break;
case 1:
echo "i equals 1";
break;
case 2:
echo "i equals 2";
break;
default:
echo "i is not equal to 0, 1 or 2";
}
?>
The case expression may be any expression that evaluates to a simple type, that is, integer or floating-point numbers and strings. Arrays or objects cannot be used here unless they are dereferenced to a simple type.
The alternative syntax for control structures is supported with switches. For more information, see Alternative syntax for control structures.
<?php
switch ($i):
case 0:
echo "i equals 0";
break;
case 1:
echo "i equals 1";
break;
case 2:
echo "i equals 2";
break;
default:
echo "i is not equal to 0, 1 or 2";
endswitch;
?>
It's possible to use a semicolon instead of a colon after a case like:
<?php
switch($beer)
{
case 'tuborg';
case 'carlsberg';
case 'heineken';
echo 'Good choice';
break;
default;
echo 'Please make a new selection...';
break;
}
?>
declare
(PHP 4, PHP 5)
The declare construct is used to set execution directives for a block of code. The syntax of declare is similar to the syntax of other flow control constructs:
declare (directive)
statement
The directive section allows the behavior of the declare block to be set. Currently only two directives are recognized: the ticks directive (See below for more information on the ticks directive) and the encoding directive (See below for more information on the encoding directive).
Informacja: The encoding directive was added in PHP 5.3.0
The statement part of the declare block will be executed - how it is executed and what side effects occur during execution may depend on the directive set in the directive block.
The declare construct can also be used in the global scope, affecting all code following it (however if the file with declare was included then it does not affect the parent file).
<?php
// these are the same:
// you can use this:
declare(ticks=1) {
// entire script here
}
// or you can use this:
declare(ticks=1);
// entire script here
?>
Ticks
A tick is an event that occurs for every
N low-level tickable statements executed
by the parser within the declare block.
The value for N is specified
using ticks=N
within the declare blocks's
directive section.
Not all statements are tickable. Typically, condition expressions and argument expressions are not tickable.
The event(s) that occur on each tick are specified using the register_tick_function(). See the example below for more details. Note that more than one event can occur for each tick.
Przykład #1 Tick usage example
<?php
declare(ticks=1);
// A function called on each tick event
function tick_handler()
{
echo "tick_handler() called\n";
}
register_tick_function('tick_handler');
$a = 1;
if ($a > 0) {
$a += 2;
print($a);
}
?>
Przykład #2 Ticks usage example
<?php
function tick_handler()
{
echo "tick_handler() called\n";
}
$a = 1;
tick_handler();
if ($a > 0) {
$a += 2;
tick_handler();
print($a);
tick_handler();
}
tick_handler();
?>
See also register_tick_function() and unregister_tick_function().
Encoding
A script's encoding can be specified per-script using the encoding directive.
Przykład #3 Declaring an encoding for the script.
<?php
declare(encoding='ISO-8859-1');
// code here
?>
When combined with namespaces, the only legal syntax for declare is declare(encoding='...'); where ... is the encoding value. declare(encoding='...') {} will result in a parse error when combined with namespaces.
The encoding declare value is ignored in PHP 5.3 unless php is compiled with --enable-zend-multibyte.
Note that PHP does not expose whether --enable-zend-multibyte was used to compile PHP other than by phpinfo().
return
(PHP 4, PHP 5)
If called from within a function, the return() statement immediately ends execution of the current function, and returns its argument as the value of the function call. return() will also end the execution of an eval() statement or script file.
If called from the global scope, then execution of the current script file is ended. If the current script file was include()ed or require()ed, then control is passed back to the calling file. Furthermore, if the current script file was include()ed, then the value given to return() will be returned as the value of the include() call. If return() is called from within the main script file, then script execution ends. If the current script file was named by the auto_prepend_file or auto_append_file configuration options in php.ini, then that script file's execution is ended.
For more information, see Returning values.
Informacja: Note that since return() is a language construct and not a function, the parentheses surrounding its arguments are not required. It is common to leave them out, and you actually should do so as PHP has less work to do in this case.
Informacja: If no parameter is supplied, then the parentheses must be omitted and
NULLwill be returned. Calling return() with parentheses but with no arguments will result in a parse error.
Informacja: You should never use parentheses around your return variable when returning by reference, as this will not work. You can only return variables by reference, not the result of a statement. If you use return ($a); then you're not returning a variable, but the result of the expression ($a) (which is, of course, the value of $a).
require()
(PHP 4, PHP 5)
require() is identical to include()
except upon failure it will also produce a fatal E_COMPILE_ERROR
level error. In other words, it will halt the script whereas
include() only emits a warning
(E_WARNING) which allows the script to continue.
See the include() documentation for how this works.
include()
(PHP 4, PHP 5)
The include() statement includes and evaluates the specified file.
The documentation below also applies to require().
Files are included based on the file path given or, if none is given, the include_path specified. If the file isn't found in the include_path, include() will finally check in the calling script's own directory and the current working directory before failing. The include() construct will emit a warning if it cannot find a file; this is different behavior from require(), which will emit a fatal error.
If a path is defined — whether absolute (starting with a drive letter or \ on Windows, or / on Unix/Linux systems) or relative to the current directory (starting with . or ..) — the include_path will be ignored altogether. For example, if a filename begins with ../, the parser will look in the parent directory to find the requested file.
For more information on how PHP handles including files and the include path, see the documentation for include_path.
When a file is included, the code it contains inherits the variable scope of the line on which the include occurs. Any variables available at that line in the calling file will be available within the called file, from that point forward. However, all functions and classes defined in the included file have the global scope.
Przykład #1 Basic include() example
vars.php
<?php
$color = 'green';
$fruit = 'apple';
?>
test.php
<?php
echo "A $color $fruit"; // A
include 'vars.php';
echo "A $color $fruit"; // A green apple
?>
If the include occurs inside a function within the calling file, then all of the code contained in the called file will behave as though it had been defined inside that function. So, it will follow the variable scope of that function. An exception to this rule are magic constants which are evaluated by the parser before the include occurs.
Przykład #2 Including within functions
<?php
function foo()
{
global $color;
include 'vars.php';
echo "A $color $fruit";
}
/* vars.php is in the scope of foo() so *
* $fruit is NOT available outside of this *
* scope. $color is because we declared it *
* as global. */
foo(); // A green apple
echo "A $color $fruit"; // A green
?>
When a file is included, parsing drops out of PHP mode and into HTML mode at the beginning of the target file, and resumes again at the end. For this reason, any code inside the target file which should be executed as PHP code must be enclosed within valid PHP start and end tags.
If "URL fopen wrappers" are enabled in PHP (which they are in the default configuration), you can specify the file to be included using a URL (via HTTP or other supported wrapper - see Supported Protocols and Wrappers for a list of protocols) instead of a local pathname. If the target server interprets the target file as PHP code, variables may be passed to the included file using a URL request string as used with HTTP GET. This is not strictly speaking the same thing as including the file and having it inherit the parent file's variable scope; the script is actually being run on the remote server and the result is then being included into the local script.
PHP w wersji starszej niż 4.3.0, pracujące pod kontrolą systemów Windows, nie obsługują dostępu do zdalnych plików w tej funkcji, nawet jeśli opcja allow_url_fopen jest włączona.
Przykład #3 include() through HTTP
<?php
/* This example assumes that www.example.com is configured to parse .php
* files and not .txt files. Also, 'Works' here means that the variables
* $foo and $bar are available within the included file. */
// Won't work; file.txt wasn't handled by www.example.com as PHP
include 'http://www.example.com/file.txt?foo=1&bar=2';
// Won't work; looks for a file named 'file.php?foo=1&bar=2' on the
// local filesystem.
include 'file.php?foo=1&bar=2';
// Works.
include 'http://www.example.com/file.php?foo=1&bar=2';
$foo = 1;
$bar = 2;
include 'file.txt'; // Works.
include 'file.php'; // Works.
?>
Security warning
Remote file may be processed at the remote server (depending on the file extension and the fact if the remote server runs PHP or not) but it still has to produce a valid PHP script because it will be processed at the local server. If the file from the remote server should be processed there and outputted only, readfile() is much better function to use. Otherwise, special care should be taken to secure the remote script to produce a valid and desired code.
See also Remote files, fopen() and file() for related information.
Handling Returns: It is possible to execute a return() statement inside an included file in order to terminate processing in that file and return to the script which called it. Also, it's possible to return values from included files. You can take the value of the include call as you would for a normal function. This is not, however, possible when including remote files unless the output of the remote file has valid PHP start and end tags (as with any local file). You can declare the needed variables within those tags and they will be introduced at whichever point the file was included.
Because include() is a special language construct, parentheses are not needed around its argument. Take care when comparing return value.
Przykład #4 Comparing return value of include
<?php
// won't work, evaluated as include(('vars.php') == 'OK'), i.e. include('')
if (include('vars.php') == 'OK') {
echo 'OK';
}
// works
if ((include 'vars.php') == 'OK') {
echo 'OK';
}
?>
Przykład #5 include() and the return() statement
return.php
<?php
$var = 'PHP';
return $var;
?>
noreturn.php
<?php
$var = 'PHP';
?>
testreturns.php
<?php
$foo = include 'return.php';
echo $foo; // prints 'PHP'
$bar = include 'noreturn.php';
echo $bar; // prints 1
?>
$bar is the value 1 because the include
was successful. Notice the difference between the above examples. The first uses
return() within the included file while the other does not.
If the file can't be included, FALSE is returned and
E_WARNING is issued.
If there are functions defined in the included file, they can be used in the main file independent if they are before return() or after. If the file is included twice, PHP 5 issues fatal error because functions were already declared, while PHP 4 doesn't complain about functions defined after return(). It is recommended to use include_once() instead of checking if the file was already included and conditionally return inside the included file.
Another way to "include" a PHP file into a variable is to capture the output by using the Output Control Functions with include(). For example:
Przykład #6 Using output buffering to include a PHP file into a string
<?php
$string = get_include_contents('somefile.php');
function get_include_contents($filename) {
if (is_file($filename)) {
ob_start();
include $filename;
return ob_get_clean();
}
return false;
}
?>
In order to automatically include files within scripts, see also the auto_prepend_file and auto_append_file configuration options in php.ini.
Informacja: Ponieważ jest to element składni języka a nie funkcja, nie może być on wywoływany używając zmiennych funkcji
See also require(), require_once(), include_once(), get_included_files(), readfile(), virtual(), and include_path.
require_once()
(PHP 4, PHP 5)
The require_once() statement is identical to require() except PHP will check if the file has already been included, and if so, not include (require) it again.
See the include_once() documentation for information about the _once behaviour, and how it differs from its non _once siblings.
include_once()
(PHP 4, PHP 5)
The include_once() statement includes and evaluates the specified file during the execution of the script. This is a behavior similar to the include() statement, with the only difference being that if the code from a file has already been included, it will not be included again. As the name suggests, it will be included just once.
include_once() may be used in cases where the same file might be included and evaluated more than once during a particular execution of a script, so in this case it may help avoid problems such as function redefinitions, variable value reassignments, etc.
See the include() documentation for information about how this function works.
Informacja:
With PHP 4, _once functionality differs with case-insensitive operating systems (like Windows) so for example:
Przykład #1 include_once() with a case insensitive OS in PHP 4
<?php
include_once "a.php"; // this will include a.php
include_once "A.php"; // this will include a.php again! (PHP 4 only)
?>This behaviour changed in PHP 5, so for example with Windows the path is normalized first so that C:\PROGRA~1\A.php is realized the same as C:\Program Files\a.php and the file is included just once.
goto
(PHP 5 >= 5.3.0)
The goto operator can be used to jump to another section in the program. The target point is specified by a label followed by a colon, and the instruction is given as goto followed by the desired target label. This is not a full unrestricted goto. The target label must be within the same file and context, meaning that you cannot jump out of a function or method, nor can you jump into one. You also cannot jump into any sort of loop or switch structure. You may jump out of these, and a common use is to use a goto in place of a multi-level break.
Przykład #1 goto example
<?php
goto a;
echo 'Foo';
a:
echo 'Bar';
?>
Powyższy przykład wyświetli:
Bar
Przykład #2 goto loop example
<?php
for($i=0,$j=50; $i<100; $i++) {
while($j--) {
if($j==17) goto end;
}
}
echo "i = $i";
end:
echo 'j hit 17';
?>
Powyższy przykład wyświetli:
j hit 17
Przykład #3 This will not work
<?php
goto loop;
for($i=0,$j=50; $i<100; $i++) {
while($j--) {
loop:
}
}
echo "$i = $i";
?>
Powyższy przykład wyświetli:
Fatal error: 'goto' into loop or switch statement is disallowed in script on line 2
Informacja:
The goto operator is available as of PHP 5.3.
Funkcje
Spis treści
- Funkcje definiowane przez użytkownika
- Argumenty funkcji
- Zwracanie wartości
- Funkcje zmiennych
- Wewnętrzne (wbudowane) funkcje
Funkcje definiowane przez użytkownika
Funkcja może być definiowana przy użyciu następującej składni:
Przykład #1 Pseudokod demonstrujący użycie funkcji
<?php
function foo($arg_1, $arg_2, /* ..., */ $arg_n)
{
echo "Przykładowa funkcja.\n";
return $retval;
}
?>
Każdy poprawny kod może być użyty wewnątrz funkcji, łącznie z definicjami innych funkcji i klas.
Nazwy funkcji obowiązują identyczne zasady, jak w przypadku wszystkich innych etykiet w PHP. Poprawna nazwa funkcji zaczyna się od litery lub podkreślnika, po których następuje dowolna ilość liter, cyfr i podkreślników. Jako wyrażenie regularne, określone zostałoby to następująco: [a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*.
Zobacz także Userland Naming Guide.
Funkcje nie muszą być zdefiniowane przed odniesieniem się do nich, oprócz sytuacji, w których funkcja jest zdefiniowana warunkowo jak w dwóch poniższych przykładach.
Kiedy funkcja jest zdefiniowana warunkowo, jak w dwóch poniższych przykładach, jej definicja musi być przetworzona przed jej wywołaniem.
Przykład #2 Funkcje zdefiniowane warunkowo
<?php
$makefoo = true;
/* Nie możemy tu wywołać foo()
ponieważ jeszcze nie istnieje,
ale możemy wywołać bar() */
bar();
if ($makefoo) {
function foo()
{
echo "Nie istnieję, dopóki nie zostanę wykonana.\n";
}
}
/* Teraz możemy bezpiecznie wywołać foo()
ponieważ $makefoo ma wartość logiczną 1 */
if ($makefoo) foo();
function bar()
{
echo "Istnieję od początku działania skryptu.\n";
}
?>
Przykład #3 Funkcje wewnątrz funkcji
<?php
function foo()
{
function bar()
{
echo "Nie istnieję, dopóki foo() nie jest wywołana.\n";
}
}
/* Nie możemy tu wywołać bar()
ponieważ jeszcze nie istnieje. */
foo();
/* Teraz możemy wywołać bar(),
wykonanie foo() spodowało
że jest to już możliwe. */
bar();
?>
Wszystkie funkcje i klasy w PHP mają globalny zasięg - mogą być wykonane poza funkcją, nawet jeśli były zdefiniowane wewnątrz niej, i odwrotnie.
PHP nie umożliwia przeładowywania funkcji, nie jest też możliwe usunięcie jej definicji lub redefiniowanie poprzednio określonych funkcji.
Informacja: Nazwy funkcji nie rozróżniają wielkości liter, ale dobrym zwyczajem jest wywoływanie ich w formie, w której zostały zdefiniowane.
Zarówno przyjmowanie różnej ilości argumentów jak i wartości domyślne argumentów są obsługiwane w funkcjach. Zobacz także opisy funkcji func_num_args(), func_get_arg(), i func_get_args() aby uzyskać więcej informacji.
W PHP jest możliwe wykonywanie rekurencyjnych funkcji. Unikaj jednak wywoływania rekurencyjnych funkcji/metod które osiągają poziom rekurencji większy niż 100-200, ponieważ może to spowodować przepełnienie stosu i zakończenie wykonywania skryptu.
Przykład #4 Funkcje rekurencyjne
<?php
function recursion($a)
{
if ($a < 20) {
echo "$a\n";
recursion($a + 1);
}
}
?>
Argumenty funkcji
Dane mogą być przekazywane do funkcji przez listę argumentów, która jest listą oddzielonych przecinkami wyrażeń.
PHP obsługuje podawanie argumentów jako wartości (domyślnie), przez referencję, oraz domyślne wartości argumentów. Różna ilość argumentów także jest obsługiwana, zobacz opisy funkcji func_num_args(), func_get_arg(), i func_get_args() aby dowiedzieć się więcej.
Przykład #1 Tablica jako argument funkcji
<?php
function takes_array($input)
{
echo "$input[0] + $input[1] = ", $input[0]+$input[1];
}
?>
Podawanie argumentów jako referencji
Domyślnie, argumenty funkcji podawane są jako wartości (kiedy wartość argumentu wewnątrz funkcji się zmienia, nie wpływa to na wartość zmiennej poza funkcją). Aby pozwolić funkcji na modyfikację jej jej argumentów, muszą one być podane przez referencję.
Aby argument zawsze był podawany przez referencję, poprzedź nazwę argumentu znakiem (&) w definicji funkcji:
Przykład #2 Podawanie parametrów funkcji przez referencję
<?php
function add_some_extra(&$string)
{
$string .= 'i coś ekstra.';
}
$str = 'To jest ciąg znaków, ';
add_some_extra($str);
echo $str; // wypisuje 'To jest ciąg znaków, i coś ekstra.'
?>
Domyślne wartości argumentów
Można zdefiniować domyślne wartości skalarne argumentów w stylu C++ następująco:
Przykład #3 Użycie domyślnych wartości argumentów w funkcji
<?php
function makecoffee($type = "cappuccino")
{
return "Robię kubek $type.\n";
}
echo makecoffee();
echo makecoffee(null);
echo makecoffee("espresso");
?>
Wynikiem powyższego kodu jest:
Robię kubek cappuccino.
Robię kubek .
Robię kubek espresso.
PHP pozwala również na użycie tablic(array) i specjalnego typu NULL
jako domyślnych wartości, na przykład:
Przykład #4 Użycie nie-skalarnych typów jako domyślnych wartości
<?php
function makecoffee($types = array("cappuccino"), $coffeeMaker = NULL)
{
$device = is_null($coffeeMaker) ? "rąk" : $coffeeMaker;
return "Robię kubek ".join(", ", $types)." za pomocą $device.\n";
}
echo makecoffee();
echo makecoffee(array("cappuccino", "lavazza"), "teapot");
?>
Domyślna wartość musi być stałym wyrażeniem, a nie na przykład zmienną, członkiem klasy czy wywołaniem funkcji.
Zauważ, że przy użyciu domyślnych wartości, powinne one być zdefiniowane po prawej stronie nie-domyślnych argumentów; W przeciwnym wypadku, nie zadziała to jak powinno. Na przykład:
Przykład #5 Niepoprawne użycie domyślnych wartości argumentów
<?php
function makeyogurt($type = "acidophilus", $flavour)
{
return "Making a bowl of $type $flavour.\n";
}
echo makeyogurt("raspberry"); // nie zadziała tak, jak oczekujemy
?>
Wynik powyższego skryptu to:
Warning: Missing argument 2 in call to makeyogurt() in
/usr/local/etc/httpd/htdocs/phptest/functest.html on line 41
Making a bowl of raspberry .
Porównaj go teraz z:
Przykład #6 Poprawne użycie domyślnych wartości argumentów
<?php
function makeyogurt($flavour, $type = "jogurtu")
{
return "Robię miskę $type $flavour.\n";
}
echo makeyogurt("malinowego"); // działa zgodnie z naszymi oczekiwaniami
?>
Wynikiem działania powyższego przykładu jest:
Robię miskę malinowego jogurtu.
Informacja: Od PHP 5 domyślne wartości argumentów mogą być podawane przez referencję.
Podawanie różnej ilości argumentów
Od PHP 4 możliwe jest użycie różnej ilości argumentów dla funkcji definiowanych przez użytkownika. Jest to dosyć proste przy użyciu funkcji func_num_args(), func_get_arg() i func_get_args().
Nie wymaga to żadnej specjalnej składni, listy argumentów w dalszym ciągu podawane są przy definiowaniu funkcji i zachowują się normalnie.
Zwracanie wartości
Wartości zwracane są przy użyciu opcjonalnego wyrażenia return. Wszystkie typy mogą być zwracane, łącznie z tablicami i obiektami. Powoduje to natychmiastowe zakończenie wykonywania funkcji i wznowienie wykonywania skryptu od linijki w której funkcja została wywołana. Zobacz return() aby uzyskać więcej informacji.
Przykład #1 Użycie return()
<?php
function square($num)
{
return $num * $num;
}
echo square(4); // wypisuje '16'.
?>
Funkcjia nie może zwracać wielu wartości, ale podobny efekt może zostać osiągnięty poprzez zwracanie tablicy.
Przykład #2 Zwracanie tablicy
<?php
function small_numbers()
{
return array (0, 1, 2);
}
list ($zero, $one, $two) = small_numbers();
?>
Aby zwrócić referencję, użyj operatora & zarówno w deklaracji funkcji jak i podczas przypisywania zwracanej wartości zmiennej:
Przykład #3 Zwracanie referencji
<?php
function &returns_reference()
{
return $someref;
}
$newref =& returns_reference();
?>
Aby uzyskać więcej informacji o referencjach, przejdź do Wyjaśnienie Referencji.
Funkcje zmiennych
PHP obsługuje opcję funkcji zmiennych. Oznacza to, że jeśli do nazwy zmiennej dodane są nawiasy, PHP postara się znaleźć funkcję o nazwie takiej jak wartość zmiennej i spróbuje ją wykonać. Między innymi, może to służyć do zaimplementowania tzw. callbacks, tablic funkcji, a także wielu innych rzeczy.
Funkcje zmiennych nie zadziałają z takimi elementami języka jak echo(), print(), unset(), isset(), empty(), include(), require() i podobnymi. Używaj okrężnych funkcji aby skorzystać z któregoś z powyższych elementów języka jako funkcji zmiennych.
Przykład #1 Przykład funkcji zmiennych
<?php
function foo() {
echo "W foo()<br />\n";
}
function bar($arg = '')
{
echo "W bar(); argumentem było '$arg'.<br />\n";
}
// To jest funkcja okrężna dla "echo"
function echoit($string)
{
echo $string;
}
$func = 'foo';
$func(); // Wywołuje foo()
$func = 'bar';
$func('test'); // Wywołuje bar()
$func = 'echoit';
$func('test'); // Wywołuje echoit()
?>
Jako funkcje zmiennych mogą być także wywoływane metody obiektów.
Przykład #2 Przykład metod zmiennych
<?php
class Foo
{
function Zmienna()
{
$name = 'Bar';
$this->$name(); // Wywołuje metodę Bar()
}
function Bar()
{
echo "To jest Bar";
}
}
$foo = new Foo();
$funcname = "Zmienna";
$foo->$funcname(); // Wywołuje $foo->Zmienna()
?>
Zobacz także call_user_func(), zmienne zmienne oraz function_exists().
Wewnętrzne (wbudowane) funkcje
PHP zapewnia wiele wbudowanych funkcji i konstrukcji. Istnieją także funkcje wymagające wkompilowania specyficznych rozszerzeń PHP, w przeciwnym wypadku wywołanie ich skutkuje błędami "undefined function". Na przykładd, aby użyć funkcji obrazków takich jak imagecreatetruecolor(), PHP musi być skompilowane z obsługą GD. Aby użyć mysql_connect(), PHP musi być skompilowane z obsługą MySQL. Jest wiele funkcji wbudowanych w rdzeń każdej wersji PHP, takich jak funkcje typu string oraz zmiennych. Wywołanie to phpinfo() lub get_loaded_extensions() pokaże, które rozszerzenia PHP są załadowane. Zauważ, że wiele rozszerzeń jest domyślnie załadowanych i podręcznik PHP jest podzielony według rozszerzeń. Zobacz rozdziały o konfiguracji, instalacji, a także te dotyczące poszczególnych rozszerzeń, aby dowiedzieć się jak uruchomić PHP.
Czytanie i rozumienie prototypów funkcji wyjaśnione jest w rozdziale podręcznika zatytułowanym jak czytać definicje funkcji. Ważne jest zrozumienie, czy funkcja zwraca konkretną wartość czy operuje bezpośrednio na podanej zmiennej. Na przykład, str_replace() zwróci zmodyfikowany obiekt typu string, podczas gdy usort() pracuje bezpośrednio na podanej zmiennej. Każda funkcja posiada swoją stronę w podręczniku PHP, która podaje informacje takie jak parametry funkcji, jej zachowanie, wartości zwracane po poprawnym wykonaniu i w przypadku błędu, a także dane dotyczące jej dostępności. Znanie tych ważnych (chociaż często drobnych) różnic jest kluczowe podczas pisania kodu w PHP.
Informacja: Jeśli parametry podane funkcji nie są takie, jak spodziewane, na przykład tablica(array) podawana jest w miejscu, gdzie oczekiwana jest zmienna typu string, wartość zwracana przez funkcję nie jest zdefiniowana. W takim wypadku funkcja prawdopodobnie zwróci
NULLale jest to jedynie konwencja a nie zasada, na której można się opierać.
Zobacz także function_exists(), the function reference, get_extension_funcs() i dl().
Classes and Objects
Spis treści
- Introduction
- The Basics
- Properties
- Class Constants
- Autoloading Classes
- Constructors and Destructors
- Visibility
- Object Inheritance
- Scope Resolution Operator (::)
- Static Keyword
- Class Abstraction
- Object Interfaces
- Traits
- Overloading
- Object Iteration
- Patterns
- Magic Methods
- Final Keyword
- Object Cloning
- Comparing Objects
- Type Hinting
- Late Static Bindings
- Objects and references
- Object Serialization
- OOP Changelog
Introduction
Starting with PHP 5, the object model was rewritten to allow for better performance and more features. This was a major change from PHP 4. PHP 5 has a full object model.
Among the features in PHP 5 are the inclusions of visibility, abstract and final classes and methods, additional magic methods, interfaces, cloning and typehinting.
PHP treats objects in the same way as references or handles, meaning that each variable contains an object reference rather than a copy of the entire object. See Objects and References
Zobacz także Userland Naming Guide.
The Basics
class
Basic class definitions begin with the keyword class, followed by a class name, followed by a pair of curly braces which enclose the definitions of the properties and methods belonging to the class.
The class name can be any valid label which is a not a PHP reserved word. A valid class name starts with a letter or underscore, followed by any number of letters, numbers, or underscores. As a regular expression, it would be expressed thus: [a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*.
A class may contain its own constants, variables (called "properties"), and functions (called "methods").
Przykład #1 Simple Class definition
<?php
class SimpleClass
{
// property declaration
public $var = 'a default value';
// method declaration
public function displayVar() {
echo $this->var;
}
}
?>
The pseudo-variable $this is available when a method is called from within an object context. $this is a reference to the calling object (usually the object to which the method belongs, but possibly another object, if the method is called statically from the context of a secondary object).
Przykład #2 Some examples of the $this pseudo-variable
<?php
class A
{
function foo()
{
if (isset($this)) {
echo '$this is defined (';
echo get_class($this);
echo ")\n";
} else {
echo "\$this is not defined.\n";
}
}
}
class B
{
function bar()
{
// Note: the next line will issue a warning if E_STRICT is enabled.
A::foo();
}
}
$a = new A();
$a->foo();
// Note: the next line will issue a warning if E_STRICT is enabled.
A::foo();
$b = new B();
$b->bar();
// Note: the next line will issue a warning if E_STRICT is enabled.
B::bar();
?>
Powyższy przykład wyświetli:
$this is defined (A) $this is not defined. $this is defined (B) $this is not defined.
new
To create an instance of a class, the new keyword must be used. An object will always be created unless the object has a constructor defined that throws an exception on error. Classes should be defined before instantiation (and in some cases this is a requirement).
If a string containing the name of a class is used with new, a new instance of that class will be created. If the class is in a namespace, its fully qualified name must be used when doing this.
Przykład #3 Creating an instance
<?php
$instance = new SimpleClass();
// This can also be done with a variable:
$className = 'Foo';
$instance = new $className(); // Foo()
?>
In the class context, it is possible to create a new object by new self and new parent.
When assigning an already created instance of a class to a new variable, the new variable will access the same instance as the object that was assigned. This behaviour is the same when passing instances to a function. A copy of an already created object can be made by cloning it.
Przykład #4 Object Assignment
<?php
$instance = new SimpleClass();
$assigned = $instance;
$reference =& $instance;
$instance->var = '$assigned will have this value';
$instance = null; // $instance and $reference become null
var_dump($instance);
var_dump($reference);
var_dump($assigned);
?>
Powyższy przykład wyświetli:
NULL
NULL
object(SimpleClass)#1 (1) {
["var"]=>
string(30) "$assigned will have this value"
}
PHP 5.3.0 introduced a couple of new ways to create instances of an object:
Przykład #5 Creating new objects
<?php
class Test
{
static public function getNew()
{
return new static;
}
}
class Child extends Test
{}
$obj1 = new Test();
$obj2 = new $obj1;
var_dump($obj1 !== $obj2);
$obj3 = Test::getNew();
var_dump($obj3 instanceof Test);
$obj4 = Child::getNew();
var_dump($obj4 instanceof Child);
?>
Powyższy przykład wyświetli:
bool(true) bool(true) bool(true)
extends
A class can inherit the methods and properties of another class by using the keyword extends in the class declaration. It is not possible to extend multiple classes; a class can only inherit from one base class.
The inherited methods and properties can be overridden by redeclaring them with the same name defined in the parent class. However, if the parent class has defined a method as final, that method may not be overridden. It is possible to access the overridden methods or static properties by referencing them with parent::.
When overriding methods, the parameter signature should remain the same or
PHP will generate an E_STRICT level error. This does
not apply to the constructor, which allows overriding with different
parameters.
Przykład #6 Simple Class Inheritance
<?php
class ExtendClass extends SimpleClass
{
// Redefine the parent method
function displayVar()
{
echo "Extending class\n";
parent::displayVar();
}
}
$extended = new ExtendClass();
$extended->displayVar();
?>
Powyższy przykład wyświetli:
Extending class a default value
Properties
Class member variables are called "properties". You may also see them referred to using other terms such as "attributes" or "fields", but for the purposes of this reference we will use "properties". They are defined by using one of the keywords public, protected, or private, followed by a normal variable declaration. This declaration may include an initialization, but this initialization must be a constant value--that is, it must be able to be evaluated at compile time and must not depend on run-time information in order to be evaluated.
See Visibility for more information on the meanings of public, protected, and private.
Informacja:
In order to maintain backward compatibility with PHP 4, PHP 5 will still accept the use of the keyword var in property declarations instead of (or in addition to) public, protected, or private. However, var is no longer required. In versions of PHP from 5.0 to 5.1.3, the use of var was considered deprecated and would issue an
E_STRICTwarning, but since PHP 5.1.3 it is no longer deprecated and does not issue the warning.If you declare a property using var instead of one of public, protected, or private, then PHP 5 will treat the property as if it had been declared as public.
Within class methods the properties, constants, and methods may be accessed by using the form $this->property (where property is the name of the property) unless the access is to a static property within the context of a static class method, in which case it is accessed using the form self::$property. See Static Keyword for more information.
The pseudo-variable $this is available inside any class method when that method is called from within an object context. $this is a reference to the calling object (usually the object to which the method belongs, but possibly another object, if the method is called statically from the context of a secondary object).
Przykład #1 property declarations
<?php
class SimpleClass
{
// invalid property declarations:
public $var1 = 'hello ' . 'world';
public $var2 = <<<EOD
hello world
EOD;
public $var3 = 1+2;
public $var4 = self::myStaticMethod();
public $var5 = $myVar;
// valid property declarations:
public $var6 = myConstant;
public $var7 = array(true, false);
// This is allowed only in PHP 5.3.0 and later.
public $var8 = <<<'EOD'
hello world
EOD;
}
?>
Informacja:
There are some nice functions to handle classes and objects. You might want to take a look at the Class/Object Functions.
Unlike heredocs, nowdocs can be used in any static data context, including property declarations.
Przykład #2 Example of using a nowdoc to initialize a property
<?php
class foo {
// As of PHP 5.3.0
public $bar = <<<'EOT'
bar
EOT;
}
?>
Informacja:
Nowdoc support was added in PHP 5.3.0.
Class Constants
It is possible to define constant values on a per-class basis remaining the same and unchangeable. Constants differ from normal variables in that you don't use the $ symbol to declare or use them.
The value must be a constant expression, not (for example) a variable, a property, a result of a mathematical operation, or a function call.
It's also possible for interfaces to have constants. Look at the interface documentation for examples.
As of PHP 5.3.0, it's possible to reference the class using a variable. The variable's value can not be a keyword (e.g. self, parent and static).
Przykład #1 Defining and using a constant
<?php
class MyClass
{
const constant = 'constant value';
function showConstant() {
echo self::constant . "\n";
}
}
echo MyClass::constant . "\n";
$classname = "MyClass";
echo $classname::constant . "\n"; // As of PHP 5.3.0
$class = new MyClass();
$class->showConstant();
echo $class::constant."\n"; // As of PHP 5.3.0
?>
Przykład #2 Static data example
<?php
class foo {
// As of PHP 5.3.0
const bar = <<<'EOT'
bar
EOT;
}
?>
Unlike heredocs, nowdocs can be used in any static data context.
Informacja:
Nowdoc support was added in PHP 5.3.0.
Autoloading Classes
Many developers writing object-oriented applications create one PHP source file per-class definition. One of the biggest annoyances is having to write a long list of needed includes at the beginning of each script (one for each class).
In PHP 5, this is no longer necessary. You may define an __autoload() function which is automatically called in case you are trying to use a class/interface which hasn't been defined yet. By calling this function the scripting engine is given a last chance to load the class before PHP fails with an error.
spl_autoload_register() provides a more flexible alternative for autoloading classes. For this reason, using __autoload() is discouraged and may be deprecated or removed in the future.
Informacja:
Prior to 5.3.0, exceptions thrown in the __autoload function could not be caught in the catch block and would result in a fatal error. From 5.3.0+ exceptions thrown in the __autoload function can be caught in the catch block, with 1 provision. If throwing a custom exception, then the custom exception class must be available. The __autoload function may be used recursively to autoload the custom exception class.
Informacja:
Autoloading is not available if using PHP in CLI interactive mode.
Informacja:
If the class name is used e.g. in call_user_func() then it can contain some dangerous characters such as ../. It is recommended to not use the user-input in such functions or at least verify the input in __autoload().
Przykład #1 Autoload example
This example attempts to load the classes MyClass1 and MyClass2 from the files MyClass1.php and MyClass2.php respectively.
<?php
function __autoload($class_name) {
include $class_name . '.php';
}
$obj = new MyClass1();
$obj2 = new MyClass2();
?>
Przykład #2 Autoload other example
This example attempts to load the interface ITest.
<?php
function __autoload($name) {
var_dump($name);
}
class Foo implements ITest {
}
/*
string(5) "ITest"
Fatal error: Interface 'ITest' not found in ...
*/
?>
Przykład #3 Autoloading with exception handling for 5.3.0+
This example throws an exception and demonstrates the try/catch block.
<?php
function __autoload($name) {
echo "Want to load $name.\n";
throw new Exception("Unable to load $name.");
}
try {
$obj = new NonLoadableClass();
} catch (Exception $e) {
echo $e->getMessage(), "\n";
}
?>
Powyższy przykład wyświetli:
Want to load NonLoadableClass. Unable to load NonLoadableClass.
Przykład #4 Autoloading with exception handling for 5.3.0+ - Missing custom exception
This example throws an exception for a non-loadable, custom exception.
<?php
function __autoload($name) {
echo "Want to load $name.\n";
throw new MissingException("Unable to load $name.");
}
try {
$obj = new NonLoadableClass();
} catch (Exception $e) {
echo $e->getMessage(), "\n";
}
?>
Powyższy przykład wyświetli:
Want to load NonLoadableClass. Want to load MissingException. Fatal error: Class 'MissingException' not found in testMissingException.php on line 4
Constructors and Destructors
Constructor
PHP 5 allows developers to declare constructor methods for classes. Classes which have a constructor method call this method on each newly-created object, so it is suitable for any initialization that the object may need before it is used.
Informacja: Parent constructors are not called implicitly if the child class defines a constructor. In order to run a parent constructor, a call to parent::__construct() within the child constructor is required.
Przykład #1 using new unified constructors
<?php
class BaseClass {
function __construct() {
print "In BaseClass constructor\n";
}
}
class SubClass extends BaseClass {
function __construct() {
parent::__construct();
print "In SubClass constructor\n";
}
}
$obj = new BaseClass();
$obj = new SubClass();
?>
For backwards compatibility, if PHP 5 cannot find a __construct() function for a given class, it will search for the old-style constructor function, by the name of the class. Effectively, it means that the only case that would have compatibility issues is if the class had a method named __construct() which was used for different semantics.
Unlike with other methods, PHP will not generate an
E_STRICT level error message when
__construct() is overridden with different parameters
than the parent __construct() method has.
As of PHP 5.3.3, methods with the same name as the last element of a namespaced class name will no longer be treated as constructor. This change doesn't affect non-namespaced classes.
Przykład #2 Constructors in namespaced classes
<?php
namespace Foo;
class Bar {
public function Bar() {
// treated as constructor in PHP 5.3.0-5.3.2
// treated as regular method as of PHP 5.3.3
}
}
?>
Destructor
PHP 5 introduces a destructor concept similar to that of other object-oriented languages, such as C++. The destructor method will be called as soon as there are no other references to a particular object, or in any order during the shutdown sequence.
Przykład #3 Destructor Example
<?php
class MyDestructableClass {
function __construct() {
print "In constructor\n";
$this->name = "MyDestructableClass";
}
function __destruct() {
print "Destroying " . $this->name . "\n";
}
}
$obj = new MyDestructableClass();
?>
Like constructors, parent destructors will not be called implicitly by the engine. In order to run a parent destructor, one would have to explicitly call parent::__destruct() in the destructor body.
The destructor will be called even if script execution is stopped using exit(). Calling exit() in a destructor will prevent the remaining shutdown routines from executing.
Informacja:
Destructors called during the script shutdown have HTTP headers already sent. The working directory in the script shutdown phase can be different with some SAPIs (e.g. Apache).
Informacja:
Attempting to throw an exception from a destructor (called in the time of script termination) causes a fatal error.
Visibility
The visibility of a property or method can be defined by prefixing the declaration with the keywords public, protected or private. Class members declared public can be accessed everywhere. Members declared protected can be accessed only within the class itself and by inherited and parent classes. Members declared as private may only be accessed by the class that defines the member.
Property Visibility
Class properties must be defined as public, private, or protected. If declared using var, the property will be defined as public.
Przykład #1 Property declaration
<?php
/**
* Define MyClass
*/
class MyClass
{
public $public = 'Public';
protected $protected = 'Protected';
private $private = 'Private';
function printHello()
{
echo $this->public;
echo $this->protected;
echo $this->private;
}
}
$obj = new MyClass();
echo $obj->public; // Works
echo $obj->protected; // Fatal Error
echo $obj->private; // Fatal Error
$obj->printHello(); // Shows Public, Protected and Private
/**
* Define MyClass2
*/
class MyClass2 extends MyClass
{
// We can redeclare the public and protected method, but not private
protected $protected = 'Protected2';
function printHello()
{
echo $this->public;
echo $this->protected;
echo $this->private;
}
}
$obj2 = new MyClass2();
echo $obj2->public; // Works
echo $obj2->private; // Undefined
echo $obj2->protected; // Fatal Error
$obj2->printHello(); // Shows Public, Protected2, Undefined
?>
Informacja: The PHP 4 method of declaring a variable with the var keyword is still supported for compatibility reasons (as a synonym for the public keyword). In PHP 5 before 5.1.3, its usage would generate an
E_STRICTwarning.
Method Visibility
Class methods may be defined as public, private, or protected. Methods declared without any explicit visibility keyword are defined as public.
Przykład #2 Method Declaration
<?php
/**
* Define MyClass
*/
class MyClass
{
// Declare a public constructor
public function __construct() { }
// Declare a public method
public function MyPublic() { }
// Declare a protected method
protected function MyProtected() { }
// Declare a private method
private function MyPrivate() { }
// This is public
function Foo()
{
$this->MyPublic();
$this->MyProtected();
$this->MyPrivate();
}
}
$myclass = new MyClass;
$myclass->MyPublic(); // Works
$myclass->MyProtected(); // Fatal Error
$myclass->MyPrivate(); // Fatal Error
$myclass->Foo(); // Public, Protected and Private work
/**
* Define MyClass2
*/
class MyClass2 extends MyClass
{
// This is public
function Foo2()
{
$this->MyPublic();
$this->MyProtected();
$this->MyPrivate(); // Fatal Error
}
}
$myclass2 = new MyClass2;
$myclass2->MyPublic(); // Works
$myclass2->Foo2(); // Public and Protected work, not Private
class Bar
{
public function test() {
$this->testPrivate();
$this->testPublic();
}
public function testPublic() {
echo "Bar::testPublic\n";
}
private function testPrivate() {
echo "Bar::testPrivate\n";
}
}
class Foo extends Bar
{
public function testPublic() {
echo "Foo::testPublic\n";
}
private function testPrivate() {
echo "Foo::testPrivate\n";
}
}
$myFoo = new foo();
$myFoo->test(); // Bar::testPrivate
// Foo::testPublic
?>
Visibility from other objects
Objects of the same type will have access to each others private and protected members even though they are not the same instances. This is because the implementation specific details are already known when inside those objects.
Przykład #3 Accessing private members of the same object type
<?php
class Test
{
private $foo;
public function __construct($foo)
{
$this->foo = $foo;
}
private function bar()
{
echo 'Accessed the private method.';
}
public function baz(Test $other)
{
// We can change the private property:
$other->foo = 'hello';
var_dump($other->foo);
// We can also call the private method:
$other->bar();
}
}
$test = new Test('test');
$test->baz(new Test('other'));
?>
Powyższy przykład wyświetli:
string(5) "hello" Accessed the private method.
Object Inheritance
Inheritance is a well-established programming principle, and PHP makes use of this principle in its object model. This principle will affect the way many classes and objects relate to one another.
For example, when you extend a class, the subclass inherits all of the public and protected methods from the parent class. Unless a class overrides those methods, they will retain their original functionality.
This is useful for defining and abstracting functionality, and permits the implementation of additional functionality in similar objects without the need to reimplement all of the shared functionality.
Informacja:
Unless autoloading is used, then classes must be defined before they are used. If a class extends another, then the parent class must be declared before the child class structure. This rule applies to classes that inherit other classes and interfaces.
Przykład #1 Inheritance Example
<?php
class foo
{
public function printItem($string)
{
echo 'Foo: ' . $string . PHP_EOL;
}
public function printPHP()
{
echo 'PHP is great.' . PHP_EOL;
}
}
class bar extends foo
{
public function printItem($string)
{
echo 'Bar: ' . $string . PHP_EOL;
}
}
$foo = new foo();
$bar = new bar();
$foo->printItem('baz'); // Output: 'Foo: baz'
$foo->printPHP(); // Output: 'PHP is great'
$bar->printItem('baz'); // Output: 'Bar: baz'
$bar->printPHP(); // Output: 'PHP is great'
?>
Scope Resolution Operator (::)
The Scope Resolution Operator (also called Paamayim Nekudotayim) or in simpler terms, the double colon, is a token that allows access to static, constant, and overridden properties or methods of a class.
When referencing these items from outside the class definition, use the name of the class.
As of PHP 5.3.0, it's possible to reference the class using a variable. The variable's value can not be a keyword (e.g. self, parent and static).
Paamayim Nekudotayim would, at first, seem like a strange choice for naming a double-colon. However, while writing the Zend Engine 0.5 (which powers PHP 3), that's what the Zend team decided to call it. It actually does mean double-colon - in Hebrew!
Przykład #1 :: from outside the class definition
<?php
class MyClass {
const CONST_VALUE = 'A constant value';
}
$classname = 'MyClass';
echo $classname::CONST_VALUE; // As of PHP 5.3.0
echo MyClass::CONST_VALUE;
?>
Three special keywords self, parent and static are used to access properties or methods from inside the class definition.
Przykład #2 :: from inside the class definition
<?php
class OtherClass extends MyClass
{
public static $my_static = 'static var';
public static function doubleColon() {
echo parent::CONST_VALUE . "\n";
echo self::$my_static . "\n";
}
}
$classname = 'OtherClass';
echo $classname::doubleColon(); // As of PHP 5.3.0
OtherClass::doubleColon();
?>
When an extending class overrides the parents definition of a method, PHP will not call the parent's method. It's up to the extended class on whether or not the parent's method is called. This also applies to Constructors and Destructors, Overloading, and Magic method definitions.
Przykład #3 Calling a parent's method
<?php
class MyClass
{
protected function myFunc() {
echo "MyClass::myFunc()\n";
}
}
class OtherClass extends MyClass
{
// Override parent's definition
public function myFunc()
{
// But still call the parent function
parent::myFunc();
echo "OtherClass::myFunc()\n";
}
}
$class = new OtherClass();
$class->myFunc();
?>
See also some examples of static call trickery.
Static Keyword
Declaring class properties or methods as static makes them accessible without needing an instantiation of the class. A property declared as static can not be accessed with an instantiated class object (though a static method can).
For compatibility with PHP 4, if no visibility declaration is used, then the property or method will be treated as if it was declared as public.
Because static methods are callable without an instance of the object created, the pseudo-variable $this is not available inside the method declared as static.
Static properties cannot be accessed through the object using the arrow operator ->.
Calling non-static methods statically generates an E_STRICT level warning.
Like any other PHP static variable, static properties may only be initialized using a literal or constant; expressions are not allowed. So while you may initialize a static property to an integer or array (for instance), you may not initialize it to another variable, to a function return value, or to an object.
As of PHP 5.3.0, it's possible to reference the class using a variable. The variable's value can not be a keyword (e.g. self, parent and static).
Przykład #1 Static property example
<?php
class Foo
{
public static $my_static = 'foo';
public function staticValue() {
return self::$my_static;
}
}
class Bar extends Foo
{
public function fooStatic() {
return parent::$my_static;
}
}
print Foo::$my_static . "\n";
$foo = new Foo();
print $foo->staticValue() . "\n";
print $foo->my_static . "\n"; // Undefined "Property" my_static
print $foo::$my_static . "\n";
$classname = 'Foo';
print $classname::$my_static . "\n"; // As of PHP 5.3.0
print Bar::$my_static . "\n";
$bar = new Bar();
print $bar->fooStatic() . "\n";
?>
Przykład #2 Static method example
<?php
class Foo {
public static function aStaticMethod() {
// ...
}
}
Foo::aStaticMethod();
$classname = 'Foo';
$classname::aStaticMethod(); // As of PHP 5.3.0
?>
Class Abstraction
PHP 5 introduces abstract classes and methods. Classes defined as abstract may not be instantiated, and any class that contains at least one abstract method must also be abstract. Methods defined as abstract simply declare the method's signature - they cannot define the implementation.
When inheriting from an abstract class, all methods marked abstract in the parent's class declaration must be defined by the child; additionally, these methods must be defined with the same (or a less restricted) visibility. For example, if the abstract method is defined as protected, the function implementation must be defined as either protected or public, but not private. Furthermore the signatures of the methods must match, i.e. the type hints and the number of required arguments must be the same. This also applies to constructors as of PHP 5.4. Before 5.4 constructor signatures could differ.
Przykład #1 Abstract class example
<?php
abstract class AbstractClass
{
// Force Extending class to define this method
abstract protected function getValue();
abstract protected function prefixValue($prefix);
// Common method
public function printOut() {
print $this->getValue() . "\n";
}
}
class ConcreteClass1 extends AbstractClass
{
protected function getValue() {
return "ConcreteClass1";
}
public function prefixValue($prefix) {
return "{$prefix}ConcreteClass1";
}
}
class ConcreteClass2 extends AbstractClass
{
public function getValue() {
return "ConcreteClass2";
}
public function prefixValue($prefix) {
return "{$prefix}ConcreteClass2";
}
}
$class1 = new ConcreteClass1;
$class1->printOut();
echo $class1->prefixValue('FOO_') ."\n";
$class2 = new ConcreteClass2;
$class2->printOut();
echo $class2->prefixValue('FOO_') ."\n";
?>
Powyższy przykład wyświetli:
ConcreteClass1 FOO_ConcreteClass1 ConcreteClass2 FOO_ConcreteClass2
Old code that has no user-defined classes or functions named 'abstract' should run without modifications.
Object Interfaces
Object interfaces allow you to create code which specifies which methods a class must implement, without having to define how these methods are handled.
Interfaces are defined using the interface keyword, in the same way as a standard class, but without any of the methods having their contents defined.
All methods declared in an interface must be public, this is the nature of an interface.
implements
To implement an interface, the implements operator is used. All methods in the interface must be implemented within a class; failure to do so will result in a fatal error. Classes may implement more than one interface if desired by separating each interface with a comma.
Informacja:
A class cannot implement two interfaces that share function names, since it would cause ambiguity.
Informacja:
Interfaces can be extended like classes using the extends operator.
Informacja:
The class implementing the interface must use the exact same method signatures as are defined in the interface. Not doing so will result in a fatal error.
Constants
It's possible for interfaces to have constants. Interface constants works exactly like class constants except they cannot be overridden by a class/interface that inherits them.
Przykłady
Przykład #1 Interface example
<?php
// Declare the interface 'iTemplate'
interface iTemplate
{
public function setVariable($name, $var);
public function getHtml($template);
}
// Implement the interface
// This will work
class Template implements iTemplate
{
private $vars = array();
public function setVariable($name, $var)
{
$this->vars[$name] = $var;
}
public function getHtml($template)
{
foreach($this->vars as $name => $value) {
$template = str_replace('{' . $name . '}', $value, $template);
}
return $template;
}
}
// This will not work
// Fatal error: Class BadTemplate contains 1 abstract methods
// and must therefore be declared abstract (iTemplate::getHtml)
class BadTemplate implements iTemplate
{
private $vars = array();
public function setVariable($name, $var)
{
$this->vars[$name] = $var;
}
}
?>
Przykład #2 Extendable Interfaces
<?php
interface a
{
public function foo();
}
interface b extends a
{
public function baz(Baz $baz);
}
// This will work
class c implements b
{
public function foo()
{
}
public function baz(Baz $baz)
{
}
}
// This will not work and result in a fatal error
class d implements b
{
public function foo()
{
}
public function baz(Foo $foo)
{
}
}
?>
Przykład #3 Multiple interface inheritance
<?php
interface a
{
public function foo();
}
interface b
{
public function bar();
}
interface c extends a, b
{
public function baz();
}
class d implements c
{
public function foo()
{
}
public function bar()
{
}
public function baz()
{
}
}
?>
Przykład #4 Interfaces with constants
<?php
interface a
{
const b = 'Interface constant';
}
// Prints: Interface constant
echo a::b;
// This will however not work because it's not allowed to
// override constants.
class b implements a
{
const b = 'Class constant';
}
?>
An interface, together with type-hinting, provides a good way to make sure that a particular object contains particular methods. See instanceof operator and type hinting.
Traits
As of PHP 5.4.0, PHP implements a method of code reuse called Traits.
Traits is a mechanism for code reuse in single inheritance languages such as PHP. A Trait is intended to reduce some limitations of single inheritance by enabling a developer to reuse sets of methods freely in several independent classes living in different class hierarchies. The semantics of the combination of Traits and classes is defined in a way which reduces complexity, and avoids the typical problems associated with multiple inheritance and Mixins.
A Trait is similar to a class, but only intended to group functionality in a fine-grained and consistent way. It is not possible to instantiate a Trait on its own. It is an addition to traditional inheritance and enables horizontal composition of behavior; that is, the application of class members without requiring inheritance.
Przykład #1 Trait example
<?php
trait ezcReflectionReturnInfo {
function getReturnType() { /*1*/ }
function getReturnDescription() { /*2*/ }
}
class ezcReflectionMethod extends ReflectionMethod {
use ezcReflectionReturnInfo;
/* ... */
}
class ezcReflectionFunction extends ReflectionFunction {
use ezcReflectionReturnInfo;
/* ... */
}
?>
Precedence
An inherited member from a base class is overridden by a member inserted by a Trait. The precedence order is that members from the current class override Trait methods, which in return override inherited methods.
Przykład #2 Precedence Order Example
An inherited method from a base class is overridden by the method inserted into MyHelloWorld from the SayWorld Trait. The behavior is the same for methods defined in the MyHelloWorld class. The precedence order is that methods from the current class override Trait methods, which in turn override methods from the base class.
<?php
class Base {
public function sayHello() {
echo 'Hello ';
}
}
trait SayWorld {
public function sayHello() {
parent::sayHello();
echo 'World!';
}
}
class MyHelloWorld extends Base {
use SayWorld;
}
$o = new MyHelloWorld();
$o->sayHello();
?>
Powyższy przykład wyświetli:
Hello World!
Przykład #3 Alternate Precedence Order Example
<?php
trait HelloWorld {
public function sayHello() {
echo 'Hello World!';
}
}
class TheWorldIsNotEnough {
use HelloWorld;
public function sayHello() {
echo 'Hello Universe!';
}
}
$o = new TheWorldIsNotEnough();
$o->sayHello();
?>
Powyższy przykład wyświetli:
Hello Universe!
Multiple Traits
Multiple Traits can be inserted into a class by listing them in the use statement, separated by commas.
Przykład #4 Multiple Traits Usage
<?php
trait Hello {
public function sayHello() {
echo 'Hello ';
}
}
trait World {
public function sayWorld() {
echo 'World';
}
}
class MyHelloWorld {
use Hello, World;
public function sayExclamationMark() {
echo '!';
}
}
$o = new MyHelloWorld();
$o->sayHello();
$o->sayWorld();
$o->sayExclamationMark();
?>
Powyższy przykład wyświetli:
Hello World!
Conflict Resolution
If two Traits insert a method with the same name, a fatal error is produced, if the conflict is not explicitly resolved.
To resolve naming conflicts between Traits used in the same class, the insteadof operator needs to be used to chose exactly one of the conflicting methods.
Since this only allows one to exclude methods, the as operator can be used to allow the inclusion of one of the conflicting methods under another name.
Przykład #5 Conflict Resolution
In this example, Talker uses the traits A and B. Since A and B have conflicting methods, it defines to use the variant of smallTalk from trait B, and the variant of bigTalk from trait A.
The Aliased_Talker makes use of the as operator to be able to use B's bigTalk implementation under an additional alias talk.
<?php
trait A {
public function smallTalk() {
echo 'a';
}
public function bigTalk() {
echo 'A';
}
}
trait B {
public function smallTalk() {
echo 'b';
}
public function bigTalk() {
echo 'B';
}
}
class Talker {
use A, B {
B::smallTalk insteadof A;
A::bigTalk insteadof B;
}
}
class Aliased_Talker {
use A, B {
B::smallTalk insteadof A;
A::bigTalk insteadof B;
B::bigTalk as talk;
}
}
?>
Changing Method Visibility
Using the as syntax, one can also adjust the visibility of the method in the exhibiting class.
Przykład #6 Changing Method Visibility
<?php
trait HelloWorld {
public function sayHello() {
echo 'Hello World!';
}
}
// Change visibility of sayHello
class MyClass1 {
use HelloWorld { sayHello as protected; }
}
// Alias method with changed visibility
// sayHello visibility not changed
class MyClass2 {
use HelloWorld { sayHello as private myPrivateHello; }
}
?>
Traits Composed from Traits
Just as classes can make use of traits, so can other traits. By using one or more traits in a trait definition, it can be composed partially or entirely of the members defined in those other traits.
Przykład #7 Traits Composed from Traits
<?php
trait Hello {
public function sayHello() {
echo 'Hello ';
}
}
trait World {
public function sayWorld() {
echo 'World!';
}
}
trait HelloWorld {
use Hello, World;
}
class MyHelloWorld {
use HelloWorld;
}
$o = new MyHelloWorld();
$o->sayHello();
$o->sayWorld();
?>
Powyższy przykład wyświetli:
Hello World!
Abstract Trait Members
Traits support the use of abstract methods in order to impose requirements upon the exhibiting class.
Przykład #8 Express Requirements by Abstract Methods
<?php
trait Hello {
public function sayHelloWorld() {
echo 'Hello'.$this->getWorld();
}
abstract public function getWorld();
}
class MyHelloWorld {
private $world;
use Hello;
public function getWorld() {
return $this->world;
}
public function setWorld($val) {
$this->world = $val;
}
}
?>
Static Trait Members
Static variables can be referred to in trait methods, but cannot be defined by the trait. Traits can, however, define static methods for the exhibiting class.
Przykład #9 Static Variables
<?php
trait Counter {
public function inc() {
static $c = 0;
$c = $c + 1;
echo "$c\n";
}
}
class C1 {
use Counter;
}
class C2 {
use Counter;
}
$o = new C1(); $o->inc(); // echo 1
$p = new C2(); $p->inc(); // echo 1
?>
Przykład #10 Static Methods
<?php
trait StaticExample {
public static function doSomething() {
return 'Doing something';
}
}
class Example {
use StaticExample;
}
Example::doSomething();
?>
Properties
Traits can also define properties.
Przykład #11 Defining Properties
<?php
trait PropertiesTrait {
public $x = 1;
}
class PropertiesExample {
use PropertiesTrait;
}
$example = new PropertiesExample;
$example->x;
?>
If a trait defines a property then a class can not define a property with
the same name, otherwise an error is issued. It is an
E_STRICT if the class definition is compatible (same
visibility and initial value) or fatal error otherwise.
Przykład #12 Conflict Resolution
<?php
trait PropertiesTrait {
public $same = true;
public $different = false;
}
class PropertiesExample {
use PropertiesTrait;
public $same = true; // Strict Standards
public $different = true; // Fatal error
}
?>
Overloading
Overloading in PHP provides means to dynamically "create" properties and methods. These dynamic entities are processed via magic methods one can establish in a class for various action types.
The overloading methods are invoked when interacting with properties or methods that have not been declared or are not visible in the current scope. The rest of this section will use the terms "inaccessible properties" and "inaccessible methods" to refer to this combination of declaration and visibility.
All overloading methods must be defined as public.
Informacja:
None of the arguments of these magic methods can be passed by reference.
Informacja:
PHP's interpretation of "overloading" is different than most object oriented languages. Overloading traditionally provides the ability to have multiple methods with the same name but different quantities and types of arguments.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.0 | Added __callStatic(). Added warning to enforce public visibility and non-static declaration. |
| 5.1.0 | Added __isset() and __unset(). |
Property overloading
$name
)$name
)__set() is run when writing data to inaccessible properties.
__get() is utilized for reading data from inaccessible properties.
__isset() is triggered by calling isset() or empty() on inaccessible properties.
__unset() is invoked when unset() is used on inaccessible properties.
The $name argument is the name of the property being interacted with. The __set() method's $value argument specifies the value the $name'ed property should be set to.
Property overloading only works in object context. These magic methods will not be triggered in static context. Therefore these methods should not be declared static. As of PHP 5.3.0, a warning is issued if one of the magic overloading methods is declared static.
Informacja:
The return value of __set() is ignored because of the way PHP processes the assignment operator. Similarly, __get() is never called when chaining assignments together like this:
$a = $obj->b = 8;
Informacja:
It is not possible to use overloaded properties in other language constructs than isset(). This means if empty() is called on an overloaded property, the overloaded method is not called.
To workaround that limitation, the overloaded property must be copied into a local variable in the scope and then be handed to empty().
Przykład #1 Overloading properties via the __get(), __set(), __isset() and __unset() methods
<?php
class PropertyTest
{
/** Location for overloaded data. */
private $data = array();
/** Overloading not used on declared properties. */
public $declared = 1;
/** Overloading only used on this when accessed outside the class. */
private $hidden = 2;
public function __set($name, $value)
{
echo "Setting '$name' to '$value'\n";
$this->data[$name] = $value;
}
public function __get($name)
{
echo "Getting '$name'\n";
if (array_key_exists($name, $this->data)) {
return $this->data[$name];
}
$trace = debug_backtrace();
trigger_error(
'Undefined property via __get(): ' . $name .
' in ' . $trace[0]['file'] .
' on line ' . $trace[0]['line'],
E_USER_NOTICE);
return null;
}
/** As of PHP 5.1.0 */
public function __isset($name)
{
echo "Is '$name' set?\n";
return isset($this->data[$name]);
}
/** As of PHP 5.1.0 */
public function __unset($name)
{
echo "Unsetting '$name'\n";
unset($this->data[$name]);
}
/** Not a magic method, just here for example. */
public function getHidden()
{
return $this->hidden;
}
}
echo "<pre>\n";
$obj = new PropertyTest;
$obj->a = 1;
echo $obj->a . "\n\n";
var_dump(isset($obj->a));
unset($obj->a);
var_dump(isset($obj->a));
echo "\n";
echo $obj->declared . "\n\n";
echo "Let's experiment with the private property named 'hidden':\n";
echo "Privates are visible inside the class, so __get() not used...\n";
echo $obj->getHidden() . "\n";
echo "Privates not visible outside of class, so __get() is used...\n";
echo $obj->hidden . "\n";
?>
Powyższy przykład wyświetli:
Setting 'a' to '1' Getting 'a' 1 Is 'a' set? bool(true) Unsetting 'a' Is 'a' set? bool(false) 1 Let's experiment with the private property named 'hidden': Privates are visible inside the class, so __get() not used... 2 Privates not visible outside of class, so __get() is used... Getting 'hidden' Notice: Undefined property via __get(): hidden in <file> on line 70 in <file> on line 29
Method overloading
__call() is triggered when invoking inaccessible methods in an object context.
__callStatic() is triggered when invoking inaccessible methods in a static context.
The $name argument is the name of the method being called. The $arguments argument is an enumerated array containing the parameters passed to the $name'ed method.
Przykład #2 Overloading methods via the __call() and __callStatic() methods
<?php
class MethodTest
{
public function __call($name, $arguments)
{
// Note: value of $name is case sensitive.
echo "Calling object method '$name' "
. implode(', ', $arguments). "\n";
}
/** As of PHP 5.3.0 */
public static function __callStatic($name, $arguments)
{
// Note: value of $name is case sensitive.
echo "Calling static method '$name' "
. implode(', ', $arguments). "\n";
}
}
$obj = new MethodTest;
$obj->runTest('in object context');
MethodTest::runTest('in static context'); // As of PHP 5.3.0
?>
Powyższy przykład wyświetli:
Calling object method 'runTest' in object context Calling static method 'runTest' in static context
Object Iteration
PHP 5 provides a way for objects to be defined so it is possible to iterate through a list of items, with, for example a foreach statement. By default, all visible properties will be used for the iteration.
Przykład #1 Simple Object Iteration
<?php
class MyClass
{
public $var1 = 'value 1';
public $var2 = 'value 2';
public $var3 = 'value 3';
protected $protected = 'protected var';
private $private = 'private var';
function iterateVisible() {
echo "MyClass::iterateVisible:\n";
foreach($this as $key => $value) {
print "$key => $value\n";
}
}
}
$class = new MyClass();
foreach($class as $key => $value) {
print "$key => $value\n";
}
echo "\n";
$class->iterateVisible();
?>
Powyższy przykład wyświetli:
var1 => value 1 var2 => value 2 var3 => value 3 MyClass::iterateVisible: var1 => value 1 var2 => value 2 var3 => value 3 protected => protected var private => private var
As the output shows, the foreach iterated through all visible variables that can be accessed. To take it a step further you can implement one of PHP 5's internal interface named Iterator. This allows the object to decide what and how the object will be iterated.
Przykład #2 Object Iteration implementing Iterator
<?php
class MyIterator implements Iterator
{
private $var = array();
public function __construct($array)
{
if (is_array($array)) {
$this->var = $array;
}
}
public function rewind()
{
echo "rewinding\n";
reset($this->var);
}
public function current()
{
$var = current($this->var);
echo "current: $var\n";
return $var;
}
public function key()
{
$var = key($this->var);
echo "key: $var\n";
return $var;
}
public function next()
{
$var = next($this->var);
echo "next: $var\n";
return $var;
}
public function valid()
{
$key = key($this->var);
$var = ($key !== NULL && $key !== FALSE);
echo "valid: $var\n";
return $var;
}
}
$values = array(1,2,3);
$it = new MyIterator($values);
foreach ($it as $a => $b) {
print "$a: $b\n";
}
?>
Powyższy przykład wyświetli:
rewinding valid: 1 current: 1 key: 0 0: 1 next: 2 valid: 1 current: 2 key: 1 1: 2 next: 3 valid: 1 current: 3 key: 2 2: 3 next: valid:
You can also define your class so that it doesn't have to define all the Iterator functions by simply implementing the PHP 5 IteratorAggregate interface.
Przykład #3 Object Iteration implementing IteratorAggregate
<?php
class MyCollection implements IteratorAggregate
{
private $items = array();
private $count = 0;
// Required definition of interface IteratorAggregate
public function getIterator() {
return new MyIterator($this->items);
}
public function add($value) {
$this->items[$this->count++] = $value;
}
}
$coll = new MyCollection();
$coll->add('value 1');
$coll->add('value 2');
$coll->add('value 3');
foreach ($coll as $key => $val) {
echo "key/value: [$key -> $val]\n\n";
}
?>
Powyższy przykład wyświetli:
rewinding current: value 1 valid: 1 current: value 1 key: 0 key/value: [0 -> value 1] next: value 2 current: value 2 valid: 1 current: value 2 key: 1 key/value: [1 -> value 2] next: value 3 current: value 3 valid: 1 current: value 3 key: 2 key/value: [2 -> value 3] next: current: valid:
Informacja:
For more examples of iterators, see the SPL Extension.
Patterns
Patterns are ways to describe best practices and good designs. They show a flexible solution to common programming problems.
Factory
The Factory pattern allows for the instantiation of objects at runtime. It is called a Factory Pattern since it is responsible for "manufacturing" an object. A Parameterized Factory receives the name of the class to instantiate as argument.
Przykład #1 Parameterized Factory Method
<?php
class Example
{
// The parameterized factory method
public static function factory($type)
{
if (include_once 'Drivers/' . $type . '.php') {
$classname = 'Driver_' . $type;
return new $classname;
} else {
throw new Exception('Driver not found');
}
}
}
?>
Defining this method in a class allows drivers to be loaded on the fly. If the Example class was a database abstraction class, loading a MySQL and SQLite driver could be done as follows:
<?php
// Load a MySQL Driver
$mysql = Example::factory('MySQL');
// Load an SQLite Driver
$sqlite = Example::factory('SQLite');
?>
Singleton
The Singleton ensures that there can be only one instance of a Class and provides a global access point to that instance. Singleton is a "Gang of Four" Creational Pattern.
The Singleton pattern is often implemented in Database Classes, Loggers, Front Controllers or Request and Response objects.
Przykład #2 Singleton example
<?php
class Example
{
private static $instance;
private $count = 0;
private function __construct()
{
}
public static function singleton()
{
if (!isset(self::$instance)) {
echo 'Creating new instance.';
$className = __CLASS__;
self::$instance = new $className;
}
return self::$instance;
}
public function increment()
{
return $this->count++;
}
public function __clone()
{
trigger_error('Clone is not allowed.', E_USER_ERROR);
}
public function __wakeup()
{
trigger_error('Unserializing is not allowed.', E_USER_ERROR);
}
}
?>
Illustrated below is how the Singleton behaves
<?php
$singleton = Example::singleton(); // prints "Creating new instance."
echo $singleton->increment(); // 0
echo $singleton->increment(); // 1
$singleton = Example::singleton(); // reuses existing instance now
echo $singleton->increment(); // 2
echo $singleton->increment(); // 3
// all of these will raise a Fatal Error
$singleton2 = new Example;
$singleton3 = clone $singleton;
$singleton4 = unserialize(serialize($singleton));
?>
The Singleton pattern is one of the more controversial patterns. Critics argue that Singletons introduce Global State into an application and tightly couple the Singleton and its consuming classes. This leads to hidden dependencies and unexpected side-effects, which in turn leads to code that is harder to test and maintain.
Critics further argue that it is pointless to use a Singleton in a Shared Nothing Architecture like PHP where objects are unique within the Request only anyways. It is easier and cleaner to create collaborator object graphs by using Builders and Factory patterns once at the beginning of the Request.
Singletons also violate several of the "SOLID" OOP design principles and the Law of Demeter. Singletons cannot be serialized. They cannot be subtyped (before PHP 5.3) and won't be Garbage Collected because of the instance being stored as a static attribute of the Singleton.
Magic Methods
The function names __construct(), __destruct(), __call(), __callStatic(), __get(), __set(), __isset(), __unset(), __sleep(), __wakeup(), __toString(), __invoke(), __set_state() and __clone() are magical in PHP classes. You cannot have functions with these names in any of your classes unless you want the magic functionality associated with them.
PHP reserves all function names starting with __ as magical. It is recommended that you do not use function names with __ in PHP unless you want some documented magic functionality.
__sleep() and __wakeup()
serialize() checks if your class has a function with
the magic name __sleep(). If so, that function is
executed prior to any serialization. It can clean up the object
and is supposed to return an array with the names of all variables
of that object that should be serialized.
If the method doesn't return anything then NULL is serialized and
E_NOTICE is issued.
Informacja:
It is not possible for __sleep() to return names of private properties in parent classes. Doing this will result in an
E_NOTICElevel error. Instead you may use the Serializable interface.
The intended use of __sleep() is to commit pending data or perform similar cleanup tasks. Also, the function is useful if you have very large objects which do not need to be saved completely.
Conversely, unserialize() checks for the presence of a function with the magic name __wakeup(). If present, this function can reconstruct any resources that the object may have.
The intended use of __wakeup() is to reestablish any database connections that may have been lost during serialization and perform other reinitialization tasks.
Przykład #1 Sleep and wakeup
<?php
class Connection
{
protected $link;
private $server, $username, $password, $db;
public function __construct($server, $username, $password, $db)
{
$this->server = $server;
$this->username = $username;
$this->password = $password;
$this->db = $db;
$this->connect();
}
private function connect()
{
$this->link = mysql_connect($this->server, $this->username, $this->password);
mysql_select_db($this->db, $this->link);
}
public function __sleep()
{
return array('server', 'username', 'password', 'db');
}
public function __wakeup()
{
$this->connect();
}
}
?>
__toString()
The __toString() method allows a class to decide
how it will react when it is treated like a string. For example,
what echo $obj; will print. This method must
return a string, as otherwise a fatal E_RECOVERABLE_ERROR
level error is emitted.
Przykład #2 Simple example
<?php
// Declare a simple class
class TestClass
{
public $foo;
public function __construct($foo)
{
$this->foo = $foo;
}
public function __toString()
{
return $this->foo;
}
}
$class = new TestClass('Hello');
echo $class;
?>
Powyższy przykład wyświetli:
Hello
It is worth noting that before PHP 5.2.0 the __toString()
method was only called when it was directly combined with
echo() or print().
Since PHP 5.2.0, it is called in any string context (e.g. in
printf() with %s modifier) but not
in other types contexts (e.g. with %d modifier).
Since PHP 5.2.0, converting objects without __toString()
method to string would cause E_RECOVERABLE_ERROR.
__invoke()
The __invoke() method is called when a script tries to call an object as a function.
Informacja:
This feature is available since PHP 5.3.0.
Przykład #3 Using __invoke()
<?php
class CallableClass
{
public function __invoke($x)
{
var_dump($x);
}
}
$obj = new CallableClass;
$obj(5);
var_dump(is_callable($obj));
?>
Powyższy przykład wyświetli:
int(5) bool(true)
__set_state()
$properties
)This static method is called for classes exported by var_export() since PHP 5.1.0.
The only parameter of this method is an array containing exported properties in the form array('property' => value, ...).
Przykład #4 Using __set_state() (since PHP 5.1.0)
<?php
class A
{
public $var1;
public $var2;
public static function __set_state($an_array) // As of PHP 5.1.0
{
$obj = new A;
$obj->var1 = $an_array['var1'];
$obj->var2 = $an_array['var2'];
return $obj;
}
}
$a = new A;
$a->var1 = 5;
$a->var2 = 'foo';
eval('$b = ' . var_export($a, true) . ';'); // $b = A::__set_state(array(
// 'var1' => 5,
// 'var2' => 'foo',
// ));
var_dump($b);
?>
Powyższy przykład wyświetli:
object(A)#2 (2) {
["var1"]=>
int(5)
["var2"]=>
string(3) "foo"
}
Final Keyword
PHP 5 introduces the final keyword, which prevents child classes from overriding a method by prefixing the definition with final. If the class itself is being defined final then it cannot be extended.
Przykład #1 Final methods example
<?php
class BaseClass {
public function test() {
echo "BaseClass::test() called\n";
}
final public function moreTesting() {
echo "BaseClass::moreTesting() called\n";
}
}
class ChildClass extends BaseClass {
public function moreTesting() {
echo "ChildClass::moreTesting() called\n";
}
}
// Results in Fatal error: Cannot override final method BaseClass::moreTesting()
?>
Przykład #2 Final class example
<?php
final class BaseClass {
public function test() {
echo "BaseClass::test() called\n";
}
// Here it doesn't matter if you specify the function as final or not
final public function moreTesting() {
echo "BaseClass::moreTesting() called\n";
}
}
class ChildClass extends BaseClass {
}
// Results in Fatal error: Class ChildClass may not inherit from final class (BaseClass)
?>
Informacja: Properties cannot be declared final, only classes and methods may be declared as final.
Object Cloning
Creating a copy of an object with fully replicated properties is not always the wanted behavior. A good example of the need for copy constructors, is if you have an object which represents a GTK window and the object holds the resource of this GTK window, when you create a duplicate you might want to create a new window with the same properties and have the new object hold the resource of the new window. Another example is if your object holds a reference to another object which it uses and when you replicate the parent object you want to create a new instance of this other object so that the replica has its own separate copy.
An object copy is created by using the clone keyword (which calls the object's __clone() method if possible). An object's __clone() method cannot be called directly.
$copy_of_object = clone $object;
When an object is cloned, PHP 5 will perform a shallow copy of all of the object's properties. Any properties that are references to other variables, will remain references.
Once the cloning is complete, if a __clone() method is defined, then the newly created object's __clone() method will be called, to allow any necessary properties that need to be changed.
Przykład #1 Cloning an object
<?php
class SubObject
{
static $instances = 0;
public $instance;
public function __construct() {
$this->instance = ++self::$instances;
}
public function __clone() {
$this->instance = ++self::$instances;
}
}
class MyCloneable
{
public $object1;
public $object2;
function __clone()
{
// Force a copy of this->object, otherwise
// it will point to same object.
$this->object1 = clone $this->object1;
}
}
$obj = new MyCloneable();
$obj->object1 = new SubObject();
$obj->object2 = new SubObject();
$obj2 = clone $obj;
print("Original Object:\n");
print_r($obj);
print("Cloned Object:\n");
print_r($obj2);
?>
Powyższy przykład wyświetli:
Original Object:
MyCloneable Object
(
[object1] => SubObject Object
(
[instance] => 1
)
[object2] => SubObject Object
(
[instance] => 2
)
)
Cloned Object:
MyCloneable Object
(
[object1] => SubObject Object
(
[instance] => 3
)
[object2] => SubObject Object
(
[instance] => 2
)
)
Comparing Objects
In PHP 5, object comparison is more complicated than in PHP 4 and more in accordance to what one will expect from an Object Oriented Language (not that PHP 5 is such a language).
When using the comparison operator (==), object variables are compared in a simple manner, namely: Two object instances are equal if they have the same attributes and values, and are instances of the same class.
On the other hand, when using the identity operator (===), object variables are identical if and only if they refer to the same instance of the same class.
An example will clarify these rules.
Przykład #1 Example of object comparison in PHP 5
<?php
function bool2str($bool)
{
if ($bool === false) {
return 'FALSE';
} else {
return 'TRUE';
}
}
function compareObjects(&$o1, &$o2)
{
echo 'o1 == o2 : ' . bool2str($o1 == $o2) . "\n";
echo 'o1 != o2 : ' . bool2str($o1 != $o2) . "\n";
echo 'o1 === o2 : ' . bool2str($o1 === $o2) . "\n";
echo 'o1 !== o2 : ' . bool2str($o1 !== $o2) . "\n";
}
class Flag
{
public $flag;
function Flag($flag = true) {
$this->flag = $flag;
}
}
class OtherFlag
{
public $flag;
function OtherFlag($flag = true) {
$this->flag = $flag;
}
}
$o = new Flag();
$p = new Flag();
$q = $o;
$r = new OtherFlag();
echo "Two instances of the same class\n";
compareObjects($o, $p);
echo "\nTwo references to the same instance\n";
compareObjects($o, $q);
echo "\nInstances of two different classes\n";
compareObjects($o, $r);
?>
Powyższy przykład wyświetli:
Two instances of the same class o1 == o2 : TRUE o1 != o2 : FALSE o1 === o2 : FALSE o1 !== o2 : TRUE Two references to the same instance o1 == o2 : TRUE o1 != o2 : FALSE o1 === o2 : TRUE o1 !== o2 : FALSE Instances of two different classes o1 == o2 : FALSE o1 != o2 : TRUE o1 === o2 : FALSE o1 !== o2 : TRUE
Informacja:
Extensions can define own rules for their objects comparison.
Type Hinting
PHP 5 introduces type hinting. Functions are now able to force parameters to be objects (by specifying the name of the class in the function prototype), interfaces, arrays (since PHP 5.1) or callable (since PHP 5.4). However, if NULL is used as the default parameter value, it will be allowed as an argument for any later call.
If class or interface is specified as type hint then all its children or implementations are allowed too.
Type hints can not be used with scalar types such as int or string. Traits are not allowed either.
Przykład #1 Type Hinting examples
<?php
// An example class
class MyClass
{
/**
* A test function
*
* First parameter must be an object of type OtherClass
*/
public function test(OtherClass $otherclass) {
echo $otherclass->var;
}
/**
* Another test function
*
* First parameter must be an array
*/
public function test_array(array $input_array) {
print_r($input_array);
}
/**
* First parameter must be iterator
*/
public function test_interface(Traversable $iterator) {
echo get_class($iterator);
}
/**
* First parameter must be callable
*/
public function test_callable(callable $callback, $data) {
call_user_func($callback, $data);
}
}
// Another example class
class OtherClass {
public $var = 'Hello World';
}
?>
Failing to satisfy the type hint results in a catchable fatal error.
<?php
// An instance of each class
$myclass = new MyClass;
$otherclass = new OtherClass;
// Fatal Error: Argument 1 must be an object of class OtherClass
$myclass->test('hello');
// Fatal Error: Argument 1 must be an instance of OtherClass
$foo = new stdClass;
$myclass->test($foo);
// Fatal Error: Argument 1 must not be null
$myclass->test(null);
// Works: Prints Hello World
$myclass->test($otherclass);
// Fatal Error: Argument 1 must be an array
$myclass->test_array('a string');
// Works: Prints the array
$myclass->test_array(array('a', 'b', 'c'));
// Works: Prints ArrayObject
$myclass->test_interface(new ArrayObject(array()));
// Works: Prints int(1)
$myclass->test_callable('var_dump', 1);
?>
Type hinting also works with functions:
<?php
// An example class
class MyClass {
public $var = 'Hello World';
}
/**
* A test function
*
* First parameter must be an object of type MyClass
*/
function myFunction(MyClass $foo) {
echo $foo->var;
}
// Works
$myclass = new MyClass;
myFunction($myclass);
?>
Type hinting allowing NULL value:
<?php
/* Accepting NULL value */
function test(stdClass $obj = NULL) {
}
test(NULL);
test(new stdClass);
?>
Late Static Bindings
As of PHP 5.3.0, PHP implements a feature called late static bindings which can be used to reference the called class in a context of static inheritance.
More precisely, late static bindings work by storing the class named in the last "non-forwarding call". In case of static method calls, this is the class explicitly named (usually the one on the left of the :: operator); in case of non static method calls, it is the class of the object. A "forwarding call" is a static one that is introduced by self::, parent::, static::, or, if going up in the class hierarchy, forward_static_call(). The function get_called_class() can be used to retrieve a string with the name of the called class and static:: introduces its scope.
This feature was named "late static bindings" with an internal perspective in mind. "Late binding" comes from the fact that static:: will not be resolved using the class where the method is defined but it will rather be computed using runtime information. It was also called a "static binding" as it can be used for (but is not limited to) static method calls.
Limitations of self::
Static references to the current class like self:: or __CLASS__ are resolved using the class in which the function belongs, as in where it was defined:
Przykład #1 self:: usage
<?php
class A {
public static function who() {
echo __CLASS__;
}
public static function test() {
self::who();
}
}
class B extends A {
public static function who() {
echo __CLASS__;
}
}
B::test();
?>
Powyższy przykład wyświetli:
A
Late Static Bindings' usage
Late static bindings tries to solve that limitation by introducing a keyword that references the class that was initially called at runtime. Basically, a keyword that would allow you to reference B from test() in the previous example. It was decided not to introduce a new keyword but rather use static that was already reserved.
Przykład #2 static:: simple usage
<?php
class A {
public static function who() {
echo __CLASS__;
}
public static function test() {
static::who(); // Here comes Late Static Bindings
}
}
class B extends A {
public static function who() {
echo __CLASS__;
}
}
B::test();
?>
Powyższy przykład wyświetli:
B
Informacja:
In non-static contexts, the called class will be the class of the object instance. Since $this-> will try to call private methods from the same scope, using static:: may give different results. Another difference is that static:: can only refer to static properties.
Przykład #3 static:: usage in a non-static context
<?php
class A {
private function foo() {
echo "success!\n";
}
public function test() {
$this->foo();
static::foo();
}
}
class B extends A {
/* foo() will be copied to B, hence its scope will still be A and
* the call be successful */
}
class C extends A {
private function foo() {
/* original method is replaced; the scope of the new one is C */
}
}
$b = new B();
$b->test();
$c = new C();
$c->test(); //fails
?>
Powyższy przykład wyświetli:
success! success! success! Fatal error: Call to private method C::foo() from context 'A' in /tmp/test.php on line 9
Informacja:
Late static bindings' resolution will stop at a fully resolved static call with no fallback. On the other hand, static calls using keywords like parent:: or self:: will forward the calling information.
Przykład #4 Forwarding and non-forwarding calls
<?php
class A {
public static function foo() {
static::who();
}
public static function who() {
echo __CLASS__."\n";
}
}
class B extends A {
public static function test() {
A::foo();
parent::foo();
self::foo();
}
public static function who() {
echo __CLASS__."\n";
}
}
class C extends B {
public static function who() {
echo __CLASS__."\n";
}
}
C::test();
?>Powyższy przykład wyświetli:
A C C
Objects and references
One of the key-points of PHP 5 OOP that is often mentioned is that "objects are passed by references by default". This is not completely true. This section rectifies that general thought using some examples.
A PHP reference is an alias, which allows two different variables to write to the same value. As of PHP 5, an object variable doesn't contain the object itself as value anymore. It only contains an object identifier which allows object accessors to find the actual object. When an object is sent by argument, returned or assigned to another variable, the different variables are not aliases: they hold a copy of the identifier, which points to the same object.
Przykład #1 References and Objects
<?php
class A {
public $foo = 1;
}
$a = new A;
$b = $a; // $a and $b are copies of the same identifier
// ($a) = ($b) = <id>
$b->foo = 2;
echo $a->foo."\n";
$c = new A;
$d = &$c; // $c and $d are references
// ($c,$d) = <id>
$d->foo = 2;
echo $c->foo."\n";
$e = new A;
function foo($obj) {
// ($obj) = ($e) = <id>
$obj->foo = 2;
}
foo($e);
echo $e->foo."\n";
?>
Powyższy przykład wyświetli:
2 2 2
Object Serialization
Serializing objects - objects in sessions
serialize() returns a string containing a byte-stream representation of any value that can be stored in PHP. unserialize() can use this string to recreate the original variable values. Using serialize to save an object will save all variables in an object. The methods in an object will not be saved, only the name of the class.
In order to be able to unserialize() an object, the class of that object needs to be defined. That is, if you have an object of class A and serialize this, you'll get a string that refers to class A and contains all values of variables contained in it. If you want to be able to unserialize this in another file, an object of class A, the definition of class A must be present in that file first. This can be done for example by storing the class definition of class A in an include file and including this file or making use of the spl_autoload_register() function.
<?php
// classa.inc:
class A {
public $one = 1;
public function show_one() {
echo $this->one;
}
}
// page1.php:
include("classa.inc");
$a = new A;
$s = serialize($a);
// store $s somewhere where page2.php can find it.
file_put_contents('store', $s);
// page2.php:
// this is needed for the unserialize to work properly.
include("classa.inc");
$s = file_get_contents('store');
$a = unserialize($s);
// now use the function show_one() of the $a object.
$a->show_one();
?>
If an application is using sessions and uses session_register() to register objects, these objects are serialized automatically at the end of each PHP page, and are unserialized automatically on each of the following pages. This means that these objects can show up on any of the application's pages once they become part of the session. However, the session_register() is removed since PHP 5.4.0.
It is strongly recommended that if an application serializes objects, for use later in the application, that the application includes the class definition for that object throughout the application. Not doing so might result in an object being unserialized without a class definition, which will result in PHP giving the object a class of __PHP_Incomplete_Class_Name, which has no methods and would render the object useless.
So if in the example above $a became part of a session by running session_register("a"), you should include the file classa.inc on all of your pages, not only page1.php and page2.php.
OOP Changelog
Changes to the PHP 5 OOP model are logged here. Descriptions and other notes regarding these features are documented within the OOP 5 documentation.
| Wersja | Opis |
|---|---|
| 5.4.0 | Changed: If an abstract class defines a signature for the constructor it will now be enforced. |
| 5.3.3 | Changed: Methods with the same name as the last element of a namespaced class name will no longer be treated as constructor. This change doesn't affect non-namespaced classes. |
| 5.3.0 | Changed: Classes that implement interfaces with methods that have default values in the prototype are no longer required to match the interface's default value. |
| 5.3.0 | Changed: It's now possible to reference the class using a variable (e.g., echo $classname::constant;). The variable's value can not be a keyword (e.g., self, parent or static). |
| 5.3.0 |
Changed: An E_WARNING level error is issued if
the magic overloading
methods are declared static.
It also enforces the public visibility requirement.
|
| 5.3.0 | Changed: Prior to 5.3.0, exceptions thrown in the __autoload() function could not be caught in the catch block, and would result in a fatal error. Exceptions now thrown in the __autoload function can be caught in the catch block, with one proviso. If throwing a custom exception, then the custom exception class must be available. The __autoload function may be used recursively to autoload the custom exception class. |
| 5.3.0 | Added: The __callStatic method. |
| 5.3.0 | Added: heredoc and nowdoc support for class const and property definitions. Note: heredoc values must follow the same rules as double-quoted strings, (e.g., no variables within). |
| 5.3.0 | Added: Late Static Bindings. |
| 5.3.0 | Added: The __invoke() method. |
| 5.2.0 |
Changed: The __toString()
method was only called when it was directly combined with
echo() or print().
But now, it is called in any string context (e.g. in
printf() with %s modifier) but not
in other types contexts (e.g. with %d modifier).
Since PHP 5.2.0, converting objects without a __toString
method to string emits a E_RECOVERABLE_ERROR level error.
|
| 5.1.3 |
Changed: In previous versions of PHP 5, the use of var
was considered deprecated and would issue an E_STRICT
level error. It's no longer deprecated, therefore does not emit the error.
|
| 5.1.0 | Changed: The __set_state() static method is now called for classes exported by var_export(). |
| 5.1.0 | Added: The __isset() and __unset() methods. |
Namespaces
Spis treści
- Namespaces overview
- Defining namespaces
- Declaring sub-namespaces
- Defining multiple namespaces in the same file
- Using namespaces: Basics
- Namespaces and dynamic language features
- namespace keyword and __NAMESPACE__ constant
- Using namespaces: Aliasing/Importing
- Global space
- Using namespaces: fallback to global function/constant
- Name resolution rules
- FAQ: things you need to know about namespaces
Namespaces overview
(PHP 5 >= 5.3.0)
What are namespaces? In the broadest definition namespaces are a way of encapsulating items. This can be seen as an abstract concept in many places. For example, in any operating system directories serve to group related files, and act as a namespace for the files within them. As a concrete example, the file foo.txt can exist in both directory /home/greg and in /home/other, but two copies of foo.txt cannot co-exist in the same directory. In addition, to access the foo.txt file outside of the /home/greg directory, we must prepend the directory name to the file name using the directory separator to get /home/greg/foo.txt. This same principle extends to namespaces in the programming world.
In the PHP world, namespaces are designed to solve two problems that authors of libraries and applications encounter when creating re-usable code elements such as classes or functions:
- Name collisions between code you create, and internal PHP classes/functions/constants or third-party classes/functions/constants.
- Ability to alias (or shorten) Extra_Long_Names designed to alleviate the first problem, improving readability of source code.
PHP Namespaces provide a way in which to group related classes, interfaces, functions and constants. Here is an example of namespace syntax in PHP:
Przykład #1 Namespace syntax example
<?php
namespace my\name; // see "Defining Namespaces" section
class MyClass {}
function myfunction() {}
const MYCONST = 1;
$a = new MyClass;
$c = new \my\name\MyClass; // see "Global Space" section
$a = strlen('hi'); // see "Using namespaces: fallback to global
// function/constant" section
$d = namespace\MYCONST; // see "namespace operator and __NAMESPACE__
// constant" section
$d = __NAMESPACE__ . '\MYCONST';
echo constant($d); // see "Namespaces and dynamic language features" section
?>
Informacja:
Namespace names PHP and php, and compound names starting with these names (like PHP\Classes) are reserved for internal language use and should not be used in the userspace code.
Defining namespaces
(PHP 5 >= 5.3.0)
Although any valid PHP code can be contained within a namespace, only four types of code are affected by namespaces: classes, interfaces, functions and constants.
Namespaces are declared using the namespace keyword. A file containing a namespace must declare the namespace at the top of the file before any other code - with one exception: the declare keyword.
Przykład #1 Declaring a single namespace
<?php
namespace MyProject;
const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */ }
?>
Przykład #2 Declaring a single namespace
<html>
<?php
namespace MyProject; // fatal error - namespace must be the first statement in the script
?>
In addition, unlike any other PHP construct, the same namespace may be defined in multiple files, allowing splitting up of a namespace's contents across the filesystem.
Declaring sub-namespaces
(PHP 5 >= 5.3.0)
Much like directories and files, PHP namespaces also contain the ability to specify a hierarchy of namespace names. Thus, a namespace name can be defined with sub-levels:
Przykład #1 Declaring a single namespace with hierarchy
<?php
namespace MyProject\Sub\Level;
const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */ }
?>
Defining multiple namespaces in the same file
(PHP 5 >= 5.3.0)
Multiple namespaces may also be declared in the same file. There are two allowed syntaxes.
Przykład #1 Declaring multiple namespaces, simple combination syntax
<?php
namespace MyProject;
const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */ }
namespace AnotherProject;
const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */ }
?>
This syntax is not recommended for combining namespaces into a single file. Instead it is recommended to use the alternate bracketed syntax.
Przykład #2 Declaring multiple namespaces, bracketed syntax
<?php
namespace MyProject {
const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */ }
}
namespace AnotherProject {
const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */ }
}
?>
It is strongly discouraged as a coding practice to combine multiple namespaces into the same file. The primary use case is to combine multiple PHP scripts into the same file.
To combine global non-namespaced code with namespaced code, only bracketed syntax is supported. Global code should be encased in a namespace statement with no namespace name as in:
Przykład #3 Declaring multiple namespaces and unnamespaced code
<?php
namespace MyProject {
const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */ }
}
namespace { // global code
session_start();
$a = MyProject\connect();
echo MyProject\Connection::start();
}
?>
No PHP code may exist outside of the namespace brackets except for an opening declare statement.
Przykład #4 Declaring multiple namespaces and unnamespaced code
<?php
declare(encoding='UTF-8');
namespace MyProject {
const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */ }
}
namespace { // global code
session_start();
$a = MyProject\connect();
echo MyProject\Connection::start();
}
?>
Using namespaces: Basics
(PHP 5 >= 5.3.0)
Before discussing the use of namespaces, it is important to understand how PHP knows which namespaced element your code is requesting. A simple analogy can be made between PHP namespaces and a filesystem. There are three ways to access a file in a file system:
- Relative file name like foo.txt. This resolves to currentdirectory/foo.txt where currentdirectory is the directory currently occupied. So if the current directory is /home/foo, the name resolves to /home/foo/foo.txt.
- Relative path name like subdirectory/foo.txt. This resolves to currentdirectory/subdirectory/foo.txt.
- Absolute path name like /main/foo.txt. This resolves to /main/foo.txt.
- Unqualified name, or an unprefixed class name like $a = new foo(); or foo::staticmethod();. If the current namespace is currentnamespace, this resolves to currentnamespace\foo. If the code is global, non-namespaced code, this resolves to foo. One caveat: unqualified names for functions and constants will resolve to global functions and constants if the namespaced function or constant is not defined. See Using namespaces: fallback to global function/constant for details.
- Qualified name, or a prefixed class name like $a = new subnamespace\foo(); or subnamespace\foo::staticmethod();. If the current namespace is currentnamespace, this resolves to currentnamespace\subnamespace\foo. If the code is global, non-namespaced code, this resolves to subnamespace\foo.
- Fully qualified name, or a prefixed name with global prefix operator like $a = new \currentnamespace\foo(); or \currentnamespace\foo::staticmethod();. This always resolves to the literal name specified in the code, currentnamespace\foo.
Here is an example of the three kinds of syntax in actual code:
file1.php
<?php
namespace Foo\Bar\subnamespace;
const FOO = 1;
function foo() {}
class foo
{
static function staticmethod() {}
}
?>
file2.php
<?php
namespace Foo\Bar;
include 'file1.php';
const FOO = 2;
function foo() {}
class foo
{
static function staticmethod() {}
}
/* Unqualified name */
foo(); // resolves to function Foo\Bar\foo
foo::staticmethod(); // resolves to class Foo\Bar\foo, method staticmethod
echo FOO; // resolves to constant Foo\Bar\FOO
/* Qualified name */
subnamespace\foo(); // resolves to function Foo\Bar\subnamespace\foo
subnamespace\foo::staticmethod(); // resolves to class Foo\Bar\subnamespace\foo,
// method staticmethod
echo subnamespace\FOO; // resolves to constant Foo\Bar\subnamespace\FOO
/* Fully qualified name */
\Foo\Bar\foo(); // resolves to function Foo\Bar\foo
\Foo\Bar\foo::staticmethod(); // resolves to class Foo\Bar\foo, method staticmethod
echo \Foo\Bar\FOO; // resolves to constant Foo\Bar\FOO
?>
Note that to access any global class, function or constant, a fully qualified name can be used, such as \strlen() or \Exception or \INI_ALL.
Przykład #1 Accessing global classes, functions and constants from within a namespace
<?php
namespace Foo;
function strlen() {}
const INI_ALL = 3;
class Exception {}
$a = \strlen('hi'); // calls global function strlen
$b = \INI_ALL; // accesses global constant INI_ALL
$c = new \Exception('error'); // instantiates global class Exception
?>
Namespaces and dynamic language features
(PHP 5 >= 5.3.0)
PHP's implementation of namespaces is influenced by its dynamic nature as a programming language. Thus, to convert code like the following example into namespaced code:
Przykład #1 Dynamically accessing elements
example1.php:
<?php
class classname
{
function __construct()
{
echo __METHOD__,"\n";
}
}
function funcname()
{
echo __FUNCTION__,"\n";
}
const constname = "global";
$a = 'classname';
$obj = new $a; // prints classname::__construct
$b = 'funcname';
$b(); // prints funcname
echo constant('constname'), "\n"; // prints global
?>
Przykład #2 Dynamically accessing namespaced elements
<?php
namespace namespacename;
class classname
{
function __construct()
{
echo __METHOD__,"\n";
}
}
function funcname()
{
echo __FUNCTION__,"\n";
}
const constname = "namespaced";
include 'example1.php';
$a = 'classname';
$obj = new $a; // prints classname::__construct
$b = 'funcname';
$b(); // prints funcname
echo constant('constname'), "\n"; // prints global
/* note that if using double quotes, "\\namespacename\\classname" must be used */
$a = '\namespacename\classname';
$obj = new $a; // prints namespacename\classname::__construct
$a = 'namespacename\classname';
$obj = new $a; // also prints namespacename\classname::__construct
$b = 'namespacename\funcname';
$b(); // prints namespacename\funcname
$b = '\namespacename\funcname';
$b(); // also prints namespacename\funcname
echo constant('\namespacename\constname'), "\n"; // prints namespaced
echo constant('namespacename\constname'), "\n"; // also prints namespaced
?>
Be sure to read the note about escaping namespace names in strings.
namespace keyword and __NAMESPACE__ constant
(PHP 5 >= 5.3.0)
PHP supports two ways of abstractly accessing elements within the current namespace,
the __NAMESPACE__ magic constant, and the namespace
keyword.
The value of __NAMESPACE__ is a string that contains the current
namespace name. In global, un-namespaced code, it contains an empty string.
Przykład #1 __NAMESPACE__ example, namespaced code
<?php
namespace MyProject;
echo '"', __NAMESPACE__, '"'; // outputs "MyProject"
?>
Przykład #2 __NAMESPACE__ example, global code
<?php
echo '"', __NAMESPACE__, '"'; // outputs ""
?>
__NAMESPACE__ constant is useful for dynamically constructing
names, for instance:
Przykład #3 using __NAMESPACE__ for dynamic name construction
<?php
namespace MyProject;
function get($classname)
{
$a = __NAMESPACE__ . '\\' . $classname;
return new $a;
}
?>
The namespace keyword can be used to explicitly request an element from the current namespace or a sub-namespace. It is the namespace equivalent of the self operator for classes.
Przykład #4 the namespace operator, inside a namespace
<?php
namespace MyProject;
use blah\blah as mine; // see "Using namespaces: importing/aliasing"
blah\mine(); // calls function MyProject\blah\mine()
namespace\blah\mine(); // calls function MyProject\blah\mine()
namespace\func(); // calls function MyProject\func()
namespace\sub\func(); // calls function MyProject\sub\func()
namespace\cname::method(); // calls static method "method" of class MyProject\cname
$a = new namespace\sub\cname(); // instantiates object of class MyProject\sub\cname
$b = namespace\CONSTANT; // assigns value of constant MyProject\CONSTANT to $b
?>
Przykład #5 the namespace operator, in global code
<?php
namespace\func(); // calls function func()
namespace\sub\func(); // calls function sub\func()
namespace\cname::method(); // calls static method "method" of class cname
$a = new namespace\sub\cname(); // instantiates object of class sub\cname
$b = namespace\CONSTANT; // assigns value of constant CONSTANT to $b
?>
Using namespaces: Aliasing/Importing
(PHP 5 >= 5.3.0)
The ability to refer to an external fully qualified name with an alias, or importing, is an important feature of namespaces. This is similar to the ability of unix-based filesystems to create symbolic links to a file or to a directory.
PHP namespaces support three kinds of aliasing or importing: aliasing a class name, aliasing an interface name, and aliasing a namespace name. Note that importing a function or constant is not supported.
In PHP, aliasing is accomplished with the use operator. Here is an example showing all 3 kinds of importing:
Przykład #1 importing/aliasing with the use operator
<?php
namespace foo;
use My\Full\Classname as Another;
// this is the same as use My\Full\NSname as NSname
use My\Full\NSname;
// importing a global class
use ArrayObject;
$obj = new namespace\Another; // instantiates object of class foo\Another
$obj = new Another; // instantiates object of class My\Full\Classname
NSname\subns\func(); // calls function My\Full\NSname\subns\func
$a = new ArrayObject(array(1)); // instantiates object of class ArrayObject
// without the "use ArrayObject" we would instantiate an object of class foo\ArrayObject
?>
PHP additionally supports a convenience shortcut to place multiple use statements on the same line
Przykład #2 importing/aliasing with the use operator, multiple use statements combined
<?php
use My\Full\Classname as Another, My\Full\NSname;
$obj = new Another; // instantiates object of class My\Full\Classname
NSname\subns\func(); // calls function My\Full\NSname\subns\func
?>
Importing is performed at compile-time, and so does not affect dynamic class, function or constant names.
Przykład #3 Importing and dynamic names
<?php
use My\Full\Classname as Another, My\Full\NSname;
$obj = new Another; // instantiates object of class My\Full\Classname
$a = 'Another';
$obj = new $a; // instantiates object of class Another
?>
In addition, importing only affects unqualified and qualified names. Fully qualified names are absolute, and unaffected by imports.
Przykład #4 Importing and fully qualified names
<?php
use My\Full\Classname as Another, My\Full\NSname;
$obj = new Another; // instantiates object of class My\Full\Classname
$obj = new \Another; // instantiates object of class Another
$obj = new Another\thing; // instantiates object of class My\Full\Classname\thing
$obj = new \Another\thing; // instantiates object of class Another\thing
?>
Scoping rules for importing
The use keyword must be declared in the outermost scope of a file (the global scope) or inside namespace declarations. This is because the importing is done at compile time and not runtime, so it cannot be block scoped. The following example will show an illegal use of the use keyword:
Przykład #5 Illegal importing rule
<?php
namespace Languages;
class Greenlandic
{
use Languages\Danish;
...
}
?>
Informacja:
Importing rules are per file basis, meaning included files will NOT inherit the parent file's importing rules.
Global space
(PHP 5 >= 5.3.0)
Without any namespace definition, all class and function definitions are placed into the global space - as it was in PHP before namespaces were supported. Prefixing a name with \ will specify that the name is required from the global space even in the context of the namespace.
Przykład #1 Using global space specification
<?php
namespace A\B\C;
/* This function is A\B\C\fopen */
function fopen() {
/* ... */
$f = \fopen(...); // call global fopen
return $f;
}
?>
Using namespaces: fallback to global function/constant
(PHP 5 >= 5.3.0)
Inside a namespace, when PHP encounters a unqualified Name in a class name, function or constant context, it resolves these with different priorities. Class names always resolve to the current namespace name. Thus to access internal or non-namespaced user classes, One must refer to them with their fully qualified Name as in:
Przykład #1 Accessing global classes inside a namespace
<?php
namespace A\B\C;
class Exception extends \Exception {}
$a = new Exception('hi'); // $a is an object of class A\B\C\Exception
$b = new \Exception('hi'); // $b is an object of class Exception
$c = new ArrayObject; // fatal error, class A\B\C\ArrayObject not found
?>
For functions and constants, PHP will fall back to global functions or constants if a namespaced function or constant does not exist.
Przykład #2 global functions/constants fallback inside a namespace
<?php
namespace A\B\C;
const E_ERROR = 45;
function strlen($str)
{
return \strlen($str) - 1;
}
echo E_ERROR, "\n"; // prints "45"
echo INI_ALL, "\n"; // prints "7" - falls back to global INI_ALL
echo strlen('hi'), "\n"; // prints "2"
if (is_array('hi')) { // prints "is not array"
echo "is array\n";
} else {
echo "is not array\n";
}
?>
Name resolution rules
(PHP 5 >= 5.3.0)
For the purposes of these resolution rules, here are some important definitions:
-
Namespace name definitions
- Unqualified name
-
This is an identifier without a namespace separator, such as Foo
- Qualified name
-
This is an identifier with a namespace separator, such as Foo\Bar
- Fully qualified name
-
This is an identifier with a namespace separator that begins with a namespace separator, such as \Foo\Bar. namespace\Foo is also a fully qualified name.
Names are resolved following these resolution rules:
- Calls to fully qualified functions, classes or constants are resolved at compile-time. For instance new \A\B resolves to class A\B.
- All unqualified and qualified names (not fully qualified names) are translated during compilation according to current import rules. For example, if the namespace A\B\C is imported as C, a call to C\D\e() is translated to A\B\C\D\e().
- Inside a namespace, all qualified names not translated according to import rules have the current namespace prepended. For example, if a call to C\D\e() is performed within namespace A\B, it is translated to A\B\C\D\e().
- Unqualified class names are translated during compilation according to current import rules (full name substituted for short imported name). In example, if the namespace A\B\C is imported as C, new C() is translated to new A\B\C().
-
Inside namespace (say A\B), calls to unqualified functions are resolved at run-time.
Here is how a
call to function foo() is resolved:
- It looks for a function from the current namespace: A\B\foo().
- It tries to find and call the global function foo().
-
Inside namespace (say A\B), calls to unqualified or qualified
class names (not fully qualified class names)
are resolved at run-time. Here is how a call to
new C() or new D\E() is resolved.
For new C():
- It looks for a class from the current namespace: A\B\C.
- It attempts to autoload A\B\C.
- It looks for a class by prepending the current namespace: A\B\D\E.
- It attempts to autoload A\B\D\E.
Przykład #1 Name resolutions illustrated
<?php
namespace A;
use B\D, C\E as F;
// function calls
foo(); // first tries to call "foo" defined in namespace "A"
// then calls global function "foo"
\foo(); // calls function "foo" defined in global scope
my\foo(); // calls function "foo" defined in namespace "A\my"
F(); // first tries to call "F" defined in namespace "A"
// then calls global function "F"
// class references
new B(); // creates object of class "B" defined in namespace "A"
// if not found, it tries to autoload class "A\B"
new D(); // using import rules, creates object of class "D" defined in namespace "B"
// if not found, it tries to autoload class "B\D"
new F(); // using import rules, creates object of class "E" defined in namespace "C"
// if not found, it tries to autoload class "C\E"
new \B(); // creates object of class "B" defined in global scope
// if not found, it tries to autoload class "B"
new \D(); // creates object of class "D" defined in global scope
// if not found, it tries to autoload class "D"
new \F(); // creates object of class "F" defined in global scope
// if not found, it tries to autoload class "F"
// static methods/namespace functions from another namespace
B\foo(); // calls function "foo" from namespace "A\B"
B::foo(); // calls method "foo" of class "B" defined in namespace "A"
// if class "A\B" not found, it tries to autoload class "A\B"
D::foo(); // using import rules, calls method "foo" of class "D" defined in namespace "B"
// if class "B\D" not found, it tries to autoload class "B\D"
\B\foo(); // calls function "foo" from namespace "B"
\B::foo(); // calls method "foo" of class "B" from global scope
// if class "B" not found, it tries to autoload class "B"
// static methods/namespace functions of current namespace
A\B::foo(); // calls method "foo" of class "B" from namespace "A\A"
// if class "A\A\B" not found, it tries to autoload class "A\A\B"
\A\B::foo(); // calls method "foo" of class "B" from namespace "A"
// if class "A\B" not found, it tries to autoload class "A\B"
?>
FAQ: things you need to know about namespaces
(PHP 5 >= 5.3.0)
This FAQ is split into two sections: common questions, and some specifics of implementation that are helpful to understand fully.
First, the common questions.
- If I don't use namespaces, should I care about any of this?
- How do I use internal or global classes in a namespace?
- How do I use namespaces classes functions, or constants in their own namespace?
- How does a name like \my\name or \name resolve?
- How does a name like my\name resolve?
- How does an unqualified class name like name resolve?
- How does an unqualified function name or unqualified constant name like name resolve?
There are a few implementation details of the namespace implementations that are helpful to understand.
- Import names cannot conflict with classes defined in the same file.
- Nested namespaces are not allowed.
- Neither functions nor constants can be imported via the use statement.
- Dynamic namespace names (quoted identifiers) should escape backslash.
- Undefined Constants referenced using any backslash die with fatal error
- Cannot override special constants NULL, TRUE, FALSE, ZEND_THREAD_SAFE or ZEND_DEBUG_BUILD
If I don't use namespaces, should I care about any of this?
No. Namespaces do not affect any existing code in any way, or any as-yet-to-be-written code that does not contain namespaces. You can write this code if you wish:
Przykład #1 Accessing global classes outside a namespace
<?php
$a = new \stdClass;
?>
This is functionally equivalent to:
Przykład #2 Accessing global classes outside a namespace
<?php
$a = new stdClass;
?>
How do I use internal or global classes in a namespace?
Przykład #3 Accessing internal classes in namespaces
<?php
namespace foo;
$a = new \stdClass;
function test(\ArrayObject $typehintexample = null) {}
$a = \DirectoryIterator::CURRENT_AS_FILEINFO;
// extending an internal or global class
class MyException extends \Exception {}
?>
How do I use namespaces classes, functions, or constants in their own namespace?
Przykład #4 Accessing internal classes, functions or constants in namespaces
<?php
namespace foo;
class MyClass {}
// using a class from the current namespace as a type hint
function test(MyClass $typehintexample = null) {}
// another way to use a class from the current namespace as a type hint
function test(\foo\MyClass $typehintexample = null) {}
// extending a class from the current namespace
class Extended extends MyClass {}
// accessing a global function
$a = \globalfunc();
// accessing a global constant
$b = \INI_ALL;
?>
How does a name like \my\name or \name resolve?
Names that begin with a \ always resolve to what they look like, so \my\name is in fact my\name, and \Exception is Exception.
Przykład #5 Fully Qualified names
<?php
namespace foo;
$a = new \my\name(); // instantiates "my\name" class
echo \strlen('hi'); // calls function "strlen"
$a = \INI_ALL; // $a is set to the value of constant "INI_ALL"
?>
How does a name like my\name resolve?
Names that contain a backslash but do not begin with a backslash like my\name can be resolved in 2 different ways.
If there is an import statement that aliases another name to my, then the import alias is applied to the my in my\name.
Otherwise, the current namespace name is prepended to my\name.
Przykład #6 Qualified names
<?php
namespace foo;
use blah\blah as foo;
$a = new my\name(); // instantiates "foo\my\name" class
foo\bar::name(); // calls static method "name" in class "blah\blah\bar"
my\bar(); // calls function "foo\my\bar"
$a = my\BAR; // sets $a to the value of constant "foo\my\BAR"
?>
How does an unqualified class name like name resolve?
Class names that do not contain a backslash like name can be resolved in 2 different ways.
If there is an import statement that aliases another name to name, then the import alias is applied.
Otherwise, the current namespace name is prepended to name.
Przykład #7 Unqualified class names
<?php
namespace foo;
use blah\blah as foo;
$a = new name(); // instantiates "foo\name" class
foo::name(); // calls static method "name" in class "blah\blah"
?>
How does an unqualified function name or unqualified constant name like name resolve?
Function or constant names that do not contain a backslash like name can be resolved in 2 different ways.
First, the current namespace name is prepended to name.
Finally, if the constant or function name does not exist in the current namespace, a global constant or function name is used if it exists.
Przykład #8 Unqualified function or constant names
<?php
namespace foo;
use blah\blah as foo;
const FOO = 1;
function my() {}
function foo() {}
function sort(&$a)
{
sort($a);
$a = array_flip($a);
return $a;
}
my(); // calls "foo\my"
$a = strlen('hi'); // calls global function "strlen" because "foo\strlen" does not exist
$arr = array(1,3,2);
$b = sort($arr); // calls function "foo\sort"
$c = foo(); // calls function "foo\foo" - import is not applied
$a = FOO; // sets $a to value of constant "foo\FOO" - import is not applied
$b = INI_ALL; // sets $b to value of global constant "INI_ALL"
?>
Import names cannot conflict with classes defined in the same file.
The following script combinations are legal:
file1.php
<?php
namespace my\stuff;
class MyClass {}
?>
another.php
<?php
namespace another;
class thing {}
?>
file2.php
<?php
namespace my\stuff;
include 'file1.php';
include 'another.php';
use another\thing as MyClass;
$a = new MyClass; // instantiates class "thing" from namespace another
?>
There is no name conflict, even though the class MyClass exists within the my\stuff namespace, because the MyClass definition is in a separate file. However, the next example causes a fatal error on name conflict because MyClass is defined in the same file as the use statement.
<?php
namespace my\stuff;
use another\thing as MyClass;
class MyClass {} // fatal error: MyClass conflicts with import statement
$a = new MyClass;
?>
Nested namespaces are not allowed.
PHP does not allow nesting namespaces
<?php
namespace my\stuff {
namespace nested {
class foo {}
}
}
?>
<?php
namespace my\stuff\nested {
class foo {}
}
?>
Neither functions nor constants can be imported via the use statement.
The only elements that are affected by use statements are namespaces and class names. In order to shorten a long constant or function, import its containing namespace
<?php
namespace mine;
use ultra\long\ns\name;
$a = name\CONSTANT;
name\func();
?>
Dynamic namespace names (quoted identifiers) should escape backslash
It is very important to realize that because the backslash is used as an escape character within strings, it should always be doubled when used inside a string. Otherwise there is a risk of unintended consequences:
Przykład #9 Dangers of using namespaced names inside a double-quoted string
<?php
$a = new "dangerous\name"; // \n is a newline inside double quoted strings!
$obj = new $a;
$a = new 'not\at\all\dangerous'; // no problems here.
$obj = new $a;
?>
Undefined Constants referenced using any backslash die with fatal error
Any undefined constant that is unqualified like FOO will produce a notice explaining that PHP assumed FOO was the value of the constant. Any constant, qualified or fully qualified, that contains a backslash will produce a fatal error if not found.
Przykład #10 Undefined constants
<?php
namespace bar;
$a = FOO; // produces notice - undefined constants "FOO" assumed "FOO";
$a = \FOO; // fatal error, undefined namespace constant FOO
$a = Bar\FOO; // fatal error, undefined namespace constant bar\Bar\FOO
$a = \Bar\FOO; // fatal error, undefined namespace constant Bar\FOO
?>
Cannot override special constants NULL, TRUE, FALSE, ZEND_THREAD_SAFE or ZEND_DEBUG_BUILD
Any attempt to define a namespaced constant that is a special, built-in constant results in a fatal error
Przykład #11 Undefined constants
<?php
namespace bar;
const NULL = 0; // fatal error;
const true = 'stupid'; // also fatal error;
// etc.
?>
Exceptions
Spis treści
PHP 5 has an exception model similar to that of other programming languages. An exception can be thrown, and caught ("catched") within PHP. Code may be surrounded in a try block, to facilitate the catching of potential exceptions. Each try must have at least one corresponding catch block. Multiple catch blocks can be used to catch different classes of exceptions. Normal execution (when no exception is thrown within the try block, or when a catch matching the thrown exception's class is not present) will continue after that last catch block defined in sequence. Exceptions can be thrown (or re-thrown) within a catch block.
When an exception is thrown, code following the statement will not be executed, and PHP will attempt to find the first matching catch block. If an exception is not caught, a PHP Fatal Error will be issued with an "Uncaught Exception ..." message, unless a handler has been defined with set_exception_handler().
The thrown object must be an instance of the Exception class or a subclass of Exception. Trying to throw an object that is not will result in a PHP Fatal Error.
Informacja:
Internal PHP functions mainly use Error reporting, only modern Object oriented extensions use exceptions. However, errors can be simply translated to exceptions with ErrorException.
The Standard PHP Library (SPL) provides a good number of built-in exceptions.
Przykład #1 Throwing an Exception
<?php
function inverse($x) {
if (!$x) {
throw new Exception('Division by zero.');
}
else return 1/$x;
}
try {
echo inverse(5) . "\n";
echo inverse(0) . "\n";
} catch (Exception $e) {
echo 'Caught exception: ', $e->getMessage(), "\n";
}
// Continue execution
echo 'Hello World';
?>
Powyższy przykład wyświetli:
0.2 Caught exception: Division by zero. Hello World
Przykład #2 Nested Exception
<?php
class MyException extends Exception { }
class Test {
public function testing() {
try {
try {
throw new MyException('foo!');
} catch (MyException $e) {
/* rethrow it */
throw $e;
}
} catch (Exception $e) {
var_dump($e->getMessage());
}
}
}
$foo = new Test;
$foo->testing();
?>
Powyższy przykład wyświetli:
string(4) "foo!"
Extending Exceptions
A User defined Exception class can be defined by extending the built-in Exception class. The members and properties below, show what is accessible within the child class that derives from the built-in Exception class.
Przykład #1 The Built in Exception class
<?php
class Exception
{
protected $message = 'Unknown exception'; // exception message
private $string; // __toString cache
protected $code = 0; // user defined exception code
protected $file; // source filename of exception
protected $line; // source line of exception
private $trace; // backtrace
private $previous; // previous exception if nested exception
public function __construct($message = null, $code = 0, Exception $previous = null);
final private function __clone(); // Inhibits cloning of exceptions.
final public function getMessage(); // message of exception
final public function getCode(); // code of exception
final public function getFile(); // source filename
final public function getLine(); // source line
final public function getTrace(); // an array of the backtrace()
final public function getPrevious(); // previous exception
final public function getTraceAsString(); // formatted string of trace
/* Overrideable */
public function __toString(); // formatted string for display
}
?>
If a class extends the built-in Exception class and re-defines the constructor, it is highly recommended that it also call parent::__construct() to ensure all available data has been properly assigned. The __toString() method can be overridden to provide a custom output when the object is presented as a string.
Informacja:
Exceptions cannot be cloned. Attempting to clone an Exception will result in a fatal
E_ERRORerror.
Przykład #2 Extending the Exception class (PHP 5.3.0+)
<?php
/**
* Define a custom exception class
*/
class MyException extends Exception
{
// Redefine the exception so message isn't optional
public function __construct($message, $code = 0, Exception $previous = null) {
// some code
// make sure everything is assigned properly
parent::__construct($message, $code, $previous);
}
// custom string representation of object
public function __toString() {
return __CLASS__ . ": [{$this->code}]: {$this->message}\n";
}
public function customFunction() {
echo "A custom function for this type of exception\n";
}
}
/**
* Create a class to test the exception
*/
class TestException
{
public $var;
const THROW_NONE = 0;
const THROW_CUSTOM = 1;
const THROW_DEFAULT = 2;
function __construct($avalue = self::THROW_NONE) {
switch ($avalue) {
case self::THROW_CUSTOM:
// throw custom exception
throw new MyException('1 is an invalid parameter', 5);
break;
case self::THROW_DEFAULT:
// throw default one.
throw new Exception('2 is not allowed as a parameter', 6);
break;
default:
// No exception, object will be created.
$this->var = $avalue;
break;
}
}
}
// Example 1
try {
$o = new TestException(TestException::THROW_CUSTOM);
} catch (MyException $e) { // Will be caught
echo "Caught my exception\n", $e;
$e->customFunction();
} catch (Exception $e) { // Skipped
echo "Caught Default Exception\n", $e;
}
// Continue execution
var_dump($o); // Null
echo "\n\n";
// Example 2
try {
$o = new TestException(TestException::THROW_DEFAULT);
} catch (MyException $e) { // Doesn't match this type
echo "Caught my exception\n", $e;
$e->customFunction();
} catch (Exception $e) { // Will be caught
echo "Caught Default Exception\n", $e;
}
// Continue execution
var_dump($o); // Null
echo "\n\n";
// Example 3
try {
$o = new TestException(TestException::THROW_CUSTOM);
} catch (Exception $e) { // Will be caught
echo "Default Exception caught\n", $e;
}
// Continue execution
var_dump($o); // Null
echo "\n\n";
// Example 4
try {
$o = new TestException();
} catch (Exception $e) { // Skipped, no exception
echo "Default Exception caught\n", $e;
}
// Continue execution
var_dump($o); // TestException
echo "\n\n";
?>
Informacja:
Versions of PHP 5, prior to PHP 5.3.0 do not support nesting of exceptions. The following code fragment can be used as a replacement MyException class if you wish to run this example.
<?php
/**
* Define a custom exception class
*/
class MyException extends Exception
{
// Redefine the exception so message isn't optional
public function __construct($message, $code = 0) {
// some code
// make sure everything is assigned properly
parent::__construct($message, $code);
}
// custom string representation of object
public function __toString() {
return __CLASS__ . ": [{$this->code}]: {$this->message}\n";
}
public function customFunction() {
echo "A custom function for this type of exception\n";
}
}
?>
Referencje
Spis treści
- Czym są referencje
- Co robią referencje
- Czym nie są referencje
- Przekazywanie przez referencje
- Zwracanie referencji
- Niszczenie referencji
- Znajdywanie referencji
Czym są referencje
W PHP referencje są środkiem dostępu do tej samej wartości zmiennej poprzez różne nazwy. Nie działają na takiej zasadzie jak wskaźniki w C, lecz są aliasami w tablicy symboli. Zwróc uwagę na to, że w PHP nazwa zmiennej oraz wartość zmiennej są dwiema różnymi rzeczami, wobec tego ta sama wartość może być dostępna poprzez różne nazwy. Najbliższą analogią jest Uniksowy system plików i ich nazw - nazwy zmiennych to wpisy katalogowe, a wartości to same pliki. Można myśleć o referencjach jak o twardych dowiązaniach w Uniksowym systemie plików.
Co robią referencje
W PHP referencje pozwalają na stworzenie dwu zmiennych zawierających tą samą zawartość. Więc poniższy skrypt:
<?php
$a =& $b
?>
Informacja:
$a oraz $b są całkowicie równe, czyli nie $a wskazuje na $b lub odwrotnie, lecz $a oraz $b wskazują na to samo miejsce.
Ta sama składnia może być używana z funkcjami zwracającymi referencje, i z operatorem new (w PHP 4.0.4 i późniejszych):
<?php
$bar =& new foo_klasa();
$foo =& znajdx_zmienna($bar);
?>
Informacja:
Brak operatora & powoduje powstanie kopii obiektu. Jeżeli użyjesz $this wewnątrz klasy, zmienna ta będzie pracować na bieżącym egzemplarzu danej klasy. Dowiązanie bez użycia & spowoduje powstanie kopii egzemplarza danej klasy (czyli naszego obiektu) i $this będzie pracować na kopii, co nie jest zwykle tym czego byśmy chcieli. Zwykle pożądane jest posiadanie tylko jednego egzemplarza z którym chcemy pracować, z powodów wydajności i zajętości pamięci.
Pomimo tego, że możliwe jest użycie operatora @ do wyciszenia ewentualnych błędów w konstruktorze podczas użycia go w konstrukcji @new, to zapis ten nie działa kiedy używana jest konstrukcja &new. Jest to ograniczenie silnika Zend (Zend Engine) i użycie takiego zapisu spowoduje błąd parsowania.
Drugą rzeczą na którą pozwalają referencje jest przekazywanie zmiennych przez-referencje. Możliwe jest to przez uczynienie zmiennej lokalnej w funkcji i zmiennej w zakresie wywoływania tej funkcji odwołujacych się do tej samej wartości. Na przykład:
<?php
function foo (&$zmienna)
{
$zmienna++;
}
$a=5;
foo ($a);
?>
Trzecią rzeczą którą umożliwiają referencje jest zwracanie przez referencje.
Czym nie są referencje
Jak powiedizano wcześniej, referencje nie są wskaźnikami. To znaczy, że poniższy zapis nie zadziała tak jak się wydaje:
<?php
function foo (&$zmienna)
{
$zmienna =& $GLOBALS["baz"];
}
foo($bar);
?>
To, co się faktycznie dzieje, to zmienna $zmienna w funkcji foo będzie związana ze zmienną $bar podczas wywołania, lecz zaraz potem będzie związana po raz wtóry, tym razem z $GLOBALS["baz"]. Nie ma sposobu by związać $bar w zakresie wywoływującym funkcję z czymś innym, używając mechanizmu referencji, ponieważ zmienna $bar nie jest dostępna w funkcji foo (jest tylko reprezentowana przez zmienną $zmienna, lecz $zmienna zawiera tylko wartość zmiennej, a nie jest wiązaniem nazwa-wartość w tablicy symboli).
Przekazywanie przez referencje
Możesz przekazać zmienną do funkcji poprzez referencję, by funkcja mogła modyfikować swoje parametry. Skłania jest jak następuje:
<?php
function foo (&$zmienna)
{
$zmienna++;
}
$a=5;
foo ($a);
// $a jest równe 6 w tym momencie
?>
Przez referencję mogą być przekazywane następujące rzeczy:
- Zmienne, np. foo($a)
- Instrukcja new, np. foo(new foobar())
-
Referencję, zwracane z funkcji, np.:
Zobacz również wyjaśnienia na temat zwracania przez referencję.<?php
function &bar()
{
$a = 5;
return $a;
}
foo(bar());
?>
Każde inne wyrażenie nie powinno być przekazywane przez referencję, ponieważ wynik takiego przekazania jest nieprzewidywalny. Dla przykładu, poniższe przykłady przekazywania przez referencję są niepoprawne:
<?php
function bar() // Zwróć uwagę na brak &
{
$a = 5;
return $a;
}
foo(bar());
foo($a = 5); // Wyrażenie, nie zmienna
foo(5); // Stała, nie zmienna
?>
Zwracanie referencji
Zwracanie przez-referencję jest użyteczne gdy chcesz użyć funkcji do znalezienia zmiennej do której referencją powinna być dowiązana. Zwracając referencje używaj tej składni:
<?php
function &znajdz_zmienna ($param)
{
/* ...kod... */
return $znaleziona_zmienna;
}
$foo =& znajdz_zmienna ($bar);
$foo->x = 2;
?>
Informacja: Inaczej niż przy przekazywaniu parametrów, tutaj musisz używać & w obu miejscach - by wskazać, że zwracasz przez-referencję, a nie kopię jak normalnie, i by zwrócić uwagę, że dla zmiennej $foo powinno być użyte powiązanie przez referencję, a nie zwykłe przypisanie.
Niszczenie referencji
Kiedy niszczysz referencje, zrywasz wiązanie między nazwą zmiennej a jej zawartością. Nie znaczy to, że ta zawartość będzie zniszczona. Na przykład:
<?php
$a = 1;
$b =& $a;
unset ($a);
?>
Znów, pomocne będzie pomyślenie o tym jak o analogii do Uniksowego wywołania unlink.
Znajdywanie referencji
Wiele konstrukcji składniowych w PHP jest zaimplementowanych przy użyciu referencji, tak więc wszystko co zostało powiedziane wcześniej o referencjach dotyczyć będzie również tych konstrukcji. Pewne konstrukcje, jak przekazywanie i zwracanie przez referencje, są wspomniane wyżej. Innymi konstrukcjami używającymi mechanizmu referencji są:
Referencje konstrukcji global
Kiedy deklarujesz zmienną jako global $var to tak naprawdę tworzysz referencję do zmiennej globalnej. To znaczy, że działa to tak samo jak:
<?php
$zmienna =& $GLOBALS["zmienna"];
?>
To znaczy, na przykład, że usunięcie $zmienna nie usunie zmiennej globalnej.
$this
W metodach obiektowych, $this jest zawsze referencją do obiektu wywłującego daną metodę.
Predefined Variables
PHP provides a large number of predefined variables to all scripts. The variables represent everything from external variables to built-in environment variables, last error messages to last retrieved headers.
See also the FAQ titled "How does register_globals affect me?"
Superglobals
Superglobals — Superglobals are built-in variables that are always available in all scopes
Opis
Several predefined variables in PHP are "superglobals", which means they are available in all scopes throughout a script. There is no need to do global $variable; to access them within functions or methods.
These superglobal variables are:
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.1.0 | Superglobals were introduced to PHP. |
Notatki
Informacja: Variable availability
By default, all of the superglobals are available but there are directives that affect this availability. For further information, refer to the documentation for variables_order.
Informacja: Dealing with register_globals
If the deprecated register_globals directive is set to on then the variables within will also be made available in the global scope of the script. For example, $_POST['foo'] would also exist as $foo.
For related information, see the FAQ titled "How does register_globals affect me?"
Informacja: Variable variables
Superglobals cannot be used as variable variables inside functions or class methods.
$GLOBALS
(PHP 4, PHP 5)
$GLOBALS — References all variables available in global scope
Opis
An associative array containing references to all variables which are currently defined in the global scope of the script. The variable names are the keys of the array.
Przykłady
Przykład #1 $GLOBALS example
<?php
function test() {
$foo = "local variable";
echo '$foo in global scope: ' . $GLOBALS["foo"] . "\n";
echo '$foo in current scope: ' . $foo . "\n";
}
$foo = "Example content";
test();
?>
Powyższy przykład wyświetli coś podobnego do:
$foo in global scope: Example content $foo in current scope: local variable
Notatki
Informacja:
To jest zmienna "superglobalna" lub automatycznie ustawiona na globalną. To po prostu oznacza, że jest dostępna w każdym miejscu skryptu. Nie jest konieczne użycie global $zmienna; aby mieć do niej dostęp w funkcjach i metodach.
Informacja: Variable availability
Unlike all of the other superglobals, $GLOBALS has essentially always been available in PHP.
$_SERVER
$HTTP_SERVER_VARS [deprecated]
(PHP 4 >= 4.1.0, PHP 5)
$_SERVER -- $HTTP_SERVER_VARS [deprecated] — Server and execution environment information
Opis
$_SERVER is an array containing information such as headers, paths, and script locations. The entries in this array are created by the web server. There is no guarantee that every web server will provide any of these; servers may omit some, or provide others not listed here. That said, a large number of these variables are accounted for in the » CGI/1.1 specification, so you should be able to expect those.
$HTTP_SERVER_VARS contains the same initial information, but is not a superglobal. (Note that $HTTP_SERVER_VARS and $_SERVER are different variables and that PHP handles them as such)
Wykaz zmiennych
You may or may not find any of the following elements in $_SERVER. Note that few, if any, of these will be available (or indeed have any meaning) if running PHP on the command line.
- 'PHP_SELF'
- The filename of the currently executing script, relative to the document root. For instance, $_SERVER['PHP_SELF'] in a script at the address http://example.com/test.php/foo.bar would be /test.php/foo.bar. The __FILE__ constant contains the full path and filename of the current (i.e. included) file. If PHP is running as a command-line processor this variable contains the script name since PHP 4.3.0. Previously it was not available.
- 'argv'
- Array of arguments passed to the script. When the script is run on the command line, this gives C-style access to the command line parameters. When called via the GET method, this will contain the query string.
- 'argc'
- Contains the number of command line parameters passed to the script (if run on the command line).
- 'GATEWAY_INTERFACE'
- What revision of the CGI specification the server is using; i.e. 'CGI/1.1'.
- 'SERVER_ADDR'
- The IP address of the server under which the current script is executing.
- 'SERVER_NAME'
- The name of the server host under which the current script is executing. If the script is running on a virtual host, this will be the value defined for that virtual host.
- 'SERVER_SOFTWARE'
- Server identification string, given in the headers when responding to requests.
- 'SERVER_PROTOCOL'
- Name and revision of the information protocol via which the page was requested; i.e. 'HTTP/1.0';
- 'REQUEST_METHOD'
-
Which request method was used to access the page; i.e. 'GET',
'HEAD', 'POST', 'PUT'.
Informacja:
PHP script is terminated after sending headers (it means after producing any output without output buffering) if the request method was HEAD.
- 'REQUEST_TIME'
- The timestamp of the start of the request. Available since PHP 5.1.0.
- 'REQUEST_TIME_FLOAT'
- The timestamp of the start of the request, with microsecond precision. Available since PHP 5.4.0.
- 'QUERY_STRING'
- The query string, if any, via which the page was accessed.
- 'DOCUMENT_ROOT'
- The document root directory under which the current script is executing, as defined in the server's configuration file.
- 'HTTP_ACCEPT'
- Contents of the Accept: header from the current request, if there is one.
- 'HTTP_ACCEPT_CHARSET'
- Contents of the Accept-Charset: header from the current request, if there is one. Example: 'iso-8859-1,*,utf-8'.
- 'HTTP_ACCEPT_ENCODING'
- Contents of the Accept-Encoding: header from the current request, if there is one. Example: 'gzip'.
- 'HTTP_ACCEPT_LANGUAGE'
- Contents of the Accept-Language: header from the current request, if there is one. Example: 'en'.
- 'HTTP_CONNECTION'
- Contents of the Connection: header from the current request, if there is one. Example: 'Keep-Alive'.
- 'HTTP_HOST'
- Contents of the Host: header from the current request, if there is one.
- 'HTTP_REFERER'
- The address of the page (if any) which referred the user agent to the current page. This is set by the user agent. Not all user agents will set this, and some provide the ability to modify HTTP_REFERER as a feature. In short, it cannot really be trusted.
- 'HTTP_USER_AGENT'
- Contents of the User-Agent: header from the current request, if there is one. This is a string denoting the user agent being which is accessing the page. A typical example is: Mozilla/4.5 [en] (X11; U; Linux 2.2.9 i586). Among other things, you can use this value with get_browser() to tailor your page's output to the capabilities of the user agent.
- 'HTTPS'
-
Set to a non-empty value if the script was queried through the HTTPS
protocol.
Informacja: Note that when using ISAPI with IIS, the value will be off if the request was not made through the HTTPS protocol.
- 'REMOTE_ADDR'
- The IP address from which the user is viewing the current page.
- 'REMOTE_HOST'
-
The Host name from which the user is viewing the current
page. The reverse dns lookup is based off the
REMOTE_ADDR of the user.
Informacja: Your web server must be configured to create this variable. For example in Apache you'll need HostnameLookups On inside httpd.conf for it to exist. See also gethostbyaddr().
- 'REMOTE_PORT'
- The port being used on the user's machine to communicate with the web server.
- 'REMOTE_USER'
- The authenticated user.
- 'REDIRECT_REMOTE_USER'
- The authenticated user if the request is internally redirected.
- 'SCRIPT_FILENAME'
-
The absolute pathname of the currently executing script.
Informacja:
If a script is executed with the CLI, as a relative path, such as file.php or ../file.php, $_SERVER['SCRIPT_FILENAME'] will contain the relative path specified by the user.
- 'SERVER_ADMIN'
- The value given to the SERVER_ADMIN (for Apache) directive in the web server configuration file. If the script is running on a virtual host, this will be the value defined for that virtual host.
- 'SERVER_PORT'
- The port on the server machine being used by the web server for communication. For default setups, this will be '80'; using SSL, for instance, will change this to whatever your defined secure HTTP port is.
- 'SERVER_SIGNATURE'
- String containing the server version and virtual host name which are added to server-generated pages, if enabled.
- 'PATH_TRANSLATED'
-
Filesystem- (not document root-) based path to the current
script, after the server has done any virtual-to-real
mapping.
Informacja: As of PHP 4.3.2, PATH_TRANSLATED is no longer set implicitly under the Apache 2 SAPI in contrast to the situation in Apache 1, where it's set to the same value as the SCRIPT_FILENAME server variable when it's not populated by Apache. This change was made to comply with the CGI specification that PATH_TRANSLATED should only exist if PATH_INFO is defined. Apache 2 users may use AcceptPathInfo = On inside httpd.conf to define PATH_INFO.
- 'SCRIPT_NAME'
- Contains the current script's path. This is useful for pages which need to point to themselves. The __FILE__ constant contains the full path and filename of the current (i.e. included) file.
- 'REQUEST_URI'
- The URI which was given in order to access this page; for instance, '/index.html'.
- 'PHP_AUTH_DIGEST'
- When doing Digest HTTP authentication this variable is set to the 'Authorization' header sent by the client (which you should then use to make the appropriate validation).
- 'PHP_AUTH_USER'
- When doing HTTP authentication this variable is set to the username provided by the user.
- 'PHP_AUTH_PW'
- When doing HTTP authentication this variable is set to the password provided by the user.
- 'AUTH_TYPE'
- When doing HTTP authenticated this variable is set to the authentication type.
- 'PATH_INFO'
- Contains any client-provided pathname information trailing the actual script filename but preceding the query string, if available. For instance, if the current script was accessed via the URL http://www.example.com/php/path_info.php/some/stuff?foo=bar, then $_SERVER['PATH_INFO'] would contain /some/stuff.
- 'ORIG_PATH_INFO'
- Original version of 'PATH_INFO' before processed by PHP.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.1.0 | Introduced $_SERVER that deprecated $HTTP_SERVER_VARS. |
Przykłady
Przykład #1 $_SERVER example
<?php
echo $_SERVER['SERVER_NAME'];
?>
Powyższy przykład wyświetli coś podobnego do:
www.example.com
Notatki
Informacja:
To jest zmienna "superglobalna" lub automatycznie ustawiona na globalną. To po prostu oznacza, że jest dostępna w każdym miejscu skryptu. Nie jest konieczne użycie global $zmienna; aby mieć do niej dostęp w funkcjach i metodach.
$_GET
$HTTP_GET_VARS [deprecated]
(PHP 4 >= 4.1.0, PHP 5)
$_GET -- $HTTP_GET_VARS [deprecated] — HTTP GET variables
Opis
An associative array of variables passed to the current script via the URL parameters.
$HTTP_GET_VARS contains the same initial information, but is not a superglobal. (Note that $HTTP_GET_VARS and $_GET are different variables and that PHP handles them as such)
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.1.0 | Introduced $_GET that deprecated $HTTP_GET_VARS. |
Przykłady
Przykład #1 $_GET example
<?php
echo 'Hello ' . htmlspecialchars($_GET["name"]) . '!';
?>
Assuming the user entered http://example.com/?name=Hannes
Powyższy przykład wyświetli coś podobnego do:
Hello Hannes!
Notatki
Informacja:
To jest zmienna "superglobalna" lub automatycznie ustawiona na globalną. To po prostu oznacza, że jest dostępna w każdym miejscu skryptu. Nie jest konieczne użycie global $zmienna; aby mieć do niej dostęp w funkcjach i metodach.
Informacja:
The GET variables are passed through urldecode().
$_POST
$HTTP_POST_VARS [deprecated]
(PHP 4 >= 4.1.0, PHP 5)
$_POST -- $HTTP_POST_VARS [deprecated] — HTTP POST variables
Opis
An associative array of variables passed to the current script via the HTTP POST method.
$HTTP_POST_VARS contains the same initial information, but is not a superglobal. (Note that $HTTP_POST_VARS and $_POST are different variables and that PHP handles them as such)
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.1.0 | Introduced $_POST that deprecated $HTTP_POST_VARS. |
Przykłady
Przykład #1 $_POST example
<?php
echo 'Hello ' . htmlspecialchars($_POST["name"]) . '!';
?>
Assuming the user POSTed name=Hannes
Powyższy przykład wyświetli coś podobnego do:
Hello Hannes!
Notatki
Informacja:
To jest zmienna "superglobalna" lub automatycznie ustawiona na globalną. To po prostu oznacza, że jest dostępna w każdym miejscu skryptu. Nie jest konieczne użycie global $zmienna; aby mieć do niej dostęp w funkcjach i metodach.
$_FILES
$HTTP_POST_FILES [deprecated]
(PHP 4 >= 4.1.0, PHP 5)
$_FILES -- $HTTP_POST_FILES [deprecated] — HTTP File Upload variables
Opis
An associative array of items uploaded to the current script via the HTTP POST method.
$HTTP_POST_FILES contains the same initial information, but is not a superglobal. (Note that $HTTP_POST_FILES and $_FILES are different variables and that PHP handles them as such)
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.1.0 | Introduced $_FILES that deprecated $HTTP_POST_FILES. |
Notatki
Informacja:
To jest zmienna "superglobalna" lub automatycznie ustawiona na globalną. To po prostu oznacza, że jest dostępna w każdym miejscu skryptu. Nie jest konieczne użycie global $zmienna; aby mieć do niej dostęp w funkcjach i metodach.
Zobacz też:
- move_uploaded_file() - Przenieś uploadowany plik do innej lokalizacji
- Handling File Uploads
$_REQUEST
(PHP 4 >= 4.1.0, PHP 5)
$_REQUEST — HTTP Request variables
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.0 | Introduced request_order. This directive affects the contents of $_REQUEST. |
| 4.3.0 | $_FILES information was removed from $_REQUEST. |
| 4.1.0 | Introduced $_REQUEST. |
Notatki
Informacja:
To jest zmienna "superglobalna" lub automatycznie ustawiona na globalną. To po prostu oznacza, że jest dostępna w każdym miejscu skryptu. Nie jest konieczne użycie global $zmienna; aby mieć do niej dostęp w funkcjach i metodach.
Informacja:
When running on the command line , this will not include the argv and argc entries; these are present in the $_SERVER array.
Informacja:
The variables in $_REQUEST are provided to the script via the GET, POST, and COOKIE input mechanisms and therefore could be modified by the remote user and cannot be trusted. The presence and order of variables listed in this array is defined according to the PHP variables_order configuration directive.
Zobacz też:
- import_request_variables() - Import GET/POST/Cookie variables into the global scope
- Handling external variables
- The filter extension
$_SESSION
$HTTP_SESSION_VARS [deprecated]
(PHP 4 >= 4.1.0, PHP 5)
$_SESSION -- $HTTP_SESSION_VARS [deprecated] — Session variables
Opis
An associative array containing session variables available to the current script. See the Session functions documentation for more information on how this is used.
$HTTP_SESSION_VARS contains the same initial information, but is not a superglobal. (Note that $HTTP_SESSION_VARS and $_SESSION are different variables and that PHP handles them as such)
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.1.0 | Introduced $_SESSION that deprecated $HTTP_SESSION_VARS. |
Notatki
Informacja:
To jest zmienna "superglobalna" lub automatycznie ustawiona na globalną. To po prostu oznacza, że jest dostępna w każdym miejscu skryptu. Nie jest konieczne użycie global $zmienna; aby mieć do niej dostęp w funkcjach i metodach.
$_ENV
$HTTP_ENV_VARS [deprecated]
(PHP 4 >= 4.1.0, PHP 5)
$_ENV -- $HTTP_ENV_VARS [deprecated] — Environment variables
Opis
An associative array of variables passed to the current script via the environment method.
These variables are imported into PHP's global namespace from the environment under which the PHP parser is running. Many are provided by the shell under which PHP is running and different systems are likely running different kinds of shells, a definitive list is impossible. Please see your shell's documentation for a list of defined environment variables.
Other environment variables include the CGI variables, placed there regardless of whether PHP is running as a server module or CGI processor.
$HTTP_ENV_VARS contains the same initial information, but is not a superglobal. (Note that $HTTP_ENV_VARS and $_ENV are different variables and that PHP handles them as such)
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.1.0 | Introduced $_ENV that deprecated $HTTP_ENV_VARS. |
Przykłady
Przykład #1 $_ENV example
<?php
echo 'My username is ' .$_ENV["USER"] . '!';
?>
Assuming "bjori" executes this script
Powyższy przykład wyświetli coś podobnego do:
My username is bjori!
Notatki
Informacja:
To jest zmienna "superglobalna" lub automatycznie ustawiona na globalną. To po prostu oznacza, że jest dostępna w każdym miejscu skryptu. Nie jest konieczne użycie global $zmienna; aby mieć do niej dostęp w funkcjach i metodach.
$php_errormsg
(PHP 4, PHP 5)
$php_errormsg — The previous error message
Opis
$php_errormsg is a variable containing the text of the last error message generated by PHP. This variable will only be available within the scope in which the error occurred, and only if the track_errors configuration option is turned on (it defaults to off).
Informacja: This variable is only available when track_errors is enabled in php.ini.
If a user defined error handler (set_error_handler())
is set $php_errormsg is only set if the error handler
returns FALSE
Przykłady
Przykład #1 $php_errormsg example
<?php
@strpos();
echo $php_errormsg;
?>
Powyższy przykład wyświetli coś podobnego do:
Wrong parameter count for strpos()
$HTTP_RAW_POST_DATA
(PHP 4, PHP 5)
$HTTP_RAW_POST_DATA — Raw POST data
Opis
$HTTP_RAW_POST_DATA contains the raw POST data. See always_populate_raw_post_data
$http_response_header
(PHP 4 >= 4.0.4, PHP 5)
$http_response_header — HTTP response headers
Opis
The $http_response_header array is similar to the get_headers() function. When using the HTTP wrapper, $http_response_header will be populated with the HTTP response headers. $http_response_header will be created in the local scope.
Przykłady
Przykład #1 $http_response_header example
<?php
function get_contents() {
file_get_contents("http://example.com");
var_dump($http_response_header);
}
get_contents();
var_dump($http_response_header);
?>
Powyższy przykład wyświetli coś podobnego do:
array(9) {
[0]=>
string(15) "HTTP/1.1 200 OK"
[1]=>
string(35) "Date: Sat, 12 Apr 2008 17:30:38 GMT"
[2]=>
string(29) "Server: Apache/2.2.3 (CentOS)"
[3]=>
string(44) "Last-Modified: Tue, 15 Nov 2005 13:24:10 GMT"
[4]=>
string(27) "ETag: "280100-1b6-80bfd280""
[5]=>
string(20) "Accept-Ranges: bytes"
[6]=>
string(19) "Content-Length: 438"
[7]=>
string(17) "Connection: close"
[8]=>
string(38) "Content-Type: text/html; charset=UTF-8"
}
NULL
$argc
(PHP 4, PHP 5)
$argc — The number of arguments passed to script
Opis
Contains the number of arguments passed to the current script when running from the command line.
Informacja: The script's filename is always passed as an argument to the script, therefore the minimum value of $argc is 1.
Informacja: This variable is not available when register_argc_argv is disabled.
Przykłady
Przykład #1 $argc example
<?php
var_dump($argc);
?>
When executing the example with: php script.php arg1 arg2 arg3
Powyższy przykład wyświetli coś podobnego do:
int(4)
$argv
(PHP 4, PHP 5)
$argv — Array of arguments passed to script
Opis
Contains an array of all the arguments passed to the script when running from the command line.
Informacja: The first argument $argv[0] is always the name that was used to run the script.
Informacja: This variable is not available when register_argc_argv is disabled.
Przykłady
Przykład #1 $argv example
<?php
var_dump($argv);
?>
When executing the example with: php script.php arg1 arg2 arg3
Powyższy przykład wyświetli coś podobnego do:
array(4) {
[0]=>
string(10) "script.php"
[1]=>
string(4) "arg1"
[2]=>
string(4) "arg2"
[3]=>
string(4) "arg3"
}
Spis treści
- Superglobals — Superglobals are built-in variables that are always available in all scopes
- $GLOBALS — References all variables available in global scope
- $_SERVER — Server and execution environment information
- $_GET — HTTP GET variables
- $_POST — HTTP POST variables
- $_FILES — HTTP File Upload variables
- $_REQUEST — HTTP Request variables
- $_SESSION — Session variables
- $_ENV — Environment variables
- $_COOKIE — HTTP Cookies
- $php_errormsg — The previous error message
- $HTTP_RAW_POST_DATA — Raw POST data
- $http_response_header — HTTP response headers
- $argc — The number of arguments passed to script
- $argv — Array of arguments passed to script
Predefined Exceptions
Spis treści
See also the SPL Exceptions
Exception
(PHP 5 >= 5.1.0)
Wstęp
Exception is the base class for all Exceptions.
Krótki opis klasy
Właściwości
- message
-
The exception message
- code
-
The exception code
- file
-
The filename where the exception was created
- line
-
The line where the exception was created
Exception::__construct
(PHP 5 >= 5.1.0)
Exception::__construct — Construct the exception
Opis
$message = ""
[, int $code = 0
[, Exception $previous = NULL
]]] )Constructs the Exception.
Parametry
-
message -
The Exception message to throw.
-
code -
The Exception code.
-
previous -
The previous exception used for the exception chaining.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.0 |
The previous parameter was added.
|
Notatki
Informacja:
The
messageis NOT binary safe.
Exception::getMessage
(PHP 5 >= 5.1.0)
Exception::getMessage — Gets the Exception message
Opis
Returns the Exception message.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the Exception message as a string.
Przykłady
Przykład #1 Exception::getMessage() example
<?php
try {
throw new Exception("Some error message");
} catch(Exception $e) {
echo $e->getMessage();
}
?>
Powyższy przykład wyświetli coś podobnego do:
Some error message
Exception::getPrevious
(PHP 5 >= 5.3.0)
Exception::getPrevious — Returns previous Exception
Opis
Returns previous Exception (the third parameter of Exception::__construct()).
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the previous Exception if available
or NULL otherwise.
Przykłady
Przykład #1 Exception::getPrevious() example
Looping over, and printing out, exception trace.
<?php
class MyCustomException extends Exception {}
function doStuff() {
try {
throw new InvalidArgumentException("You are doing it wrong!", 112);
} catch(Exception $e) {
throw new MyCustomException("Something happend", 911, $e);
}
}
try {
doStuff();
} catch(Exception $e) {
do {
printf("%s:%d %s (%d) [%s]\n", $e->getFile(), $e->getLine(), $e->getMessage(), $e->getCode(), get_class($e));
} while($e = $e->getPrevious());
}
?>
Powyższy przykład wyświetli coś podobnego do:
/home/bjori/ex.php:8 Something happend (911) [MyCustomException] /home/bjori/ex.php:6 You are doing it wrong! (112) [InvalidArgumentException]
Exception::getCode
(PHP 5 >= 5.1.0)
Exception::getCode — Gets the Exception code
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the exception code as integer in Exception but possibly as other type in Exception descendants (for example as string in PDOException).
Przykłady
Przykład #1 Exception::getCode() example
<?php
try {
throw new Exception("Some error message", 30);
} catch(Exception $e) {
echo "The exception code is: " . $e->getCode();
}
?>
Powyższy przykład wyświetli coś podobnego do:
The exception code is: 30
Exception::getFile
(PHP 5 >= 5.1.0)
Exception::getFile — Gets the file in which the exception occurred
Opis
Get the name of the file the exception was created.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the filename in which the exception was created.
Przykłady
Przykład #1 Exception::getFile() example
<?php
try {
throw new Exception;
} catch(Exception $e) {
echo $e->getFile();
}
?>
Powyższy przykład wyświetli coś podobnego do:
/home/bjori/tmp/ex.php
Exception::getLine
(PHP 5 >= 5.1.0)
Exception::getLine — Gets the line in which the exception occurred
Opis
Get line number where the exception was created.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the line number where the exception was created.
Przykłady
Przykład #1 Exception::getLine() example
<?php
try {
throw new Exception("Some error message");
} catch(Exception $e) {
echo "The exception was created on line: " . $e->getLine();
}
?>
Powyższy przykład wyświetli coś podobnego do:
The exception was created on line: 3
Exception::getTrace
(PHP 5 >= 5.1.0)
Exception::getTrace — Gets the stack trace
Opis
Returns the Exception stack trace.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the Exception stack trace as an array.
Przykłady
Przykład #1 Exception::getTrace() example
<?php
function test() {
throw new Exception;
}
try {
test();
} catch(Exception $e) {
var_dump($e->getTrace());
}
?>
Powyższy przykład wyświetli coś podobnego do:
array(1) {
[0]=>
array(4) {
["file"]=>
string(22) "/home/bjori/tmp/ex.php"
["line"]=>
int(7)
["function"]=>
string(4) "test"
["args"]=>
array(0) {
}
}
}
Exception::getTraceAsString
(PHP 5 >= 5.1.0)
Exception::getTraceAsString — Gets the stack trace as a string
Opis
Returns the Exception stack trace as a string.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the Exception stack trace as a string.
Przykłady
Przykład #1 Exception::getTraceAsString() example
<?php
function test() {
throw new Exception;
}
try {
test();
} catch(Exception $e) {
echo $e->getTraceAsString();
}
?>
Powyższy przykład wyświetli coś podobnego do:
#0 /home/bjori/tmp/ex.php(7): test()
#1 {main}
Exception::__toString
(PHP 5 >= 5.1.0)
Exception::__toString — String representation of the exception
Opis
Returns the string representation of the exception.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the string representation of the exception.
Przykłady
Przykład #1 Exception::__toString() example
<?php
try {
throw new Exception("Some error message");
} catch(Exception $e) {
echo $e;
}
?>
Powyższy przykład wyświetli coś podobnego do:
exception 'Exception' with message 'Some error message' in /home/bjori/tmp/ex.php:3
Stack trace:
#0 {main}
Exception::__clone
(PHP 5 >= 5.1.0)
Exception::__clone — Clone the exception
Opis
Tries to clone the Exception, which results in Fatal error.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Nie jest zwracana żadna wartość.
Błędy/Wyjątki
Exceptions are not clonable.
Spis treści
- Exception::__construct — Construct the exception
- Exception::getMessage — Gets the Exception message
- Exception::getPrevious — Returns previous Exception
- Exception::getCode — Gets the Exception code
- Exception::getFile — Gets the file in which the exception occurred
- Exception::getLine — Gets the line in which the exception occurred
- Exception::getTrace — Gets the stack trace
- Exception::getTraceAsString — Gets the stack trace as a string
- Exception::__toString — String representation of the exception
- Exception::__clone — Clone the exception
ErrorException
(PHP 5 >= 5.1.0)
Wstęp
An Error Exception.
Krótki opis klasy
$message = ""
[, int $code = 0
[, int $severity = 1
[, string $filename = __FILE__
[, int $lineno = __LINE__
[, Exception $previous = NULL
]]]]]] )Właściwości
- severity
-
The severity of the exception
Przykłady
Przykład #1 Use set_error_handler() to change error messages into ErrorException.
<?php
function exception_error_handler($errno, $errstr, $errfile, $errline ) {
throw new ErrorException($errstr, 0, $errno, $errfile, $errline);
}
set_error_handler("exception_error_handler");
/* Trigger exception */
strpos();
?>
Powyższy przykład wyświetli coś podobnego do:
Fatal error: Uncaught exception 'ErrorException' with message 'Wrong parameter count for strpos()' in /home/bjori/tmp/ex.php:8
Stack trace:
#0 [internal function]: exception_error_handler(2, 'Wrong parameter...', '/home/bjori/php...', 8, Array)
#1 /home/bjori/php/cleandocs/test.php(8): strpos()
#2 {main}
thrown in /home/bjori/tmp/ex.php on line 8
ErrorException::__construct
(PHP 5 >= 5.1.0)
ErrorException::__construct — Constructs the exception
Opis
$message = ""
[, int $code = 0
[, int $severity = 1
[, string $filename = __FILE__
[, int $lineno = __LINE__
[, Exception $previous = NULL
]]]]]] )Constructs the Exception.
Parametry
-
message -
The Exception message to throw.
-
code -
The Exception code.
-
severity -
The severity level of the exception.
-
filename -
The filename where the exception is thrown.
-
lineno -
The line number where the exception is thrown.
-
previous -
The previous exception used for the exception chaining.
ErrorException::getSeverity
(PHP 5 >= 5.1.0)
ErrorException::getSeverity — Gets the exception severity
Opis
Returns the severity of the exception.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the severity level of the exception.
Przykłady
Przykład #1 ErrorException::getSeverity() example
<?php
try {
throw new ErrorException("Exception message", 0, 75);
} catch(ErrorException $e) {
echo "This exception severity is: " . $e->getSeverity();
}
?>
Powyższy przykład wyświetli coś podobnego do:
This exception severity is: 75
Spis treści
- ErrorException::__construct — Constructs the exception
- ErrorException::getSeverity — Gets the exception severity
Predefined Interfaces
Spis treści
See also the SPL Interfaces
The Traversable interface
(No version information available, might only be in SVN)
Wstęp
Interface to detect if a class is traversable using foreach.
Abstract base interface that cannot be implemented alone. Instead it must be implemented by either IteratorAggregate or Iterator.
Informacja:
Internal (built-in) classes that implement this interface can be used in a foreach construct and do not need to implement IteratorAggregate or Iterator.
Informacja:
This is an internal engine interface which cannot be implemented in PHP scripts. Either IteratorAggregate or Iterator must be used instead.
Zestawienie interfejsu
This interface has no methods, its only purpose is to be the base interface for all traversable classes.
The Iterator interface
(PHP 5 >= 5.0.0)
Wstęp
Interface for external iterators or objects that can be iterated themselves internally.
Zestawienie interfejsu
Predefined iterators
PHP already provides a number of iterators for many day to day tasks. See SPL iterators for a list.
Przykłady
Przykład #1 Basic usage
This example demonstrates in which order methods are called when using foreach with an iterator.
<?php
class myIterator implements Iterator {
private $position = 0;
private $array = array(
"firstelement",
"secondelement",
"lastelement",
);
public function __construct() {
$this->position = 0;
}
function rewind() {
var_dump(__METHOD__);
$this->position = 0;
}
function current() {
var_dump(__METHOD__);
return $this->array[$this->position];
}
function key() {
var_dump(__METHOD__);
return $this->position;
}
function next() {
var_dump(__METHOD__);
++$this->position;
}
function valid() {
var_dump(__METHOD__);
return isset($this->array[$this->position]);
}
}
$it = new myIterator;
foreach($it as $key => $value) {
var_dump($key, $value);
echo "\n";
}
?>
Powyższy przykład wyświetli coś podobnego do:
string(18) "myIterator::rewind" string(17) "myIterator::valid" string(19) "myIterator::current" string(15) "myIterator::key" int(0) string(12) "firstelement" string(16) "myIterator::next" string(17) "myIterator::valid" string(19) "myIterator::current" string(15) "myIterator::key" int(1) string(13) "secondelement" string(16) "myIterator::next" string(17) "myIterator::valid" string(19) "myIterator::current" string(15) "myIterator::key" int(2) string(11) "lastelement" string(16) "myIterator::next" string(17) "myIterator::valid"
Iterator::current
(PHP 5 >= 5.0.0)
Iterator::current — Return the current element
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Can return any type.
Iterator::key
(PHP 5 >= 5.0.0)
Iterator::key — Return the key of the current element
Opis
Returns the key of the current element.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns scalar on success, or NULL on failure.
Błędy/Wyjątki
Issues E_NOTICE on failure.
Iterator::next
(PHP 5 >= 5.0.0)
Iterator::next — Move forward to next element
Opis
Moves the current position to the next element.
Informacja:
This method is called after each foreach loop.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Any returned value is ignored.
Iterator::rewind
(PHP 5 >= 5.0.0)
Iterator::rewind — Rewind the Iterator to the first element
Opis
Rewinds back to the first element of the Iterator.
Informacja:
This is the first method called when starting a foreach loop. It will not be executed after foreach loops.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Any returned value is ignored.
Iterator::valid
(PHP 5 >= 5.0.0)
Iterator::valid — Checks if current position is valid
Opis
This method is called after Iterator::rewind() and Iterator::next() to check if the current position is valid.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
The return value will be casted to boolean and then evaluated.
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Spis treści
- Iterator::current — Return the current element
- Iterator::key — Return the key of the current element
- Iterator::next — Move forward to next element
- Iterator::rewind — Rewind the Iterator to the first element
- Iterator::valid — Checks if current position is valid
The IteratorAggregate interface
(PHP 5 >= 5.0.0)
Wstęp
Interface to create an external Iterator.
Zestawienie interfejsu
Przykład #1 Basic usage
<?php
class myData implements IteratorAggregate {
public $property1 = "Public property one";
public $property2 = "Public property two";
public $property3 = "Public property three";
public function __construct() {
$this->property4 = "last property";
}
public function getIterator() {
return new ArrayIterator($this);
}
}
$obj = new myData;
foreach($obj as $key => $value) {
var_dump($key, $value);
echo "\n";
}
?>
Powyższy przykład wyświetli coś podobnego do:
string(9) "property1" string(19) "Public property one" string(9) "property2" string(19) "Public property two" string(9) "property3" string(21) "Public property three" string(9) "property4" string(13) "last property"
IteratorAggregate::getIterator
(PHP 5 >= 5.0.0)
IteratorAggregate::getIterator — Retrieve an external iterator
Opis
Returns an external iterator.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
An instance of an object implementing Iterator or Traversable
Błędy/Wyjątki
Throws an Exception on failure.
Spis treści
- IteratorAggregate::getIterator — Retrieve an external iterator
The ArrayAccess interface
(PHP 5 >= 5.0.0)
Wstęp
Interface to provide accessing objects as arrays.
Zestawienie interfejsu
Przykład #1 Basic usage
<?php
class obj implements arrayaccess {
private $container = array();
public function __construct() {
$this->container = array(
"one" => 1,
"two" => 2,
"three" => 3,
);
}
public function offsetSet($offset, $value) {
if (is_null($offset)) {
$this->container[] = $value;
} else {
$this->container[$offset] = $value;
}
}
public function offsetExists($offset) {
return isset($this->container[$offset]);
}
public function offsetUnset($offset) {
unset($this->container[$offset]);
}
public function offsetGet($offset) {
return isset($this->container[$offset]) ? $this->container[$offset] : null;
}
}
$obj = new obj;
var_dump(isset($obj["two"]));
var_dump($obj["two"]);
unset($obj["two"]);
var_dump(isset($obj["two"]));
$obj["two"] = "A value";
var_dump($obj["two"]);
$obj[] = 'Append 1';
$obj[] = 'Append 2';
$obj[] = 'Append 3';
print_r($obj);
?>
Powyższy przykład wyświetli coś podobnego do:
bool(true)
int(2)
bool(false)
string(7) "A value"
obj Object
(
[container:obj:private] => Array
(
[one] => 1
[three] => 3
[two] => A value
[0] => Append 1
[1] => Append 2
[2] => Append 3
)
)
ArrayAccess::offsetExists
(PHP 5 >= 5.0.0)
ArrayAccess::offsetExists — Whether a offset exists
Opis
Whether or not an offset exists.
This method is executed when using isset() or empty() on objects implementing ArrayAccess.
Informacja:
When using empty() ArrayAccess::offsetGet() will be called and checked if empty only if ArrayAccess::offsetExists() returns
TRUE.
Parametry
-
offset -
An offset to check for.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Informacja:
The return value will be casted to boolean if non-boolean was returned.
Przykłady
Przykład #1 ArrayAccess::offsetExists() example
<?php
class obj implements arrayaccess {
public function offsetSet($offset, $value) {
var_dump(__METHOD__);
}
public function offsetExists($var) {
var_dump(__METHOD__);
if ($var == "foobar") {
return true;
}
return false;
}
public function offsetUnset($var) {
var_dump(__METHOD__);
}
public function offsetGet($var) {
var_dump(__METHOD__);
return "value";
}
}
$obj = new obj;
echo "Runs obj::offsetExists()\n";
var_dump(isset($obj["foobar"]));
echo "\nRuns obj::offsetExists() and obj::offsetGet()\n";
var_dump(empty($obj["foobar"]));
echo "\nRuns obj::offsetExists(), *not* obj:offsetGet() as there is nothing to get\n";
var_dump(empty($obj["foobaz"]));
?>
Powyższy przykład wyświetli coś podobnego do:
Runs obj::offsetExists() string(17) "obj::offsetExists" bool(true) Runs obj::offsetExists() and obj::offsetGet() string(17) "obj::offsetExists" string(14) "obj::offsetGet" bool(false) Runs obj::offsetExists(), *not* obj:offsetGet() as there is nothing to get string(17) "obj::offsetExists" bool(true)
ArrayAccess::offsetGet
(PHP 5 >= 5.0.0)
ArrayAccess::offsetGet — Offset to retrieve
Opis
Returns the value at specified offset.
This method is executed when checking if offset is empty().
Parametry
-
offset -
The offset to retrieve.
Notatki
Informacja:
Starting with PHP 5.3.4, the prototype checks were relaxed and it's possible for implementations of this method to return by reference. This makes indirect modifications to the overloaded array dimensions of ArrayAccess objects possible.
A direct modification is one that replaces completely the value of the array dimension, as in $obj[6] = 7. An indirect modification, on the other hand, only changes part of the dimension, or attempts to assign the dimension by reference to another variable, as in $obj[6][7] = 7 or $var =& $obj[6]. Increments with ++ and decrements with -- are also implemented in a way that requires indirect modification.
While direct modification triggers a call to ArrayAccess::offsetSet(), indirect modification triggers a call to ArrayAccess::offsetGet(). In that case, the implementation of ArrayAccess::offsetGet() must be able to return by reference, otherwise an
E_NOTICEmessage is raised.
Zwracane wartości
Can return all value types.
ArrayAccess::offsetSet
(PHP 5 >= 5.0.0)
ArrayAccess::offsetSet — Offset to set
Opis
Assigns a value to the specified offset.
Parametry
-
offset -
The offset to assign the value to.
-
value -
The value to set.
Zwracane wartości
Nie jest zwracana żadna wartość.
Notatki
Informacja:
The
offsetparameter will be set toNULLif another value is not available, like in the following example.<?php
$arrayaccess[] = "first value";
$arrayaccess[] = "second value";
print_r($arrayaccess);
?>Powyższy przykład wyświetli:
Array ( [0] => first value [1] => second value )
Informacja:
This function is not called in assignments by reference and otherwise indirect changes to array dimensions overloaded with ArrayAccess (indirect in the sense they are made not by changing the dimension directly, but by changing a sub-dimension or sub-property or assigning the array dimension by reference to another variable). Instead, ArrayAccess::offsetGet() is called. The operation will only be successful if that method returns by reference, which is only possible since PHP 5.3.4.
ArrayAccess::offsetUnset
(PHP 5 >= 5.0.0)
ArrayAccess::offsetUnset — Offset to unset
Parametry
-
offset -
The offset to unset.
Zwracane wartości
Nie jest zwracana żadna wartość.
Spis treści
- ArrayAccess::offsetExists — Whether a offset exists
- ArrayAccess::offsetGet — Offset to retrieve
- ArrayAccess::offsetSet — Offset to set
- ArrayAccess::offsetUnset — Offset to unset
The Serializable interface
(PHP 5 >= 5.1.0)
Wstęp
Interface for customized serializing.
Classes that implement this interface no longer support __sleep() and __wakeup(). The method serialize is called whenever an instance needs to be serialized. This does not invoke __destruct() or has any other side effect unless programmed inside the method. When the data is unserialized the class is known and the appropriate unserialize() method is called as a constructor instead of calling __construct(). If you need to execute the standard constructor you may do so in the method.
Zestawienie interfejsu
Przykład #1 Basic usage
<?php
class obj implements Serializable {
private $data;
public function __construct() {
$this->data = "My private data";
}
public function serialize() {
return serialize($this->data);
}
public function unserialize($data) {
$this->data = unserialize($data);
}
public function getData() {
return $this->data;
}
}
$obj = new obj;
$ser = serialize($obj);
var_dump($ser);
$newobj = unserialize($ser);
var_dump($newobj->getData());
?>
Powyższy przykład wyświetli coś podobnego do:
string(38) "C:3:"obj":23:{s:15:"My private data";}"
string(15) "My private data"
Serializable::serialize
(PHP 5 >= 5.1.0)
Serializable::serialize — String representation of object
Opis
Should return the string representation of the object.
Informacja:
This method acts as the destructor of the object. The __destruct() method will not be called after this method.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the string representation of the object or NULL
Błędy/Wyjątki
Throws Exception when returning other types then strings and
NULL
Serializable::unserialize
(PHP 5 >= 5.1.0)
Serializable::unserialize — Constructs the object
Opis
$serialized
)Called during unserialization of the object.
Informacja:
This method acts as the constructor of the object. The __construct() method will not be called after this method.
Parametry
-
serialized -
The string representation of the object.
Zwracane wartości
The return value from this method is ignored.
Spis treści
- Serializable::serialize — String representation of object
- Serializable::unserialize — Constructs the object
The Closure class
(No version information available, might only be in SVN)
Wstęp
Class used to represent anonymous functions.
Anonymous functions, implemented in PHP 5.3, yield objects of this type. This fact used to be considered an implementation detail, but it can now be relied upon. Starting with PHP 5.4, this class has methods that allow further control of the anonymous function after it has been created.
Besides the methods listed here, this class also has an __invoke method. This is for consistency with other classes that implement calling magic, as this method is not used for calling the function.
Closure::__construct
(No version information available, might only be in SVN)
Closure::__construct — Constructor that disallows instantiation
Opis
This method exists only to disallow instantiation of the Closure class. Objects of this class are created in the fashion described on the anonymous functions page.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
This method has no return value; it simply emits an error
(of type E_RECOVERABLE_ERROR).
Zobacz też:
Closure::bind
(No version information available, might only be in SVN)
Closure::bind — Duplicates a closure with a specific bound object and class scope
Opis
$closure
, object $newthis
[, mixed $newscope
= 'static'
] )This method is a static version of Closure::bindTo(). See the documentation of that method for more information.
Parametry
-
closure -
The anonymous functions to bind.
-
newthis -
The object to which the given anonymous function should be bound, or
NULLfor the closure to be unbound. -
newscope -
The class scope to which associate the closure is to be associated, or 'static' to keep the current one. If an object is given, the type of the object will be used instead. This determines the visibility of protected and private methods of the bound object.
Zwracane wartości
Returns a new Closure object lub FALSE w przypadku niepowodzenia
Przykłady
Przykład #1 Closure::bind() example
<?php
class A {
private static $sfoo = 1;
private $ifoo = 2;
}
$cl1 = static function() {
return A::$sfoo;
};
$cl2 = function() {
return $this->ifoo;
};
$bcl1 = Closure::bind($cl1, null, 'A');
$bcl2 = Closure::bind($cl2, new A(), 'A');
echo $bcl1(), "\n";
echo $bcl2(), "\n";
?>
Powyższy przykład wyświetli coś podobnego do:
1 2
Zobacz też:
- Anonymous functions
- Closure::bindTo() - Duplicates the closure with a new bound object and class scope
Closure::bindTo
(No version information available, might only be in SVN)
Closure::bindTo — Duplicates the closure with a new bound object and class scope
Opis
Create and return a new anonymous function with the same body and bound variables as this one, but possibly with a different bound object and a new class scope.
The “bound object” determines the value $this will
have in the function body and the “class scope” represents a class
which determines which private and protected members the anonymous
function will be able to access. Namely, the members that will be
visible are the same as if the anonymous function were a method of
the class given as value of the newscope
parameter.
Static closures cannot have any bound object (the value of the parameter
newthis should be NULL), but this function can
nevertheless be used to change their class scope.
This function will ensure that for a non-static closure, having a bound
instance will imply being scoped and vice-versa. To this end,
non-static closures that are given a scope but a NULL instance are made
static and non-static non-scoped closures that are given a non-null
instance are scoped to an unspecified class.
Informacja:
If you only want to duplicate the anonymous functions, you can use cloning instead.
Parametry
-
newthis -
The object to which the given anonymous function should be bound, or
NULLfor the closure to be unbound. -
newscope -
The class scope to which associate the closure is to be associated, or 'static' to keep the current one. If an object is given, the type of the object will be used instead. This determines the visibility of protected and private methods of the bound object.
Zwracane wartości
Returns the newly created Closure object
lub FALSE w przypadku niepowodzenia
Przykłady
Przykład #1 Closure::bindTo() example
<?php
class A {
function __construct($val) {
$this->val = $val;
}
function getClosure() {
//returns closure bound to this object and scope
return function() { return $this->val; };
}
}
$ob1 = new A(1);
$ob2 = new A(2);
$cl = $ob1->getClosure();
echo $cl(), "\n";
$cl = $cl->bindTo($ob2);
echo $cl(), "\n";
?>
Powyższy przykład wyświetli coś podobnego do:
1 2
Zobacz też:
- Anonymous functions
- Closure::bind() - Duplicates a closure with a specific bound object and class scope
Spis treści
- Closure::__construct — Constructor that disallows instantiation
- Closure::bind — Duplicates a closure with a specific bound object and class scope
- Closure::bindTo — Duplicates the closure with a new bound object and class scope
Context options and parameters
PHP offers various context options and parameters which can be used with all filesystem and stream wrappers. The context is created with stream_context_create(). Options are set with stream_context_set_option() and parameters with stream_context_set_params().
Socket context options
Socket context options — Socket context option listing
Opis
Socket context options are available for all wrappers that work over sockets, like tcp, http and ftp.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.1.0 | Added bindto. |
| 5.3.3 | Added backlog. |
Przykłady
Przykład #1 Basic bindto usage example
<?php
// connect to the internet using the '192.168.0.100' IP
$opts = array(
'socket' => array(
'bindto' => '192.168.0.100:0',
),
);
// connect to the internet using the '192.168.0.100' IP and port '7000'
$opts = array(
'socket' => array(
'bindto' => '192.168.0.100:7000',
),
);
// connect to the internet using port '7000'
$opts = array(
'socket' => array(
'bindto' => '0:7000',
),
);
// create the context...
$context = stream_context_create($opts);
// ...and use it to fetch the data
echo file_get_contents('http://www.example.com', false, $context);
?>
HTTP context options
HTTP context options — HTTP context option listing
Opis
Context options for http:// and https:// transports.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.4 |
Added follow_location.
|
| 5.3.0 |
The protocol_version supports chunked transfer
decoding when set to 1.1.
|
| 5.2.10 |
Added ignore_errors.
|
| 5.2.10 |
The header can now be an numerically indexed array.
|
| 5.2.1 |
Added timeout.
|
| 5.1.0 | Added HTTPS proxying through HTTP proxies. |
| 5.1.0 |
Added max_redirects.
|
| 5.1.0 |
Added protocol_version.
|
Przykłady
Przykład #1 Fetch a page and send POST data
<?php
$postdata = http_build_query(
array(
'var1' => 'some content',
'var2' => 'doh'
)
);
$opts = array('http' =>
array(
'method' => 'POST',
'header' => 'Content-type: application/x-www-form-urlencoded',
'content' => $postdata
)
);
$context = stream_context_create($opts);
$result = file_get_contents('http://example.com/submit.php', false, $context);
?>
Przykład #2 Ignore redirects but fetch headers and content
<?php
$url = "http://www.example.org/header.php";
$opts = array('http' =>
array(
'method' => 'GET',
'max_redirects' => '0',
'ignore_errors' => '1'
)
);
$context = stream_context_create($opts);
$stream = fopen($url, 'r', false, $context);
// header information as well as meta data
// about the stream
var_dump(stream_get_meta_data($stream));
// actual data at $url
var_dump(stream_get_contents($stream));
fclose($stream);
?>
Notatki
Informacja: Underlying socket stream context options
Additional context options may be supported by the underlying transport For http:// streams, refer to context options for the tcp:// transport. For https:// streams, refer to context options for the ssl:// transport.
Informacja: HTTP status line
When this stream wrapper follows a redirect, the wrapper_data returned by stream_get_meta_data() might not necessarily contain the HTTP status line that actually applies to the content data at index 0.The first request returned a 301 (permanent redirect), so the stream wrapper automatically followed the redirect to get a 200 response (index = 4).array ( 'wrapper_data' => array ( 0 => 'HTTP/1.0 301 Moved Permantenly', 1 => 'Cache-Control: no-cache', 2 => 'Connection: close', 3 => 'Location: http://example.com/foo.jpg', 4 => 'HTTP/1.1 200 OK', ...
FTP context options
FTP context options — FTP context option listing
Opis
Context options for ftp:// and ftps:// transports.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.1.0 |
Added proxy.
|
| 5.0.0 |
Added overwrite and resume_pos.
|
Notatki
Informacja: Underlying socket stream context options
Additional context options may be supported by the underlying transport For ftp:// streams, refer to context options for the tcp:// transport. For ftps:// streams, refer to context options for the ssl:// transport.
SSL context options
SSL context options — SSL context option listing
Opis
Context options for ssl:// and tls:// transports.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.2 |
Added SNI_enabled and
SNI_server_name.
|
| 5.0.0 |
Added capture_peer_cert,
capture_peer_chain and
ciphers.
|
Notatki
Informacja: Because ssl:// is the underlying transport for the https:// and ftps:// wrappers, any context options which apply to ssl:// also apply to https:// and ftps://.
Informacja: For SNI (Server Name Indication) to be available, then PHP must be compiled with OpenSSL 0.9.8j or greater. Use the
OPENSSL_TLSEXT_SERVER_NAMEto determine whether SNI is supported.
CURL context options
CURL context options — CURL context option listing
Opis
CURL context options are available when the CURL extension was compiled using the --with-curlwrappers configure option.
Przykłady
Przykład #1 Fetch a page and send POST data
<?php
$postdata = http_build_query(
array(
'var1' => 'some content',
'var2' => 'doh'
)
);
$opts = array('http' =>
array(
'method' => 'POST',
'header' => 'Content-type: application/x-www-form-urlencoded',
'content' => $postdata
)
);
$context = stream_context_create($opts);
$result = file_get_contents('http://example.com/submit.php', false, $context);
?>
Phar context options
Phar context options — Phar context option listing
Opis
Context options for phar:// wrapper.
Context parameters
Context parameters — Context parameter listing
Opis
These parameters can be set on a context using the stream_context_set_params() function.
Spis treści
- Socket context options — Socket context option listing
- HTTP context options — HTTP context option listing
- FTP context options — FTP context option listing
- SSL context options — SSL context option listing
- CURL context options — CURL context option listing
- Phar context options — Phar context option listing
- Context parameters — Context parameter listing
Supported Protocols and Wrappers
PHP comes with many built-in wrappers for various URL-style protocols for use with the filesystem functions such as fopen(), copy(), file_exists() and filesize(). In addition to these wrappers, it is possible to register custom wrappers using the stream_wrapper_register() function.
Informacja: The URL syntax used to describe a wrapper only supports the scheme://... syntax. The scheme:/ and scheme: syntaxes are not supported.
file://
file:// — Accessing local filesystem
Opis
Filesystem is the default wrapper used with PHP and represents the local filesystem. When a relative path is specified (a path which does not begin with /, \, \\, or a Windows drive letter) the path provided will be applied against the current working directory. In many cases this is the directory in which the script resides unless it has been changed. Using the CLI sapi, this defaults to the directory from which the script was called.
With some functions, such as fopen() and file_get_contents(), include_path may be optionally searched for relative paths as well.
Opcje
- /path/to/file.ext
- relative/path/to/file.ext
- fileInCwd.ext
- C:/path/to/winfile.ext
- C:\path\to\winfile.ext
- \\smbserver\share\path\to\winfile.ext
- file:///path/to/file.ext
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.0.0 | Added file://. |
http://
https://
http:// -- https:// — Accessing HTTP(s) URLs
Opis
Allows read-only access to files/resources via HTTP 1.0, using the HTTP GET method. A Host: header is sent with the request to handle name-based virtual hosts. If you have configured a user_agent string using your php.ini file or the stream context, it will also be included in the request.
The stream allows access to the body of the resource; the headers are stored in the $http_response_header variable.
If it's important to know the URL of the resource where your document came from (after all redirects have been processed), you'll need to process the series of response headers returned by the stream.
The from directive will be used for the From: header if set and not overwritten by the Context options and parameters.
Opcje
- http://example.com
- http://example.com/file.php?var1=val1&var2=val2
- http://user:password@example.com
- https://example.com
- https://example.com/file.php?var1=val1&var2=val2
- https://user:password@example.com
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.3.7 | Detect buggy IIS servers to avoid "SSL: Fatal Protocol Error" errors. |
| 4.3.0 | Added https://. |
| 4.0.5 | Added support for redirects. |
Przykłady
Przykład #1 Detecting which URL we ended up on after redirects
<?php
$url = 'http://www.example.com/redirecting_page.php';
$fp = fopen($url, 'r');
$meta_data = stream_get_meta_data($fp);
foreach ($meta_data['wrapper_data'] as $response) {
/* Were we redirected? */
if (strtolower(substr($response, 0, 10)) == 'location: ') {
/* update $url with where we were redirected to */
$url = substr($response, 10);
}
}
?>
Przykład #2 Sending custom headers with an HTTP request
Custom headers may be sent using context options. It is also possible to use this hack: Custom headers may be sent with an HTTP request by taking advantage of a side-effect in the handling of the user_agent INI setting. Set user_agent to any valid string (such as the default PHP/version setting) followed by a carriage-return/line-feed pair and any additional headers.
<?php
ini_set('user_agent', "PHP\r\nX-MyCustomHeader: Foo");
$fp = fopen('http://www.example.com/index.php', 'r');
?>
Results in the following request being sent:
GET /index.php HTTP/1.0 Host: www.example.com User-Agent: PHP X-MyCustomHeader: Foo
Notatki
Informacja: HTTPS is only supported when the openssl extension is enabled.
HTTP connections are read-only; writing data or copying files to an HTTP resource is not supported.
Sending POST and PUT requests, for example, can be done with the help of HTTP Contexts.
Zobacz też:
- HTTP context options
- $http_response_header
- stream_get_meta_data() - Retrieves header/meta data from streams/file pointers
ftp://
ftps://
ftp:// -- ftps:// — Accessing FTP(s) URLs
Opis
Allows read access to existing files and creation of new files via FTP. If the server does not support passive mode ftp, the connection will fail.
You can open files for either reading or writing, but not both simultaneously. If the remote file already exists on the ftp server and you attempt to open it for writing but have not specified the context option overwrite, the connection will fail. If you need to overwrite existing files over ftp, specify the overwrite option in the context and open the file for writing. Alternatively, you can use the FTP extension.
If you have set the from directive in php.ini, then this value will be sent as the anonymous FTP password.
Opcje
- ftp://example.com/pub/file.txt
- ftp://user:password@example.com/pub/file.txt
- ftps://example.com/pub/file.txt
- ftps://user:password@example.com/pub/file.txt
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.3.0 | Added ftps://. |
Notatki
Informacja:
FTPS is only supported when the openssl extension is enabled.
If the server does not support SSL, then the connection falls back to regular unencrypted ftp.
Informacja: Appending
As of PHP 5.0.0 files may be appended via the ftp:// URL wrapper. In prior versions, attempting to append to a file via ftp:// will result in failure.
Zobacz też:
php://
php:// — Accessing various I/O streams
Opis
PHP provides a number of miscellaneous I/O streams that allow access to PHP's own input and output streams, the standard input, output and error file descriptors, in-memory and disk-backed temporary file streams, and filters that can manipulate other file resources as they are read from and written to.
php://stdin, php://stdout and php://stderr
php://stdin, php://stdout and
php://stderr allow direct access to the corresponding
input or output stream of the PHP process. The stream references a
duplicate file descriptor, so if you open php://stdin
and later close it, you close only your copy of the descriptor-the actual
stream referenced by STDIN is unaffected. Note that
PHP exhibited buggy behavior in this regard until PHP 5.2.1. It is
recommended that you simply use the constants STDIN,
STDOUT and STDERR instead of
manually opening streams using these wrappers.
php://stdin is read-only, whereas php://stdout and php://stderr are write-only.
php://input
php://input is a read-only stream that allows you to read raw data from the request body. In the case of POST requests, it is preferable to use php://input instead of $HTTP_RAW_POST_DATA as it does not depend on special php.ini directives. Moreover, for those cases where $HTTP_RAW_POST_DATA is not populated by default, it is a potentially less memory intensive alternative to activating always_populate_raw_post_data. php://input is not available with enctype="multipart/form-data".
Informacja: A stream opened with php://input can only be read once; the stream does not support seek operations. However, depending on the SAPI implementation, it may be possible to open another php://input stream and restart reading. This is only possible if the request body data has been saved. Typically, this is the case for POST requests, but not other request methods, such as PUT or PROPFIND.
php://output
php://output is a write-only stream that allows you to write to the output buffer mechanism in the same way as print() and echo().
php://fd
php://fd allows direct access to the given file descriptor. For example, php://fd/3 refers to file descriptor 3.
php://memory and php://temp
php://memory and php://temp are read-write streams that allow temporary data to be stored in a file-like wrapper. The only difference between the two is that php://memory will always store its data in memory, whereas php://temp will use a temporary file once the amount of data stored hits a predefined limit (the default is 2 MB). The location of this temporary file is determined in the same way as the sys_get_temp_dir() function.
The memory limit of php://temp can be controlled by appending /maxmemory:NN, where NN is the maximum amount of data to keep in memory before using a temporary file, in bytes.
php://filter
php://filter is a kind of meta-wrapper designed to permit the application of filters to a stream at the time of opening. This is useful with all-in-one file functions such as readfile(), file(), and file_get_contents() where there is otherwise no opportunity to apply a filter to the stream prior the contents being read.
The php://filter target takes the following parameters as part of its path. Please refer to the examples for specifics on using these parameters.
| Name | Description |
|---|---|
| resource=<stream to be filtered> | This parameter is required. It specifies the stream that you would like to filter. |
| read=<filter list to apply to read chain> | This parameter is optional. One or more filter names can be provided here, separated by the pipe character (|). |
| write=<filter list to apply to write chain> | This parameter is optional. One or more filter names can be provided here, separated by the pipe character (|). |
| <filter list to apply to both chains> | Any filter lists which are not prefixed by read= or write= will be applied to both the read and write chains as appropriate. |
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.6 | php://fd was added. |
| 5.1.0 | php://memory and php://temp were added. |
| 5.0.0 | php://filter was added. |
Przykłady
Przykład #1 php://temp/maxmemory
This optional parameter allows setting the memory limit before php://temp starts using a temporary file.
<?php
// Set the limit to 5 MB.
$fiveMBs = 5 * 1024 * 1024;
$fp = fopen("php://temp/maxmemory:$fiveMBs", 'r+');
fputs($fp, "hello\n");
// Read what we have written.
rewind($fp);
echo stream_get_contents($fp);
?>
Przykład #2 php://filter/resource=<stream to be filtered>
This parameter must be located at the end of your php://filter specification and should point to the stream which you want filtered.
<?php
/* This is equivalent to simply:
readfile("http://www.example.com");
since no filters are actually specified */
readfile("php://filter/resource=http://www.example.com");
?>
Przykład #3 php://filter/read=<filter list to apply to read chain>
This parameter takes one or more filternames separated by the pipe character |.
<?php
/* This will output the contents of
www.example.com entirely in uppercase */
readfile("php://filter/read=string.toupper/resource=http://www.example.com");
/* This will do the same as above
but will also ROT13 encode it */
readfile("php://filter/read=string.toupper|string.rot13/resource=http://www.example.com");
?>
Przykład #4 php://filter/write=<filter list to apply to write chain>
This parameter takes one or more filternames separated by the pipe character |.
<?php
/* This will filter the string "Hello World"
through the rot13 filter, then write to
example.txt in the current directory */
file_put_contents("php://filter/write=string.rot13/resource=example.txt","Hello World");
?>
zlib://
bzip2://
zip://
zlib:// -- bzip2:// -- zip:// — Compression Streams
Opis
zlib: PHP 4.0.4 - PHP 4.2.3 (systems with fopencookie only)
compress.zlib:// and compress.bzip2:// PHP 4.3.0 and up
zlib: works like gzopen(), except that the stream can be used with fread() and the other filesystem functions. This is deprecated as of PHP 4.3.0 due to ambiguities with filenames containing ':' characters; use compress.zlib:// instead.
compress.zlib:// and compress.bzip2:// are equivalent to gzopen() and bzopen() respectively, and operate even on systems that do not support fopencookie.
ZIP extension registers zip: wrapper.
Opcje
- zlib:
- compress.zlib://
- compress.bzip2://
data://
data:// — Data (RFC 2397)
Opis
The data: (» RFC 2397) stream wrapper is available since PHP 5.2.0.
Opcje
- data://text/plain;base64,
Przykłady
Przykład #1 Print data:// contents
<?php
// prints "I love PHP"
echo file_get_contents('data://text/plain;base64,SSBsb3ZlIFBIUAo=');
?>
Przykład #2 Fetch the media type
<?php
$fp = fopen('data://text/plain;base64,', 'r');
$meta = stream_get_meta_data($fp);
// prints "text/plain"
echo $meta['mediatype'];
?>
glob://
glob:// — Find pathnames matching pattern
Opis
The glob: stream wrapper is available since PHP 5.3.0.
Opcje
- glob://
Przykłady
Przykład #1 Basic usage
<?php
// Loop over all *.php files in ext/spl/examples/ directory
// and print the filename and its size
$it = new DirectoryIterator("glob://ext/spl/examples/*.php");
foreach($it as $f) {
printf("%s: %.1FK\n", $f->getFilename(), $f->getSize()/1024);
}
?>
tree.php: 1.0K findregex.php: 0.6K findfile.php: 0.7K dba_dump.php: 0.9K nocvsdir.php: 1.1K phar_from_dir.php: 1.0K ini_groups.php: 0.9K directorytree.php: 0.9K dba_array.php: 1.1K class_tree.php: 1.8K
phar://
phar:// — PHP Archive
Opis
The phar:// stream wrapper is available since PHP 5.3.0. See Phar stream wrapper for detailed description.
Opcje
- phar://
Zobacz też:
ssh2://
ssh2:// — Secure Shell 2
Opis
ssh2.shell:// ssh2.exec:// ssh2.tunnel:// ssh2.sftp:// ssh2.scp:// PHP 4.3.0 and up (PECL)
Informacja: This wrapper is not enabled by default
In order to use the ssh2.*:// wrappers you must install the » SSH2 extension available from » PECL.
In addition to accepting traditional URI login details, the ssh2 wrappers will also reuse open connections by passing the connection resource in the host portion of the URL.
Opcje
- ssh2.shell://user:pass@example.com:22/xterm
- ssh2.exec://user:pass@example.com:22/usr/local/bin/somecmd
- ssh2.tunnel://user:pass@example.com:22/192.168.0.1:14
- ssh2.sftp://user:pass@example.com:22/path/to/filename
Przykłady
Przykład #1 Opening a stream from an active connection
<?php
$session = ssh2_connect('example.com', 22);
ssh2_auth_pubkey_file($session, 'username', '/home/username/.ssh/id_rsa.pub',
'/home/username/.ssh/id_rsa', 'secret');
$stream = fopen("ssh2.tunnel://$session/remote.example.com:1234", 'r');
?>
rar://
rar:// — RAR
Opis
The wrapper takes the url encoded path to the RAR archive (relative or absolute), an optional asterik (*), an optional number sign (#) and an optional url encoded entry name, as stored in the archive. Specifying an entry name requires the number sign; a leading forward slash in the entry name is optional.
This wrapper can open both files and directories. When opening directories, the asterisk sign forces the directory entries names to be returned unencoded. If it's not specified, they will be returned url encoded – the reason for this is to allow the wrapper to be correctly used with built-in functionality like the RecursiveDirectoryIterator in the presence of file names that seem like url encoded data.
If the pound sign and the entry name part are not included, the root of the archive will be displayed. This differs from regular directories in that the resulting stream will not contain information such as the modification time, as the root directory is not stored in an individual entry in the archive. The usage of the wrapper with RecursiveDirectoryIterator requires the number sign to be included in the URL when accessing the root, so that the URLs of the children may be constructed correctly.
Informacja: This wrapper is not enabled by default
In order to use the rar:// wrapper, you must install the » rar extension available from » PECL.
rar:// Available since PECL rar 3.0.0
Opcje
- rar://<url encoded archive name>[*][#[<url encoded entry name>]]
Przykłady
Przykład #1 Traversing a RAR archive
<?php
class MyRecDirIt extends RecursiveDirectoryIterator {
function current() {
return rawurldecode($this->getSubPathName()) .
(is_dir(parent::current())?" [DIR]":"");
}
}
$f = "rar://" . rawurlencode(dirname(__FILE__)) .
DIRECTORY_SEPARATOR . 'dirs_and_extra_headers.rar#';
$it = new RecursiveTreeIterator(new MyRecDirIt($f));
foreach ($it as $s) {
echo $s, "\n";
}
?>
Powyższy przykład wyświetli coś podobnego do:
|-allow_everyone_ni [DIR]
|-file1.txt
|-file2_אּ.txt
|-with_streams.txt
\-אּ [DIR]
|-אּ\%2Fempty%2E [DIR]
| \-אּ\%2Fempty%2E\file7.txt
|-אּ\empty [DIR]
|-אּ\file3.txt
|-אּ\file4_אּ.txt
\-אּ\אּ_2 [DIR]
|-אּ\אּ_2\file5.txt
\-אּ\אּ_2\file6_אּ.txt
Przykład #2 Opening an encrypted file (header encryption)
<?php
$stream = fopen("rar://" .
rawurlencode(dirname(__FILE__)) . DIRECTORY_SEPARATOR .
'encrypted_headers.rar' . '#encfile1.txt', "r", false,
stream_context_create(
array(
'rar' =>
array(
'open_password' => 'samplepassword'
)
)
)
);
var_dump(stream_get_contents($stream));
/* creation and last access date is opt-in in WinRAR, hence most
* files don't have them */
var_dump(fstat($stream));
?>
Powyższy przykład wyświetli coś podobnego do:
string(26) "Encrypted file 1 contents."
Array
(
[0] => 0
[1] => 0
[2] => 33206
[3] => 1
[4] => 0
[5] => 0
[6] => 0
[7] => 26
[8] => 0
[9] => 1259550052
[10] => 0
[11] => -1
[12] => -1
[dev] => 0
[ino] => 0
[mode] => 33206
[nlink] => 1
[uid] => 0
[gid] => 0
[rdev] => 0
[size] => 26
[atime] => 0
[mtime] => 1259550052
[ctime] => 0
[blksize] => -1
[blocks] => -1
)
ogg://
ogg:// — Audio streams
Opis
Files opened for reading via the ogg:// wrapper
are treated as compressed audio encoded using the OGG/Vorbis codec.
Similarly, files opened for writing or appending via the
ogg:// wrapper are writen as compressed audio data.
stream_get_meta_data(), when used on an OGG/Vorbis
file opened for reading will return various details about the stream
including the vendor tag, any included
comments, the number of
channels, the sampling rate,
and the encoding rate range described by:
bitrate_lower, bitrate_upper,
bitrate_nominal, and bitrate_window.
ogg:// PHP 4.3.0 and up (PECL)
Informacja: This wrapper is not enabled by default
In order to use the ogg:// wrapper you must install the » OGG/Vorbis extension available from » PECL.
Opcje
- ogg://soundfile.ogg
- ogg:///path/to/soundfile.ogg
- ogg://http://www.example.com/path/to/soundstream.ogg
Przykłady
expect://
expect:// — Process Interaction Streams
Opis
Streams opened via the expect:// wrapper provide access to process'es stdio, stdout and stderr via PTY.
Informacja: This wrapper is not enabled by default
In order to use the expect:// wrapper you must install the » Expect extension available from » PECL.
expect:// PHP 4.3.0 and up (PECL)
Opcje
- expect://command
Przykłady
Spis treści
- file:// — Accessing local filesystem
- http:// — Accessing HTTP(s) URLs
- ftp:// — Accessing FTP(s) URLs
- php:// — Accessing various I/O streams
- zlib:// — Compression Streams
- data:// — Data (RFC 2397)
- glob:// — Find pathnames matching pattern
- phar:// — PHP Archive
- ssh2:// — Secure Shell 2
- rar:// — RAR
- ogg:// — Audio streams
- expect:// — Process Interaction Streams
- Podstawowa składnia
- Types
- Zmienne
- Stałe
- Wyrażenia
- Operators
- Control Structures
- Funkcje
- Classes and Objects
- Introduction
- The Basics
- Properties
- Class Constants
- Autoloading Classes
- Constructors and Destructors
- Visibility
- Object Inheritance
- Scope Resolution Operator (::)
- Static Keyword
- Class Abstraction
- Object Interfaces
- Traits
- Overloading
- Object Iteration
- Patterns
- Magic Methods
- Final Keyword
- Object Cloning
- Comparing Objects
- Type Hinting
- Late Static Bindings
- Objects and references
- Object Serialization
- OOP Changelog
- Namespaces
- Namespaces overview
- Defining namespaces
- Declaring sub-namespaces
- Defining multiple namespaces in the same file
- Using namespaces: Basics
- Namespaces and dynamic language features
- namespace keyword and __NAMESPACE__ constant
- Using namespaces: Aliasing/Importing
- Global space
- Using namespaces: fallback to global function/constant
- Name resolution rules
- FAQ: things you need to know about namespaces
- Exceptions
- Referencje
- Predefined Variables
- Superglobals — Superglobals are built-in variables that are always available in all scopes
- $GLOBALS — References all variables available in global scope
- $_SERVER — Server and execution environment information
- $_GET — HTTP GET variables
- $_POST — HTTP POST variables
- $_FILES — HTTP File Upload variables
- $_REQUEST — HTTP Request variables
- $_SESSION — Session variables
- $_ENV — Environment variables
- $_COOKIE — HTTP Cookies
- $php_errormsg — The previous error message
- $HTTP_RAW_POST_DATA — Raw POST data
- $http_response_header — HTTP response headers
- $argc — The number of arguments passed to script
- $argv — Array of arguments passed to script
- Predefined Exceptions
- Predefined Interfaces
- Traversable — The Traversable interface
- Iterator — The Iterator interface
- IteratorAggregate — The IteratorAggregate interface
- ArrayAccess — The ArrayAccess interface
- Serializable — The Serializable interface
- Closure — The Closure class
- Context options and parameters
- Socket context options — Socket context option listing
- HTTP context options — HTTP context option listing
- FTP context options — FTP context option listing
- SSL context options — SSL context option listing
- CURL context options — CURL context option listing
- Phar context options — Phar context option listing
- Context parameters — Context parameter listing
- Supported Protocols and Wrappers
- file:// — Accessing local filesystem
- http:// — Accessing HTTP(s) URLs
- ftp:// — Accessing FTP(s) URLs
- php:// — Accessing various I/O streams
- zlib:// — Compression Streams
- data:// — Data (RFC 2397)
- glob:// — Find pathnames matching pattern
- phar:// — PHP Archive
- ssh2:// — Secure Shell 2
- rar:// — RAR
- ogg:// — Audio streams
- expect:// — Process Interaction Streams
Bezpieczeństwo
Introduction
PHP is a powerful language and the interpreter, whether included in a web server as a module or executed as a separate CGI binary, is able to access files, execute commands and open network connections on the server. These properties make anything run on a web server insecure by default. PHP is designed specifically to be a more secure language for writing CGI programs than Perl or C, and with correct selection of compile-time and runtime configuration options, and proper coding practices, it can give you exactly the combination of freedom and security you need.
As there are many different ways of utilizing PHP, there are many configuration options controlling its behaviour. A large selection of options guarantees you can use PHP for a lot of purposes, but it also means there are combinations of these options and server configurations that result in an insecure setup.
The configuration flexibility of PHP is equally rivalled by the code flexibility. PHP can be used to build complete server applications, with all the power of a shell user, or it can be used for simple server-side includes with little risk in a tightly controlled environment. How you build that environment, and how secure it is, is largely up to the PHP developer.
This chapter starts with some general security advice, explains the different configuration option combinations and the situations they can be safely used, and describes different considerations in coding for different levels of security.
General considerations
A completely secure system is a virtual impossibility, so an approach often used in the security profession is one of balancing risk and usability. If every variable submitted by a user required two forms of biometric validation (such as a retinal scan and a fingerprint), you would have an extremely high level of accountability. It would also take half an hour to fill out a fairly complex form, which would tend to encourage users to find ways of bypassing the security.
The best security is often unobtrusive enough to suit the requirements without the user being prevented from accomplishing their work, or over-burdening the code author with excessive complexity. Indeed, some security attacks are merely exploits of this kind of overly built security, which tends to erode over time.
A phrase worth remembering: A system is only as good as the weakest link in a chain. If all transactions are heavily logged based on time, location, transaction type, etc. but the user is only verified based on a single cookie, the validity of tying the users to the transaction log is severely weakened.
When testing, keep in mind that you will not be able to test all possibilities for even the simplest of pages. The input you may expect will be completely unrelated to the input given by a disgruntled employee, a cracker with months of time on their hands, or a housecat walking across the keyboard. This is why it's best to look at the code from a logical perspective, to discern where unexpected data can be introduced, and then follow how it is modified, reduced, or amplified.
The Internet is filled with people trying to make a name for themselves by breaking your code, crashing your site, posting inappropriate content, and otherwise making your day interesting. It doesn't matter if you have a small or large site, you are a target by simply being online, by having a server that can be connected to. Many cracking programs do not discern by size, they simply trawl massive IP blocks looking for victims. Try not to become one.
Installed as CGI binary
Spis treści
- Possible attacks
- Case 1: only public files served
- Case 2: using cgi.force_redirect
- Case 3: setting doc_root or user_dir
- Case 4: PHP parser outside of web tree
Possible attacks
Using PHP as a CGI binary is an option for setups that for some reason do not wish to integrate PHP as a module into server software (like Apache), or will use PHP with different kinds of CGI wrappers to create safe chroot and setuid environments for scripts. This setup usually involves installing executable PHP binary to the web server cgi-bin directory. CERT advisory » CA-96.11 recommends against placing any interpreters into cgi-bin. Even if the PHP binary can be used as a standalone interpreter, PHP is designed to prevent the attacks this setup makes possible:
- Accessing system files: http://my.host/cgi-bin/php?/etc/passwd The query information in a URL after the question mark (?) is passed as command line arguments to the interpreter by the CGI interface. Usually interpreters open and execute the file specified as the first argument on the command line. When invoked as a CGI binary, PHP refuses to interpret the command line arguments.
- Accessing any web document on server: http://my.host/cgi-bin/php/secret/doc.html The path information part of the URL after the PHP binary name, /secret/doc.html is conventionally used to specify the name of the file to be opened and interpreted by the CGI program. Usually some web server configuration directives (Apache: Action) are used to redirect requests to documents like http://my.host/secret/script.php to the PHP interpreter. With this setup, the web server first checks the access permissions to the directory /secret, and after that creates the redirected request http://my.host/cgi-bin/php/secret/script.php. Unfortunately, if the request is originally given in this form, no access checks are made by web server for file /secret/script.php, but only for the /cgi-bin/php file. This way any user able to access /cgi-bin/php is able to access any protected document on the web server. In PHP, runtime configuration directives cgi.force_redirect, doc_root and user_dir can be used to prevent this attack, if the server document tree has any directories with access restrictions. See below for full the explanation of the different combinations.
Case 1: only public files served
If your server does not have any content that is not restricted by password or ip based access control, there is no need for these configuration options. If your web server does not allow you to do redirects, or the server does not have a way to communicate to the PHP binary that the request is a safely redirected request, you can specify the option --enable-force-cgi-redirect to the configure script. You still have to make sure your PHP scripts do not rely on one or another way of calling the script, neither by directly http://my.host/cgi-bin/php/dir/script.php nor by redirection http://my.host/dir/script.php.
Redirection can be configured in Apache by using AddHandler and Action directives (see below).
Case 2: using cgi.force_redirect
The configuration directive cgi.force_redirect prevents anyone from calling PHP directly with a URL like http://my.host/cgi-bin/php/secretdir/script.php. Instead, PHP will only parse in this mode if it has gone through a web server redirect rule. PHP older than 4.2.0 used --enable-force-cgi-redirect compile time option for this.
Usually the redirection in the Apache configuration is done with the following directives:
Action php-script /cgi-bin/php AddHandler php-script .php
This option has only been tested with the Apache web server, and relies on Apache to set the non-standard CGI environment variable REDIRECT_STATUS on redirected requests. If your web server does not support any way of telling if the request is direct or redirected, you cannot use this option and you must use one of the other ways of running the CGI version documented here.
Case 3: setting doc_root or user_dir
To include active content, like scripts and executables, in the web server document directories is sometimes considered an insecure practice. If, because of some configuration mistake, the scripts are not executed but displayed as regular HTML documents, this may result in leakage of intellectual property or security information like passwords. Therefore many sysadmins will prefer setting up another directory structure for scripts that are accessible only through the PHP CGI, and therefore always interpreted and not displayed as such.
Also if the method for making sure the requests are not redirected, as described in the previous section, is not available, it is necessary to set up a script doc_root that is different from web document root.
You can set the PHP script document root by the configuration
directive doc_root in the
configuration file, or
you can set the environment variable
PHP_DOCUMENT_ROOT. If it is set, the CGI
version of PHP will always construct the file name to open with this
doc_root and the path information in the
request, so you can be sure no script is executed outside this
directory (except for user_dir
below).
Another option usable here is user_dir. When user_dir is unset,
only thing controlling the opened file name is
doc_root. Opening a URL like http://my.host/~user/doc.php does not
result in opening a file under users home directory, but a file
called ~user/doc.php under
doc_root (yes, a directory name starting with a tilde
[~]).
If user_dir is set to for example public_php, a request like http://my.host/~user/doc.php will open a file called doc.php under the directory named public_php under the home directory of the user. If the home of the user is /home/user, the file executed is /home/user/public_php/doc.php.
user_dir expansion happens regardless of
the doc_root setting, so you can control
the document root and user directory access
separately.
Case 4: PHP parser outside of web tree
A very secure option is to put the PHP parser binary somewhere outside of the web tree of files. In /usr/local/bin, for example. The only real downside to this option is that you will now have to put a line similar to:
#!/usr/local/bin/php
To get PHP to handle PATH_INFO and PATH_TRANSLATED information correctly with this setup, the PHP parser should be compiled with the --enable-discard-path configure option.
Installed as an Apache module
When PHP is used as an Apache module it inherits Apache's user permissions (typically those of the "nobody" user). This has several impacts on security and authorization. For example, if you are using PHP to access a database, unless that database has built-in access control, you will have to make the database accessible to the "nobody" user. This means a malicious script could access and modify the database, even without a username and password. It's entirely possible that a web spider could stumble across a database administrator's web page, and drop all of your databases. You can protect against this with Apache authorization, or you can design your own access model using LDAP, .htaccess files, etc. and include that code as part of your PHP scripts.
Often, once security is established to the point where the PHP user (in this case, the apache user) has very little risk attached to it, it is discovered that PHP is now prevented from writing any files to user directories. Or perhaps it has been prevented from accessing or changing databases. It has equally been secured from writing good and bad files, or entering good and bad database transactions.
A frequent security mistake made at this point is to allow apache root permissions, or to escalate apache's abilities in some other way.
Escalating the Apache user's permissions to root is extremely dangerous and may compromise the entire system, so sudo'ing, chroot'ing, or otherwise running as root should not be considered by those who are not security professionals.
There are some simpler solutions. By using open_basedir you can control and restrict what directories are allowed to be used for PHP. You can also set up apache-only areas, to restrict all web based activity to non-user, or non-system, files.
Filesystem Security
Spis treści
PHP is subject to the security built into most server systems with respect to permissions on a file and directory basis. This allows you to control which files in the filesystem may be read. Care should be taken with any files which are world readable to ensure that they are safe for reading by all users who have access to that filesystem.
Since PHP was designed to allow user level access to the filesystem, it's entirely possible to write a PHP script that will allow you to read system files such as /etc/passwd, modify your ethernet connections, send massive printer jobs out, etc. This has some obvious implications, in that you need to ensure that the files that you read from and write to are the appropriate ones.
Consider the following script, where a user indicates that they'd like to delete a file in their home directory. This assumes a situation where a PHP web interface is regularly used for file management, so the Apache user is allowed to delete files in the user home directories.
Przykład #1 Poor variable checking leads to....
<?php
// remove a file from the user's home directory
$username = $_POST['user_submitted_name'];
$userfile = $_POST['user_submitted_filename'];
$homedir = "/home/$username";
unlink("$homedir/$userfile");
echo "The file has been deleted!";
?>
Przykład #2 ... A filesystem attack
<?php
// removes a file from anywhere on the hard drive that
// the PHP user has access to. If PHP has root access:
$username = $_POST['user_submitted_name']; // "../etc"
$userfile = $_POST['user_submitted_filename']; // "passwd"
$homedir = "/home/$username"; // "/home/../etc"
unlink("$homedir/$userfile"); // "/home/../etc/passwd"
echo "The file has been deleted!";
?>
- Only allow limited permissions to the PHP web user binary.
- Check all variables which are submitted.
Przykład #3 More secure file name checking
<?php
// removes a file from the hard drive that
// the PHP user has access to.
$username = $_SERVER['REMOTE_USER']; // using an authentication mechanisim
$userfile = basename($_POST['user_submitted_filename']);
$homedir = "/home/$username";
$filepath = "$homedir/$userfile";
if (file_exists($filepath) && unlink($filepath)) {
$logstring = "Deleted $filepath\n";
} else {
$logstring = "Failed to delete $filepath\n";
}
$fp = fopen("/home/logging/filedelete.log", "a");
fwrite($fp, $logstring);
fclose($fp);
echo htmlentities($logstring, ENT_QUOTES);
?>
Przykład #4 More secure file name checking
<?php
$username = $_SERVER['REMOTE_USER']; // using an authentication mechanisim
$userfile = $_POST['user_submitted_filename'];
$homedir = "/home/$username";
$filepath = "$homedir/$userfile";
if (!ctype_alnum($username) || !preg_match('/^(?:[a-z0-9_-]|\.(?!\.))+$/iD', $userfile)) {
die("Bad username/filename");
}
//etc...
?>
Depending on your operating system, there are a wide variety of files which you should be concerned about, including device entries (/dev/ or COM1), configuration files (/etc/ files and the .ini files), well known file storage areas (/home/, My Documents), etc. For this reason, it's usually easier to create a policy where you forbid everything except for what you explicitly allow.
Null bytes related issues
As PHP uses the underlying C functions for filesystem related operations, it may handle null bytes in a quite unexpected way. As null bytes denote the end of a string in C, strings containing them won't be considered entirely but rather only until a null byte occurs. The following example shows a vulnerable code that demonstrates this problem:
Przykład #1 Script vulnerable to null bytes
<?php
$file = $_GET['file']; // "../../etc/passwd\0"
if (file_exists('/home/wwwrun/'.$file.'.php')) {
// file_exists will return true as the file /home/wwwrun/../../etc/passwd exists
include '/home/wwwrun/'.$file.'.php';
// the file /etc/passwd will be included
}
?>
Therefore, any tainted string that is used in a filesystem operation should always be validated properly. Here is a better version of the previous example:
Przykład #2 Correctly validating the input
<?php
$file = $_GET['file'];
// Whitelisting possible values
switch ($file) {
case 'main':
case 'foo':
case 'bar':
include '/home/wwwrun/include/'.$file.'.php';
break;
default:
include '/home/wwwrun/include/main.php';
}
?>
Database Security
Spis treści
Nowadays, databases are cardinal components of any web based application by enabling websites to provide varying dynamic content. Since very sensitive or secret information can be stored in a database, you should strongly consider protecting your databases.
To retrieve or to store any information you need to connect to the database, send a legitimate query, fetch the result, and close the connection. Nowadays, the commonly used query language in this interaction is the Structured Query Language (SQL). See how an attacker can tamper with an SQL query.
As you can surmise, PHP cannot protect your database by itself. The following sections aim to be an introduction into the very basics of how to access and manipulate databases within PHP scripts.
Keep in mind this simple rule: defense in depth. The more places you take action to increase the protection of your database, the less probability of an attacker succeeding in exposing or abusing any stored information. Good design of the database schema and the application deals with your greatest fears.
Designing Databases
The first step is always to create the database, unless you want to use one from a third party. When a database is created, it is assigned to an owner, who executed the creation statement. Usually, only the owner (or a superuser) can do anything with the objects in that database, and in order to allow other users to use it, privileges must be granted.
Applications should never connect to the database as its owner or a superuser, because these users can execute any query at will, for example, modifying the schema (e.g. dropping tables) or deleting its entire content.
You may create different database users for every aspect of your application with very limited rights to database objects. The most required privileges should be granted only, and avoid that the same user can interact with the database in different use cases. This means that if intruders gain access to your database using your applications credentials, they can only effect as many changes as your application can.
You are encouraged not to implement all the business logic in the web application (i.e. your script), instead do it in the database schema using views, triggers or rules. If the system evolves, new ports will be intended to open to the database, and you have to re-implement the logic in each separate database client. Over and above, triggers can be used to transparently and automatically handle fields, which often provides insight when debugging problems with your application or tracing back transactions.
Connecting to Database
You may want to establish the connections over SSL to encrypt client/server communications for increased security, or you can use ssh to encrypt the network connection between clients and the database server. If either of these is used, then monitoring your traffic and gaining information about your database will be difficult for a would-be attacker.
Encrypted Storage Model
SSL/SSH protects data travelling from the client to the server: SSL/SSH does not protect persistent data stored in a database. SSL is an on-the-wire protocol.
Once an attacker gains access to your database directly (bypassing the webserver), stored sensitive data may be exposed or misused, unless the information is protected by the database itself. Encrypting the data is a good way to mitigate this threat, but very few databases offer this type of data encryption.
The easiest way to work around this problem is to first create your own encryption package, and then use it from within your PHP scripts. PHP can assist you in this with several extensions, such as Mcrypt and Mhash, covering a wide variety of encryption algorithms. The script encrypts the data before inserting it into the database, and decrypts it when retrieving. See the references for further examples of how encryption works.
In the case of truly hidden data, if its raw representation is not needed (i.e. will not be displayed), hashing may also be taken into consideration. The well-known example for hashing is storing the cryptographic hash of a password in a database, instead of the password itself. See also crypt().
Przykład #1 Using hashed password field
<?php
// storing password hash
$query = sprintf("INSERT INTO users(name,pwd) VALUES('%s','%s');",
pg_escape_string($username), crypt($password, '$2a$07$usesomesillystringforsalt$'));
$result = pg_query($connection, $query);
// querying if user submitted the right password
$query = sprintf("SELECT 1 FROM users WHERE name='%s' AND pwd='%s';",
pg_escape_string($username), crypt($password, '$2a$07$usesomesillystringforsalt$'));
$result = pg_query($connection, $query);
if (pg_num_rows($result) > 0) {
echo 'Welcome, $username!';
} else {
echo 'Authentication failed for $username.';
}
?>
SQL Injection
Many web developers are unaware of how SQL queries can be tampered with, and assume that an SQL query is a trusted command. It means that SQL queries are able to circumvent access controls, thereby bypassing standard authentication and authorization checks, and sometimes SQL queries even may allow access to host operating system level commands.
Direct SQL Command Injection is a technique where an attacker creates or alters existing SQL commands to expose hidden data, or to override valuable ones, or even to execute dangerous system level commands on the database host. This is accomplished by the application taking user input and combining it with static parameters to build an SQL query. The following examples are based on true stories, unfortunately.
Owing to the lack of input validation and connecting to the database on behalf of a superuser or the one who can create users, the attacker may create a superuser in your database.
Przykład #1 Splitting the result set into pages ... and making superusers (PostgreSQL)
<?php
$offset = $argv[0]; // beware, no input validation!
$query = "SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET $offset;";
$result = pg_query($conn, $query);
?>
0;
insert into pg_shadow(usename,usesysid,usesuper,usecatupd,passwd)
select 'crack', usesysid, 't','t','crack'
from pg_shadow where usename='postgres';
--
Informacja:
It is common technique to force the SQL parser to ignore the rest of the query written by the developer with -- which is the comment sign in SQL.
A feasible way to gain passwords is to circumvent your search result pages. The only thing the attacker needs to do is to see if there are any submitted variables used in SQL statements which are not handled properly. These filters can be set commonly in a preceding form to customize WHERE, ORDER BY, LIMIT and OFFSET clauses in SELECT statements. If your database supports the UNION construct, the attacker may try to append an entire query to the original one to list passwords from an arbitrary table. Using encrypted password fields is strongly encouraged.
Przykład #2 Listing out articles ... and some passwords (any database server)
<?php
$query = "SELECT id, name, inserted, size FROM products
WHERE size = '$size'
ORDER BY $order LIMIT $limit, $offset;";
$result = odbc_exec($conn, $query);
?>
' union select '1', concat(uname||'-'||passwd) as name, '1971-01-01', '0' from usertable; --
SQL UPDATE's are also susceptible to attack. These queries are also threatened by chopping and appending an entirely new query to it. But the attacker might fiddle with the SET clause. In this case some schema information must be possessed to manipulate the query successfully. This can be acquired by examining the form variable names, or just simply brute forcing. There are not so many naming conventions for fields storing passwords or usernames.
Przykład #3 From resetting a password ... to gaining more privileges (any database server)
<?php
$query = "UPDATE usertable SET pwd='$pwd' WHERE uid='$uid';";
?>
<?php
// $uid == ' or uid like'%admin%'; --
$query = "UPDATE usertable SET pwd='...' WHERE uid='' or uid like '%admin%'; --";
// $pwd == "hehehe', admin='yes', trusted=100 "
$query = "UPDATE usertable SET pwd='hehehe', admin='yes', trusted=100 WHERE
...;";
?>
A frightening example how operating system level commands can be accessed on some database hosts.
Przykład #4 Attacking the database hosts operating system (MSSQL Server)
<?php
$query = "SELECT * FROM products WHERE id LIKE '%$prod%'";
$result = mssql_query($query);
?>
<?php
$query = "SELECT * FROM products
WHERE id LIKE '%a%'
exec master..xp_cmdshell 'net user test testpass /ADD'--";
$result = mssql_query($query);
?>
Informacja:
Some of the examples above is tied to a specific database server. This does not mean that a similar attack is impossible against other products. Your database server may be similarly vulnerable in another manner.
Avoidance Techniques
While it remains obvious that an attacker must possess at least some knowledge of the database architecture in order to conduct a successful attack, obtaining this information is often very simple. For example, if the database is part of an open source or other publicly-available software package with a default installation, this information is completely open and available. This information may also be divulged by closed-source code - even if it's encoded, obfuscated, or compiled - and even by your very own code through the display of error messages. Other methods include the user of common table and column names. For example, a login form that uses a 'users' table with column names 'id', 'username', and 'password'.
These attacks are mainly based on exploiting the code not being written with security in mind. Never trust any kind of input, especially that which comes from the client side, even though it comes from a select box, a hidden input field or a cookie. The first example shows that such a blameless query can cause disasters.
- Never connect to the database as a superuser or as the database owner. Use always customized users with very limited privileges.
- Check if the given input has the expected data type. PHP has a wide range of input validating functions, from the simplest ones found in Variable Functions and in Character Type Functions (e.g. is_numeric(), ctype_digit() respectively) and onwards to the Perl compatible Regular Expressions support.
-
If the application waits for numerical input, consider verifying data with is_numeric(), or silently change its type using settype(), or use its numeric representation by sprintf().
Przykład #5 A more secure way to compose a query for paging
<?php
settype($offset, 'integer');
$query = "SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET $offset;";
// please note %d in the format string, using %s would be meaningless
$query = sprintf("SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET %d;",
$offset);
?> - Quote each non numeric user supplied value that is passed to the database with the database-specific string escape function (e.g. mysql_real_escape_string(), sqlite_escape_string(), etc.). If a database-specific string escape mechanism is not available, the addslashes() and str_replace() functions may be useful (depending on database type). See the first example. As the example shows, adding quotes to the static part of the query is not enough, making this query easily crackable.
- Do not print out any database specific information, especially about the schema, by fair means or foul. See also Error Reporting and Error Handling and Logging Functions.
- You may use stored procedures and previously defined cursors to abstract data access so that users do not directly access tables or views, but this solution has another impacts.
Besides these, you benefit from logging queries either within your script or by the database itself, if it supports logging. Obviously, the logging is unable to prevent any harmful attempt, but it can be helpful to trace back which application has been circumvented. The log is not useful by itself, but through the information it contains. More detail is generally better than less.
Error Reporting
With PHP security, there are two sides to error reporting. One is beneficial to increasing security, the other is detrimental.
A standard attack tactic involves profiling a system by feeding it improper data, and checking for the kinds, and contexts, of the errors which are returned. This allows the system cracker to probe for information about the server, to determine possible weaknesses. For example, if an attacker had gleaned information about a page based on a prior form submission, they may attempt to override variables, or modify them:
Przykład #1 Attacking Variables with a custom HTML page
<form method="post" action="attacktarget?username=badfoo&password=badfoo"> <input type="hidden" name="username" value="badfoo" /> <input type="hidden" name="password" value="badfoo" /> </form>
The PHP errors which are normally returned can be quite helpful to a developer who is trying to debug a script, indicating such things as the function or file that failed, the PHP file it failed in, and the line number which the failure occurred in. This is all information that can be exploited. It is not uncommon for a php developer to use show_source(), highlight_string(), or highlight_file() as a debugging measure, but in a live site, this can expose hidden variables, unchecked syntax, and other dangerous information. Especially dangerous is running code from known sources with built-in debugging handlers, or using common debugging techniques. If the attacker can determine what general technique you are using, they may try to brute-force a page, by sending various common debugging strings:
Przykład #2 Exploiting common debugging variables
<form method="post" action="attacktarget?errors=Y&showerrors=1&debug=1"> <input type="hidden" name="errors" value="Y" /> <input type="hidden" name="showerrors" value="1" /> <input type="hidden" name="debug" value="1" /> </form>
Regardless of the method of error handling, the ability to probe a system for errors leads to providing an attacker with more information.
For example, the very style of a generic PHP error indicates a system is running PHP. If the attacker was looking at an .html page, and wanted to probe for the back-end (to look for known weaknesses in the system), by feeding it the wrong data they may be able to determine that a system was built with PHP.
A function error can indicate whether a system may be running a specific database engine, or give clues as to how a web page or programmed or designed. This allows for deeper investigation into open database ports, or to look for specific bugs or weaknesses in a web page. By feeding different pieces of bad data, for example, an attacker can determine the order of authentication in a script, (from the line number errors) as well as probe for exploits that may be exploited in different locations in the script.
A filesystem or general PHP error can indicate what permissions the web server has, as well as the structure and organization of files on the web server. Developer written error code can aggravate this problem, leading to easy exploitation of formerly "hidden" information.
There are three major solutions to this issue. The first is to scrutinize all functions, and attempt to compensate for the bulk of the errors. The second is to disable error reporting entirely on the running code. The third is to use PHP's custom error handling functions to create your own error handler. Depending on your security policy, you may find all three to be applicable to your situation.
One way of catching this issue ahead of time is to make use of
PHP's own error_reporting(), to help you
secure your code and find variable usage that may be dangerous.
By testing your code, prior to deployment, with E_ALL,
you can quickly find areas where your variables may be open to poisoning
or modification in other ways. Once you are ready for deployment,
you should either disable error reporting completely by setting
error_reporting() to 0, or turn off the error
display using the php.ini option display_errors,
to insulate your code from probing. If you choose to do the latter,
you should also define the path to your log file using the
error_log ini directive, and turn
log_errors on.
Przykład #3 Finding dangerous variables with E_ALL
<?php
if ($username) { // Not initialized or checked before usage
$good_login = 1;
}
if ($good_login == 1) { // If above test fails, not initialized or checked before usage
readfile ("/highly/sensitive/data/index.html");
}
?>
Using Register Globals
This feature has been DEPRECATED as of PHP 5.3.0 and REMOVED as of PHP 5.4.0.
Perhaps the most controversial change in PHP is when the default value for the PHP directive register_globals went from ON to OFF in PHP » 4.2.0. Reliance on this directive was quite common and many people didn't even know it existed and assumed it's just how PHP works. This page will explain how one can write insecure code with this directive but keep in mind that the directive itself isn't insecure but rather it's the misuse of it.
When on, register_globals will inject your scripts with all sorts of variables, like request variables from HTML forms. This coupled with the fact that PHP doesn't require variable initialization means writing insecure code is that much easier. It was a difficult decision, but the PHP community decided to disable this directive by default. When on, people use variables yet really don't know for sure where they come from and can only assume. Internal variables that are defined in the script itself get mixed up with request data sent by users and disabling register_globals changes this. Let's demonstrate with an example misuse of register_globals:
Przykład #1 Example misuse with register_globals = on
<?php
// define $authorized = true only if user is authenticated
if (authenticated_user()) {
$authorized = true;
}
// Because we didn't first initialize $authorized as false, this might be
// defined through register_globals, like from GET auth.php?authorized=1
// So, anyone can be seen as authenticated!
if ($authorized) {
include "/highly/sensitive/data.php";
}
?>
When register_globals = on, our logic above may be compromised. When off, $authorized can't be set via request so it'll be fine, although it really is generally a good programming practice to initialize variables first. For example, in our example above we might have first done $authorized = false. Doing this first means our above code would work with register_globals on or off as users by default would be unauthorized.
Another example is that of sessions. When register_globals = on, we could also use $username in our example below but again you must realize that $username could also come from other means, such as GET (through the URL).
Przykład #2 Example use of sessions with register_globals on or off
<?php
// We wouldn't know where $username came from but do know $_SESSION is
// for session data
if (isset($_SESSION['username'])) {
echo "Hello <b>{$_SESSION['username']}</b>";
} else {
echo "Hello <b>Guest</b><br />";
echo "Would you like to login?";
}
?>
It's even possible to take preventative measures to warn when forging is being attempted. If you know ahead of time exactly where a variable should be coming from, you can check to see if the submitted data is coming from an inappropriate kind of submission. While it doesn't guarantee that data has not been forged, it does require an attacker to guess the right kind of forging. If you don't care where the request data comes from, you can use $_REQUEST as it contains a mix of GET, POST and COOKIE data. See also the manual section on using variables from external sources.
Przykład #3 Detecting simple variable poisoning
<?php
if (isset($_COOKIE['MAGIC_COOKIE'])) {
// MAGIC_COOKIE comes from a cookie.
// Be sure to validate the cookie data!
} elseif (isset($_GET['MAGIC_COOKIE']) || isset($_POST['MAGIC_COOKIE'])) {
mail("admin@example.com", "Possible breakin attempt", $_SERVER['REMOTE_ADDR']);
echo "Security violation, admin has been alerted.";
exit;
} else {
// MAGIC_COOKIE isn't set through this REQUEST
}
?>
Of course, simply turning off register_globals does not mean your code
is secure. For every piece of data that is submitted, it should also be
checked in other ways. Always validate your user data and initialize
your variables! To check for uninitialized variables you may turn up
error_reporting() to show
E_NOTICE level errors.
For information about emulating register_globals being On or Off, see this FAQ.
Informacja: Tablice superglobalne: informacja o dostępności
Tablice superglobalne, takie jak $_GET, $_POST, $_SERVER, itd. są dostępne od PHP 4.1.0. Aby uzyskać więcej informacji, należy zapoznać się z superglobals
User Submitted Data
The greatest weakness in many PHP programs is not inherent in the language itself, but merely an issue of code not being written with security in mind. For this reason, you should always take the time to consider the implications of a given piece of code, to ascertain the possible damage if an unexpected variable is submitted to it.
Przykład #1 Dangerous Variable Usage
<?php
// remove a file from the user's home directory... or maybe
// somebody else's?
unlink ($evil_var);
// Write logging of their access... or maybe an /etc/passwd entry?
fwrite ($fp, $evil_var);
// Execute something trivial.. or rm -rf *?
system ($evil_var);
exec ($evil_var);
?>
You should always carefully examine your code to make sure that any variables being submitted from a web browser are being properly checked, and ask yourself the following questions:
- Will this script only affect the intended files?
- Can unusual or undesirable data be acted upon?
- Can this script be used in unintended ways?
- Can this be used in conjunction with other scripts in a negative manner?
- Will any transactions be adequately logged?
By adequately asking these questions while writing the script, rather than later, you prevent an unfortunate re-write when you need to increase your security. By starting out with this mindset, you won't guarantee the security of your system, but you can help improve it.
You may also want to consider turning off register_globals, magic_quotes, or other convenience settings which may confuse you as to the validity, source, or value of a given variable. Working with PHP in error_reporting(E_ALL) mode can also help warn you about variables being used before they are checked or initialized (so you can prevent unusual data from being operated upon).
Magic Quotes
Spis treści
This feature has been DEPRECATED as of PHP 5.3.0 and REMOVED as of PHP 5.4.0.
Magic Quotes is a process that automagically escapes incoming data to the PHP script. It's preferred to code with magic quotes off and to instead escape the data at runtime, as needed.
What are Magic Quotes
This feature has been DEPRECATED as of PHP 5.3.0 and REMOVED as of PHP 5.4.0.
When on, all ' (single-quote), " (double quote), \ (backslash) and NULL characters are escaped with a backslash automatically. This is identical to what addslashes() does.
There are three magic quote directives:
- magic_quotes_gpc Affects HTTP Request data (GET, POST, and COOKIE). Cannot be set at runtime, and defaults to on in PHP. See also get_magic_quotes_gpc().
- magic_quotes_runtime If enabled, most functions that return data from an external source, including databases and text files, will have quotes escaped with a backslash. Can be set at runtime, and defaults to off in PHP. See also set_magic_quotes_runtime() and get_magic_quotes_runtime().
- magic_quotes_sybase If enabled, a single-quote is escaped with a single-quote instead of a backslash. If on, it completely overrides magic_quotes_gpc. Having both directives enabled means only single quotes are escaped as ''. Double quotes, backslashes and NULL's will remain untouched and unescaped. See also ini_get() for retrieving its value.
Why did we use Magic Quotes
This feature has been DEPRECATED as of PHP 5.3.0 and REMOVED as of PHP 5.4.0.
- There is no reason to use magic quotes because they are no longer a supported part of PHP. However, they did exist and did help a few beginners blissfully and unknowingly write better (more secure) code. But, when dealing with code that relies upon this behavior it's better to update the code instead of turning magic quotes on. So why did this feature exist? Simple, to help prevent SQL Injection. Today developers are better aware of security and end up using database specific escaping mechanisms and/or prepared statements instead of relying upon features like magical quotes.
Why not to use Magic Quotes
This feature has been DEPRECATED as of PHP 5.3.0 and REMOVED as of PHP 5.4.0.
- Portability Assuming it to be on, or off, affects portability. Use get_magic_quotes_gpc() to check for this, and code accordingly.
- Performance Because not every piece of escaped data is inserted into a database, there is a performance loss for escaping all this data. Simply calling on the escaping functions (like addslashes()) at runtime is more efficient. Although php.ini-development enables these directives by default, php.ini-production disables it. This recommendation is mainly due to performance reasons.
- Inconvenience Because not all data needs escaping, it's often annoying to see escaped data where it shouldn't be. For example, emailing from a form, and seeing a bunch of \' within the email. To fix, this may require excessive use of stripslashes().
Disabling Magic Quotes
The magic_quotes_gpc directive may only be disabled at the system level, and not at runtime. In otherwords, use of ini_set() is not an option.
Przykład #1 Disabling magic quotes server side
An example that sets the value of these directives to Off in php.ini. For additional details, read the manual section titled How to change configuration settings.
; Magic quotes ; ; Magic quotes for incoming GET/POST/Cookie data. magic_quotes_gpc = Off ; Magic quotes for runtime-generated data, e.g. data from SQL, from exec(), etc. magic_quotes_runtime = Off ; Use Sybase-style magic quotes (escape ' with '' instead of \'). magic_quotes_sybase = Off
If access to the server configuration is unavailable, use of .htaccess is also an option. For example:
php_flag magic_quotes_gpc Off
In the interest of writing portable code (code that works in any environment), like if setting at the server level is not possible, here's an example to disable magic_quotes_gpc at runtime. This method is inefficient so it's preferred to instead set the appropriate directives elsewhere.
Przykład #2 Disabling magic quotes at runtime
<?php
if (get_magic_quotes_gpc()) {
$process = array(&$_GET, &$_POST, &$_COOKIE, &$_REQUEST);
while (list($key, $val) = each($process)) {
foreach ($val as $k => $v) {
unset($process[$key][$k]);
if (is_array($v)) {
$process[$key][stripslashes($k)] = $v;
$process[] = &$process[$key][stripslashes($k)];
} else {
$process[$key][stripslashes($k)] = stripslashes($v);
}
}
}
unset($process);
}
?>
Hiding PHP
In general, security by obscurity is one of the weakest forms of security. But in some cases, every little bit of extra security is desirable.
A few simple techniques can help to hide PHP, possibly slowing down an attacker who is attempting to discover weaknesses in your system. By setting expose_php to off in your php.ini file, you reduce the amount of information available to them.
Another tactic is to configure web servers such as apache to parse different filetypes through PHP, either with an .htaccess directive, or in the apache configuration file itself. You can then use misleading file extensions:
Przykład #1 Hiding PHP as another language
# Make PHP code look like other code types AddType application/x-httpd-php .asp .py .pl
Przykład #2 Using unknown types for PHP extensions
# Make PHP code look like unknown types AddType application/x-httpd-php .bop .foo .133t
Przykład #3 Using HTML types for PHP extensions
# Make all PHP code look like HTML AddType application/x-httpd-php .htm .html
Keeping Current
PHP, like any other large system, is under constant scrutiny and improvement. Each new version will often include both major and minor changes to enhance security and repair any flaws, configuration mishaps, and other issues that will affect the overall security and stability of your system.
Like other system-level scripting languages and programs, the best approach is to update often, and maintain awareness of the latest versions and their changes.
Możliwości
Uwierzytelnianie HTTP w PHP
Możliwe jest używanie funkcji header() w celu wysłania do przeądarki komunikatu "Wymagana autoryzacja". To powoduje wyświetlenie okna z polami: użytkownik i hasło. Po wypełnieniu przez użytkownika tych pól, URL zawierający skrypt PHP zostanie ponownie wywołany z ustawionymi predefiniowanymi zmiennymi PHP_AUTH_USER, PHP_AUTH_PW i AUTH_TYPE zawierającymi odpowiednio nazwę użytkownika, hasło i typ autoryzacji. Zmienne te będą dostępne w tablicach $_SERVER oraz $HTTP_SERVER_VARS. Obecnie obsługiwane są autoryzacje typu "Basic" i "Digest" (od PHP 5.1.0). Więcej informacji można znaleć w opisie funkcji header().
Informacja: Notatka dotycząca wersji PHP
Zmienne superglobalne, takie jak $_SERVER, udostępniono w PHP » 4.1.0.
Przykładowy skrypt wymuszający autoryzację klienta:
Przykład #1 Uwierzytelnianie Basic HTTP
<?php
if (!isset($_SERVER['PHP_AUTH_USER'])) {
header('WWW-Authenticate: Basic realm="My Realm"');
header('HTTP/1.0 401 Unauthorized');
echo 'Tekst do wysłania, jeśli użytkownik wciśnie przycisk Anuluj';
exit;
} else {
echo "<p>Hej {$_SERVER['PHP_AUTH_USER']}.</p>";
echo "<p>Twoje hasło to {$_SERVER['PHP_AUTH_PW']}.</p>";
}
?>
Przykład #2 Przykład uwierzytelnianie Digest HTTP
Ten przykład pokazuje jak zaimplementować proste umierzytelnianie Digest HTTP. Więcej informacji znajduje się w dokumencie » RFC 2617.
<?php
$realm = 'Zastrzeżona strefa';
//user => password
$users = array('admin' => 'mypass', 'guest' => 'guest');
if (empty($_SERVER['PHP_AUTH_DIGEST'])) {
header('HTTP/1.1 401 Unauthorized');
header('WWW-Authenticate: Digest realm="'.$realm.
'",qop="auth",nonce="'.uniqid().'",opaque="'.md5($realm).'"');
die('Tekst do wysłania kiedy użytkownik kliknie klawisz anuluj');
}
// analiza zmiennej PHP_AUTH_DIGEST
if (!($data = http_digest_parse($_SERVER['PHP_AUTH_DIGEST'])) ||
!isset($users[$data['username']]))
die('Nieprawidłowe listy uwierzytelniające!');
// tworzenie prawidłowej odpowiedzi
$A1 = md5($data['username'] . ':' . $realm . ':' . $users[$data['username']]);
$A2 = md5($_SERVER['REQUEST_METHOD'].':'.$data['uri']);
$valid_response = md5($A1.':'.$data['nonce'].':'.$data['nc'].':'.$data['cnonce'].':'.$data['qop'].':'.$A2);
if ($data['response'] != $valid_response)
die('Nieprawidłowe listy uwierzytelniające!');
// ok, prawidłowa nazwa użytkownika i hasło
echo 'Jesteś zalogowany jako: ' . $data['username'];
// function to parse the http auth header
function http_digest_parse($txt)
{
// zabezpieczenie przeciwko brakującym informacjom
$needed_parts = array('nonce'=>1, 'nc'=>1, 'cnonce'=>1, 'qop'=>1, 'username'=>1, 'uri'=>1, 'response'=>1);
$data = array();
$keys = implode('|', array_keys($needed_parts));
preg_match_all('@(\w+)=(?:([\'"])([^\2]+)\2|([^\s,]+))@', $txt, $matches, PREG_SET_ORDER);
foreach ($matches as $m) {
$data[$m[1]] = $m[3] ? $m[3] : $m[4];
unset($needed_parts[$m[1]]);
}
return $needed_parts ? false : $data;
}
?>
Informacja: Kompatybilność
Należy uważać z linijkami dodawanymi do nagłówka HTTP. W celu zachowania maksymalnej zgodności ze wszystkimi klientami, słowo Basic powinno zaczynać się dużą literą "B", wartość realm powinna być otoczona cudzysłowami (nie apostrofami), i dokładnie jeden znak odstępu powinien poprzedzać kod 401 w linii HTTP/1.0 401. Parametry autoryzacyjne muszą być oddzielone przecinkami jak pokazano to w przykładzie digest powyżej.
Zamiast wyświetlać wartość PHP_AUTH_USER i PHP_AUTH_PW, jak to zrobiono w powyższym przykładzie, zechcesz zapewne sprawdzić poprawność nazwy użytkownika i hasła. Na przykład poprzez zapytanie do bazy danych lub odnalezienie użytkownika w pliku dbm.
Należy uważać na kapryśne przeglądarki Internet Explorer. Są wrażliwe na kolejność wysyłanych nagłówków HTTP. Wysłanie nagłowka WWW-Authenticate przed HTTP/1.0 401 powinno rozwiązać problem.
Od PHP 4.3.0, aby zapobiec sytuacji w której ktoś napisze skrypt wykradający hasło wysłane tradycyjnym zewnętrznym mechanizmem, zmienne PHP_AUTH nie będą ustawiane, jeśli dla danej strony aktywna jest autoryzacja zewnętrzna i tryb bezpieczny jest włączony. Bez względu na to, REMOTE_USER może zostać użyte do zidentyfikowania użytkownika autoryzowanego zewnętrznie Zatem, możesz użyć $_SERVER['REMOTE_USER'].
Informacja: Konfiguracja
Aby wykryć czy miała miejsce zewnętrzna autoryzacja, PHP sprwadza obecność dyrektywy AuthType.
Powyższa metoda nie zapobiega jednak wykradaniu haseł do stron wymagających autoryzacji przez kogoś, kto na tym samym serwerze kontroluje strony nie wymagające autoryzacji.
Zarówno Netscape Navigator jak i Internet Explorer opróżnią bufor autoryzacji po otrzymaniu od serwera kodu 401. Można w ten sposób wylogowanić użytkownika i zmusić go do ponownego wysłania nazwy użytkownika i hasła. Tej metody można użyć do wylogowania użytkownika po określonym czasie lub stworzenia przycisku "Wyloguj".
Przykład #3 Uwierzytelnianie HTTP z wymuszeniem przelogowania
<?php
function authenticate() {
header('WWW-Authenticate: Basic realm="Testowy system autoryzacji"');
header('HTTP/1.0 401 Unauthorized');
echo "Musisz podać poprawny login i hasło by wejść na tę stronę\n";
exit;
}
if (!isset($_SERVER['PHP_AUTH_USER']) ||
($_POST['SeenBefore'] == 1 && $_POST['OldAuth'] == $_SERVER['PHP_AUTH_USER'])) {
authenticate();
} else {
echo "<p>Witaj: " . htmlspecialchars($_SERVER['PHP_AUTH_USER']) . "<br />";
echo "Poprzednio: " . htmlspecialchars($_REQUEST['OldAuth']);
echo "<form action='' method='post'>\n";
echo "<input type='hidden' name='SeenBefore' value='1' />\n";
echo "<input type='hidden' name='OldAuth' value=\"" . htmlspecialchars($_SERVER['PHP_AUTH_USER']) . "\" />\n";
echo "<input type='submit' value='Re Authenticate' />\n";
echo "</form></p>\n";
}
?>
Powyższa metoda nie jest wymagana przez autoryzację HTTP Basic, więc nie można na niej polegać. Testy z przeglądarką Lynx pokazały, że Lynx nie usuwa danych o autoryzacji po odebraniu od serwera kodu 401, zatem przejście wstecz a następnie do przodu otworzy stronę, chyba, że wymagania co do danych autoryzacji zmieniły się. Użytkownik może jednak użyć klawisza '_' by usunąc dane o autoryzacji.
Zwóć uwagę, że do wersji PHP 4.3.3, Autoryzacja HTTP nie działała na serwerze Microsoft IIS z PHP w wersji CGI z powodu ograniczeń IIS. Aby zmusić go do działania w PHP 4.3.3+ musisz wyedytować "Bezpieczeństwo katalogów" w konfiguracji IIS. Kliknij na "Edytuj" i zaznacz wyłącznie "Anonimowy Dostęp", wszystkie inne pola powinny pozostać nie zaznaczone.
Inne ogranicznie jest jeśli używasz modułu IIS (ISAPI) i PHP 4, nie możesz wtedy użyć zmiennych PHP_AUTH_* ale zamiast nich, dostępna jest zmienna HTTP_AUTHORIZATION. Na przykład rozważ następujący kod: list($user, $pw) = explode(':', base64_decode(substr($_SERVER['HTTP_AUTHORIZATION'], 6)));
Informacja: Notatka IIS:
Aby Autoryzacja HTTP działała z IIS, dyrektywa PHP cgi.rfc2616_headers musi być ustawiona na 0 (domyślna wartość).
Informacja:
Jeśli włączony jest tryb bezpieczny, uid skryptu jest doklejany do pola realm nagłówka WWW-Authenticate.
Sessions
Session support in PHP consists of a way to preserve certain data across subsequent accesses. This enables you to build more customized applications and increase the appeal of your web site. All information is in the Session reference section.
Dealing with XForms
» XForms defines a variation on traditional webforms which allows them to be used on a wider variety of platforms and browsers or even non-traditional media such as PDF documents.
The first key difference in XForms is how the form is sent to the client. » XForms for HTML Authors contains a detailed description of how to create XForms, for the purpose of this tutorial we'll only be looking at a simple example.
Przykład #1 A simple XForms search form
<h:html xmlns:h="http://www.w3.org/1999/xhtml"
xmlns="http://www.w3.org/2002/xforms">
<h:head>
<h:title>Search</h:title>
<model>
<submission action="http://example.com/search"
method="post" id="s"/>
</model>
</h:head>
<h:body>
<h:p>
<input ref="q"><label>Find</label></input>
<submit submission="s"><label>Go</label></submit>
</h:p>
</h:body>
</h:html>
The above form displays a text input box (named q),
and a submit button. When the submit button is clicked, the form will be
sent to the page referred to by action.
Here's where it starts to look different from your web application's point of view. In a normal HTML form, the data would be sent as application/x-www-form-urlencoded, in the XForms world however, this information is sent as XML formatted data.
If you're choosing to work with XForms then you probably want that data as XML, in that case, look in $HTTP_RAW_POST_DATA where you'll find the XML document generated by the browser which you can pass into your favorite XSLT engine or document parser.
If you're not interested in formatting and just want your data to be loaded
into the traditional $_POST variable, you can instruct
the client browser to send it as application/x-www-form-urlencoded
by changing the method attribute to
urlencoded-post.
Przykład #2 Using an XForm to populate $_POST
<h:html xmlns:h="http://www.w3.org/1999/xhtml"
xmlns="http://www.w3.org/2002/xforms">
<h:head>
<h:title>Search</h:title>
<model>
<submission action="http://example.com/search"
method="urlencoded-post" id="s"/>
</model>
</h:head>
<h:body>
<h:p>
<input ref="q"><label>Find</label></input>
<submit submission="s"><label>Go</label></submit>
</h:p>
</h:body>
</h:html>
Informacja: As of this writing, many browsers do not support XForms. Check your browser version if the above examples fails.
Handling file uploads
Spis treści
- POST method uploads
- Error Messages Explained
- Common Pitfalls
- Uploading multiple files
- PUT method support
POST method uploads
This feature lets people upload both text and binary files. With PHP's authentication and file manipulation functions, you have full control over who is allowed to upload and what is to be done with the file once it has been uploaded.
PHP is capable of receiving file uploads from any RFC-1867 compliant browser.
Informacja: Related Configurations Note
See also the file_uploads, upload_max_filesize, upload_tmp_dir, post_max_size and max_input_time directives in php.ini
PHP also supports PUT-method file uploads as used by Netscape Composer and W3C's Amaya clients. See the PUT Method Support for more details.
Przykład #1 File Upload Form
A file upload screen can be built by creating a special form which looks something like this:
<!-- The data encoding type, enctype, MUST be specified as below -->
<form enctype="multipart/form-data" action="__URL__" method="POST">
<!-- MAX_FILE_SIZE must precede the file input field -->
<input type="hidden" name="MAX_FILE_SIZE" value="30000" />
<!-- Name of input element determines name in $_FILES array -->
Send this file: <input name="userfile" type="file" />
<input type="submit" value="Send File" />
</form>
The __URL__ in the above example should be replaced, and point to a PHP file.
The MAX_FILE_SIZE hidden field (measured in bytes) must precede the file input field, and its value is the maximum filesize accepted by PHP. This form element should always be used as it saves users the trouble of waiting for a big file being transferred only to find that it was too large and the transfer failed. Keep in mind: fooling this setting on the browser side is quite easy, so never rely on files with a greater size being blocked by this feature. It is merely a convenience feature for users on the client side of the application. The PHP settings (on the server side) for maximum-size, however, cannot be fooled.
Informacja:
Be sure your file upload form has attribute enctype="multipart/form-data" otherwise the file upload will not work.
The global $_FILES exists as of PHP 4.1.0 (Use $HTTP_POST_FILES instead if using an earlier version). These arrays will contain all the uploaded file information.
The contents of $_FILES from the example form is as follows. Note that this assumes the use of the file upload name userfile, as used in the example script above. This can be any name.
- $_FILES['userfile']['name']
-
The original name of the file on the client machine.
- $_FILES['userfile']['type']
-
The mime type of the file, if the browser provided this information. An example would be "image/gif". This mime type is however not checked on the PHP side and therefore don't take its value for granted.
- $_FILES['userfile']['size']
-
The size, in bytes, of the uploaded file.
- $_FILES['userfile']['tmp_name']
-
The temporary filename of the file in which the uploaded file was stored on the server.
- $_FILES['userfile']['error']
-
The error code associated with this file upload. This element was added in PHP 4.2.0
Files will, by default be stored in the server's default temporary directory, unless another location has been given with the upload_tmp_dir directive in php.ini. The server's default directory can be changed by setting the environment variable TMPDIR in the environment in which PHP runs. Setting it using putenv() from within a PHP script will not work. This environment variable can also be used to make sure that other operations are working on uploaded files, as well.
Przykład #2 Validating file uploads
See also the function entries for is_uploaded_file() and move_uploaded_file() for further information. The following example will process the file upload that came from a form.
<?php
// In PHP versions earlier than 4.1.0, $HTTP_POST_FILES should be used instead
// of $_FILES.
$uploaddir = '/var/www/uploads/';
$uploadfile = $uploaddir . basename($_FILES['userfile']['name']);
echo '<pre>';
if (move_uploaded_file($_FILES['userfile']['tmp_name'], $uploadfile)) {
echo "File is valid, and was successfully uploaded.\n";
} else {
echo "Possible file upload attack!\n";
}
echo 'Here is some more debugging info:';
print_r($_FILES);
print "</pre>";
?>
The PHP script which receives the uploaded file should implement whatever logic is necessary for determining what should be done with the uploaded file. You can, for example, use the $_FILES['userfile']['size'] variable to throw away any files that are either too small or too big. You could use the $_FILES['userfile']['type'] variable to throw away any files that didn't match a certain type criteria, but use this only as first of a series of checks, because this value is completely under the control of the client and not checked on the PHP side. As of PHP 4.2.0, you could use $_FILES['userfile']['error'] and plan your logic according to the error codes. Whatever the logic, you should either delete the file from the temporary directory or move it elsewhere.
If no file is selected for upload in your form, PHP will return $_FILES['userfile']['size'] as 0, and $_FILES['userfile']['tmp_name'] as none.
The file will be deleted from the temporary directory at the end of the request if it has not been moved away or renamed.
Przykład #3 Uploading array of files
PHP supports HTML array feature even with files.
<form action="" method="post" enctype="multipart/form-data"> <p>Pictures: <input type="file" name="pictures[]" /> <input type="file" name="pictures[]" /> <input type="file" name="pictures[]" /> <input type="submit" value="Send" /> </p> </form>
<?php
foreach ($_FILES["pictures"]["error"] as $key => $error) {
if ($error == UPLOAD_ERR_OK) {
$tmp_name = $_FILES["pictures"]["tmp_name"][$key];
$name = $_FILES["pictures"]["name"][$key];
move_uploaded_file($tmp_name, "data/$name");
}
}
?>
File upload progress bar can be implemented using Session Upload Progress.
Error Messages Explained
Since PHP 4.2.0, PHP returns an appropriate error code along with the file array. The error code can be found in the error segment of the file array that is created during the file upload by PHP. In other words, the error might be found in $_FILES['userfile']['error'].
-
UPLOAD_ERR_OK -
Value: 0; There is no error, the file uploaded with success.
-
UPLOAD_ERR_INI_SIZE -
Value: 1; The uploaded file exceeds the upload_max_filesize directive in php.ini.
-
UPLOAD_ERR_FORM_SIZE -
Value: 2; The uploaded file exceeds the MAX_FILE_SIZE directive that was specified in the HTML form.
-
UPLOAD_ERR_PARTIAL -
Value: 3; The uploaded file was only partially uploaded.
-
UPLOAD_ERR_NO_FILE -
Value: 4; No file was uploaded.
-
UPLOAD_ERR_NO_TMP_DIR -
Value: 6; Missing a temporary folder. Introduced in PHP 4.3.10 and PHP 5.0.3.
-
UPLOAD_ERR_CANT_WRITE -
Value: 7; Failed to write file to disk. Introduced in PHP 5.1.0.
-
UPLOAD_ERR_EXTENSION -
Value: 8; A PHP extension stopped the file upload. PHP does not provide a way to ascertain which extension caused the file upload to stop; examining the list of loaded extensions with phpinfo() may help. Introduced in PHP 5.2.0.
Informacja:
These became PHP constants in PHP 4.3.0.
Common Pitfalls
The MAX_FILE_SIZE item cannot specify a file size greater than the file size that has been set in the upload_max_filesize in the php.ini file. The default is 2 megabytes.
If a memory limit is enabled, a larger memory_limit may be needed. Make sure you set memory_limit large enough.
If max_execution_time is set too small, script execution may be exceeded by the value. Make sure you set max_execution_time large enough.
Informacja: max_execution_time only affects the execution time of the script itself. Any time spent on activity that happens outside the execution of the script such as system calls using system(), the sleep() function, database queries, time taken by the file upload process, etc. is not included when determining the maximum time that the script has been running.
max_input_time sets the maximum time, in seconds, the script is allowed to receive input; this includes file uploads. For large or multiple files, or users on slower connections, the default of 60 seconds may be exceeded.
If post_max_size is set too small, large files cannot be uploaded. Make sure you set post_max_size large enough.
Since PHP 5.2.12, the max_file_uploads configuration setting controls the maximum number of files that can uploaded in one request. If more files are uploaded than the limit, then $_FILES will stop processing files once the limit is reached. For example, if max_file_uploads is set to 10, then $_FILES will never contain more than 10 items.
Not validating which file you operate on may mean that users can access sensitive information in other directories.
Please note that the CERN httpd seems to strip off everything starting at the first whitespace in the content-type mime header it gets from the client. As long as this is the case, CERN httpd will not support the file upload feature.
Due to the large amount of directory listing styles we cannot guarantee that files with exotic names (like containing spaces) are handled properly.
A developer may not mix normal input fields and file upload fields in the same form variable (by using an input name like foo[]).
Uploading multiple files
Multiple files can be uploaded using different name for input.
It is also possible to upload multiple files simultaneously and have the information organized automatically in arrays for you. To do so, you need to use the same array submission syntax in the HTML form as you do with multiple selects and checkboxes:
Przykład #1 Uploading multiple files
<form action="file-upload.php" method="post" enctype="multipart/form-data"> Send these files:<br /> <input name="userfile[]" type="file" /><br /> <input name="userfile[]" type="file" /><br /> <input type="submit" value="Send files" /> </form>
When the above form is submitted, the arrays $_FILES['userfile'], $_FILES['userfile']['name'], and $_FILES['userfile']['size'] will be initialized (as well as in $HTTP_POST_FILES for PHP versions prior to 4.1.0). When register_globals is on, globals for uploaded files are also initialized. Each of these will be a numerically indexed array of the appropriate values for the submitted files.
For instance, assume that the filenames /home/test/review.html and /home/test/xwp.out are submitted. In this case, $_FILES['userfile']['name'][0] would contain the value review.html, and $_FILES['userfile']['name'][1] would contain the value xwp.out. Similarly, $_FILES['userfile']['size'][0] would contain review.html's file size, and so forth.
$_FILES['userfile']['name'][0], $_FILES['userfile']['tmp_name'][0], $_FILES['userfile']['size'][0], and $_FILES['userfile']['type'][0] are also set.
Since PHP 5.2.12, the max_file_uploads configuration setting acts as a limit on the number of files that can be uploaded in one request. You will need to ensure that your form does not try to upload more files in one request than this limit.
PUT method support
PHP provides support for the HTTP PUT method used by some clients to store files on a server. PUT requests are much simpler than a file upload using POST requests and they look something like this:
PUT /path/filename.html HTTP/1.1
This would normally mean that the remote client would like to save the content that follows as: /path/filename.html in your web tree. It is obviously not a good idea for Apache or PHP to automatically let everybody overwrite any files in your web tree. So, to handle such a request you have to first tell your web server that you want a certain PHP script to handle the request. In Apache you do this with the Script directive. It can be placed almost anywhere in your Apache configuration file. A common place is inside a <Directory> block or perhaps inside a <VirtualHost> block. A line like this would do the trick:
Script PUT /put.php
This tells Apache to send all PUT requests for URIs that match the context in which you put this line to the put.php script. This assumes, of course, that you have PHP enabled for the .php extension and PHP is active. The destination resource for all PUT requests to this script has to be the script itself, not a filename the uploaded file should have.
With PHP you would then do something like the following in your put.php. This would copy the contents of the uploaded file to the file myputfile.ext on the server. You would probably want to perform some checks and/or authenticate the user before performing this file copy.
Przykład #1 Saving HTTP PUT files
<?php
/* PUT data comes in on the stdin stream */
$putdata = fopen("php://input", "r");
/* Open a file for writing */
$fp = fopen("myputfile.ext", "w");
/* Read the data 1 KB at a time
and write to the file */
while ($data = fread($putdata, 1024))
fwrite($fp, $data);
/* Close the streams */
fclose($fp);
fclose($putdata);
?>
Korzystanie ze zdalnych plików
Jeśli parametr allow_url_fopen w pliku php.ini zostanie włączony, będzie można używać adresów HTTP i FTP w większości funkcji, które jako parametr przyjmują nazwę pliku, włączając w to instrukcje include(), include_once(), require() oraz require_once() (od PHP 5.2.0, musi być włączona opcja allow_url_include ). Więcej informacji o protokołach obsługiwanych przez PHP znajduje się w Supported Protocols and Wrappers.
Informacja:
W PHP 4.0.3 i starszych, aby używać opakowań URL, należy skonfigurowć PHP z opcją --enable-url-fopen-wrapper .
Informacja:
PHP dla Windows, w wersji wcześniejszej niż 4.3 nie obsługiwało zdalnego dostępu do plików przy użyciu instrukcji: include(), include_once(), require() i require_once() oraz rodziny funkcji imagecreatefromXXX z rozszerzenia GD and Image Funkcje.
Możesz wykorzystać tę własność aby otworzyć plik na zdalnym serwrze, przetworzyć jego zawartość i użyć wyników w zapytaniu do bazy danych, lub po prostu wyświetlić plik dostosowując jego wygląd do swojej strony.
Przykład #1 Pobieranie tytułu zdalnej strony
<?php
$file = fopen ("http://www.example.com/", "r");
if (!$file) {
echo "<p>Nie można otworzyć zdalnego pliku.\n";
exit;
}
while (!feof ($file)) {
$line = fgets ($file, 1024);
/* Zadziała tylko wtedy, gdy tytuł i jego znaczniki są w tej samej linii */
if (preg_match ("@\<title\>(.*)\</title\>@i", $line, $out)) {
$title = $out[1];
break;
}
}
fclose($file);
?>
Możesz również zapisywać pliki na serwerach FTP (zakładając, że połączyłeś się jako użytkownik z odpowiednimi prawami dostepu). Przy użyciu tej metody możesz jedynie tworzyć nowe pliki. Jeśli spróbujesz nadpisać istniejący plik, wywołanie funkcji fopen() zwróci błąd.
Aby połączyć się jako użytkowni inny niż 'anonymous', należy określić nazwę uzytkownika (możliwe, że i hasło) w URL, w następujący sposób 'ftp://użytkownik:hasło@ftp.example.com/ścieżka/do/pliku'. (Można używać takiej samej składni aby uzyskać dostęp do plików za pomocą HTTP w czasie wykorzystywania uwierzytelnienia typu Basic.)
Przykład #2 Zapisywanie danych na zdalnym serwerze.
<?php
$file = fopen ("ftp://ftp.example.com/incoming/outputfile", "w");
if (!$file) {
echo "<p>Nie można otworzyć zdalnego pliku do zapisu.\n";
exit;
}
/* Tutaj zapisujemy dane. */
fwrite ($file, $_SERVER['HTTP_USER_AGENT'] . "\n");
fclose ($file);
?>
Informacja:
Być może powyższy przykład nasunął ci pomysł, by użyć tej metody do zdalnego zapisywania logów. Niestety taka próba się nie powiedzie, gdyż wywołanie fopen() zwróci błąd, jeśli zdalny plik już istnieje. Aby zrealizować zdalne logowanie powinieneś przyjrzeć się funkcji syslog().
Obsługa połączeń
PHP wewnętrznie zarządza stanem połączenia. Mogą wystąpić trzy stany:
- 0 - NORMAL
- 1 - ABORTED (przerwany)
- 2 - TIMEOUT (przekroczony czas)
Kiedy skrypt PHP się wykonuje, aktywny jest stan NORMAL. Jeśli klient się rozłączy, stan przechodzi w ABORTED. Zwykle ma to miejsce gdy użytkownik naciśnie przycisk STOP w przeglądarce. Jeśli przekroczony zostanie narzucony limit czasu (patrz set_time_limit()), stan zmienia się na TIMEOUT.
Możesz zdecydować czy po rozłączeniu klienta praca skryptu ma zostać
przerwana. Czasem przydatne jest by skrypty działały do końca, nawet
gdy braknie przeglądarki do której można wysyłać dane. Domyślnie,
po rozłączeniu się klienta, działanie skryptu jest przerywane. To
zachowanie można zmienić dzięki opcji ignore_user_abort w php.ini, jak
również dyrektywie Apache httpd.conf php_value ignore_user_abort
lub funkcji ignore_user_abort(). Jeśli nie każesz PHP ignorować
rozłączeń klienta, a klient rozłączy się, skrypt zakończy działanie.
Jedyny wyjątek wystąpi, jeśli zarejestrujesz funkcję zamykającą, używając
register_shutdown_function(). Wtedy, gdy użytkownik
wciśnie przycisk STOP i przy kolejnej próbie wysłania wyniku PHP
wykryje przerwanie połączenia, zostanie wykonana funkcja zamykająca.
Będzie ona również wywoływana przy normalnym zakończeniu pracy skryptu,
zatem, by wykonać inne czynności gdy klient się rozłączy, można
użyć funkcji connection_aborted(). Zwraca ona
TRUE jeśli połączenie zostało przerwane.
Skrypt może zostać również zakończony przez wbudowany licznik czasu. Domyślnie czas ten wynosi 30 sekund. Wartość tę można zmienić używając opcji max_execution_time w php.ini, jak również dyrektywy Apache httpd.conf php_value max_execution_time lub funkcji set_time_limit(). Kiedy czas na wykonanie się skończy, skrypt zostanie przerwany podobnie jak w przypadku rozłączenia się klienta (patrz wyżej). Jeśli funkcja zamykająca była zarejestrowana, zostanie wywołana. Wewnątrz funkcji zamykającej możesz sprawdzić czy została ona wywołana wskutek przekroczenia czasu. Do tego celu użyj funkcji connection_status(). Funkcja zwróci 2, jeśli to przekroczenie limitu czasu spowodowało wywołanie funkcji zamykającej.
Należy zwrócić uwagę, że stany ABORTED i TIMEOUT mogą być aktywne
jednocześnie. Jest to możliwe, jeśli każesz PHP ignorować rozłączenia
klienta. PHP będzie brało pod uwagę fakt, że połączenie z klientem
mogło zostać zerwane, ale skrypt będzie pracował dalej. Gdy minie czas
przeznaczony na wykonanie skryptu, zostanie on przerwany i uruchomiona
zostanie funkcja zamykająca (jeśli była ustawiona). W tym momencie funkcje
connection_timeout() i
connection_aborted() będą zwracały TRUE. Możesz
także sprawdzić oba stany przy pomocy funkcji
connection_status() w takim wypadku zwróci ona 3.
Stałe połączenia z bazami danych
Stałe połączenia (persistent connections) to połączenia, które nie są zamykane po wykonaniu skryptu. Kiedy skrypt próbuje nawiązać stałe połączenie, PHP sprawdza czy istnieje już identyczne połączenie (otwarte wcześniej) i jeśli istnieje, używa go. Jeżeli nie, tworzone jest nowe. Połączenie 'identyczne' to połączenie z tym samym hostem, z taką samą nazwą użytkownika i hasłem.
Ludzie niezbyt dobrze znający zasady działania serwerów mogą czasem brać stałe połączenia za coś, czym te nie są. Stałe połączenia nie stwarzają możliwości otwarcia połączenia dla konkretnego użytkonika, nie pozwalają na skuteczne stworzenie systemu transakcji, i nie robią wielu innych rzeczy. Powiedzmy to jasno, stałe połączenia nie oferują nic ponad to, co robią 'zwykłe' połączenia.
Dlaczego?
Jest to związane z zasadą działania serwerów. Są trzy sposoby na które serwer może wykorzystac PHP do generowania stron.
Pierwsza metoda to wykorzystanie PHP jako "wrappera" CGI. Przy wywołaniu skryptu każdorazowo uruchamiany i niszczony jest egzamplarz PHP. Jako, że jest on niszczony po każdym wywołaniu, wszystkie zasoby przez niego posiadane (na przykład połączenia z bazą danych) są tracone. W tym przypadku używanie stałych połączeń nie przynosi korzyści, one po prostu nie są stałe.
Druga, najpopularniejsza metoda, to uruchomienie PHP jako modułu w wieloprocesowym serwerze, co obecnie dotyczy jedynie serwera Apache. Serwer wieloprocesowy zwykle uruchamia jeden proces (rodzica), który koordynuje inne procesy (potomne) zajmujące się dostarczaniem stron. Kiedy nadchodzi żądanie od klienta, jest ono przekazywane jednemu z procesów potomnych, który w danym momencie nie obsługuje innego klienta. Oznacza to, że gdy ten sam klient wyśle do serwera kolejne żądanie, może zostać obsłużony przez inny proces niż za pierwszym razem. Stałe połączenie w tym przypadku oznacza, że każdy proces potomny ustanawia połączenie z serwerem SQL przy pierwszym wywołaniu strony, która takiego połączenia używa.
Ostatnia metoda to wykorzystanie PHP jako wtyczki (plug-in) do serwera wielowątkowego. Obecnie PHP4 zawiera obsługę mechanizmów ISAPI, WSAPI i NSAPI (w Windows), które umożliwiają uruchomienie PHP jako wtyczki do wielowątkowych serwerów takich jak Netscape FastTrack (iPlanet), Microsoft Internet Information Server (IIS) i O'Reilly WebSite Pro. Zachowanie PHP jest zasadniczo takie samo jak w przypadku opisanego wcześniej modelu wieloprocesowego.
Skoro stałe połączenia nie dostarczają większej funkcjonalności, do czego mogą być przydatne?
Odpowiedź jest niezwykle prosta -- wydajność. Stałe połączenia sprawdzają się w przypadku, gdy koszt nawiązania połączenia z SQL serwerem jest wysoki. To czy koszt jest duży czy nie zależy od wielu czynników. Na przykład od typu bazy danych, od tego czy znajduje się ona na tym samym serwerze, od obciążenia maszyny, która obsługuje serwer SQL, itd. Jeśli zatem koszt połączenia jest wysoki, stałe połączenia znacznie pomagają. Sprawiają, że proces potomny łączy się z serwerem SQL tylko raz podczas swojego życia, zamiast otwierać połączenie za każdym razem gdy zażąda tego skrypt. Oznacza to, że każdy proces potomny, który nawiązał stałe połączenie, będzie posiadał własne połączenie z serwerem bazy danych. Dla przykładu, jeżeli 20 procesów potomnych uruchomi skrypt, który ustanowi stałe połączenie z serwerem SQL, będziesz mieć 20 różnych połączeń z serwerem, jedno na każdy proces.
Trzeba jednak zauważyć, że może to mieć swoje ujemne strony w przypadku, gdy limit połączeń do bazy danych zostanie przekroczony przez stałe połączenia z procesów potomnych. Jeśli twoja baza danych posiada limit szesnastu jednoczesnych połączeń, a w danej chwili obciążenie jest wysokie, siedemnasty proces nie będzie mógł się połączyć. Jeśli twoje skrypty zawierają błędy, które nie pozwalają zamknąć połączeń (na przykłąd nieskończone pętle), baza danych z limitem 16 połączeń może szybko zostać zapchana. Poszukaj w dokumentacji swojej bazy danych w jaki sposób radzi sobie ona z porzuconymi lub bezczynnymi połączeniami.
Istnieje kilka zagrożeń, które należy brać pod uwagę decydując się na używanie stałych połączeń. Jednym z nich jest sytuacja, w której skrypt blokujący tabelę, z jakiegokolwiek powodu nie może zdjąć blokady. Wtedy kolejne skrypty korzystające z tego samego połączenia będą zablokowane i może zajść potrzeba ponownego uruchomienia serwera httpd lub serwera bazy danych. Kolejne zagrożenie dotyczy transakcji. Jeśli skrypt używający transakcji zakończy działanie przed zakończeniem bloku transakcji, to zostanie on (blok) przeniesiony do następnego skryptu. W obu przypadkach można użyć register_shutdown_function(), aby zarejestrować funkcję porządkującą, która odblokuje tabele lub wycofa transakcje. Najlepiej jednak jest zrezygnować ze stałych połączeń w skryptach używających blokowania tabel lub transakcji.
Istotne podsumowanie. Stałe połączenia zostały zaprojektowane tak, by odpowiadać zwykłym połączeniom. Oznacza to, że zawsze możesz zastąpić stałe połączenia zwykłymi i nie zmieni to zachowania skryptu. Natomiast może zmienić (i zapewne zmieni) jego wydajność!
Zobacz także fbsql_pconnect(), ibase_pconnect(), ifx_pconnect(), ingres_pconnect(), msql_pconnect(), mssql_pconnect(), mysql_pconnect(), ociplogon(), odbc_pconnect(), oci_pconnect(), pfsockopen(), pg_pconnect() i sybase_pconnect().
Tryb bezpieczny
Spis treści
Tryb bezpieczny (ang. safe mode) jest próbą rozwiązania problemów bezpieczeństwa na współdzielonym serwerze. Co prawda rozwiązywanie ich na poziomie PHP nie jest najlepszym rozwiązaniem, ale jeśli nie ma możliwości zrobienia tego na poziomie serwera WWW lub systemu operacyjnego, na wielu serwerach, zwłaszcza u usługodawców internetowych, używa się trybu bezpiecznego.
Ta opcja jest PRZESTARZAŁA od PHP 5.3.0. Używanie tej opcji nie jest zalecane.
Zabezpieczenia i tryb bezpieczny
| Nazwa | Wartość domyślna | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| safe_mode | "0" | PHP_INI_SYSTEM | Usunięta w PHP 5.4.0. |
| safe_mode_gid | "0" | PHP_INI_SYSTEM | Dostępna od PHP 4.1.0. Usunięta w PHP 5.4.0. |
| safe_mode_include_dir | NULL | PHP_INI_SYSTEM | Dostępna od PHP 4.1.0. Usunięta w PHP 5.4.0. |
| safe_mode_exec_dir | "" | PHP_INI_SYSTEM | Usunięta w PHP 5.4.0. |
| safe_mode_allowed_env_vars | "PHP_" | PHP_INI_SYSTEM | Usunięta w PHP 5.4.0. |
| safe_mode_protected_env_vars | "LD_LIBRARY_PATH" | PHP_INI_SYSTEM | Usunięta w PHP 5.4.0. |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
safe_modeboolean -
Określa czy należy włączyć w PHP tryb bezpieczny. Jeśli PHP zostało skompilowane z parametrem --enable-safe-mode to domyślną wartością jest On. W przeciwnym przypadku domyślną wartością jest Off.
OstrzeżenieTa opcja jest PRZESTARZAŁA od PHP 5.3.0. Używanie tej opcji nie jest zalecane.
-
safe_mode_gidboolean -
Domyślnie tryb bezpieczny sprawdza, czy właścicielem uruchamianego skryptu lub pliku, do którego funkcja chce uzyskać dostęp, jest ten sam użytkownik (UID). Jeśli chcemy aby porównywana dotyczyły całej grupy (GID), należy włączyć safe_mode_gid. Określa czy używać UID (
FALSE) lub GID (TRUE) podczas sprawdzania dostępu do pliku. -
safe_mode_include_dirstring -
Sprawdza czy nie nastąpiło obejście UID/GID podczas dołączania plików z tego katalogu i jego podkatalogów (ścieżka do katalogu powinna być podana w include_path lub też powinna być dołączona pełna nazwa ścieżki).
Od PHP 4.2.0 ta dyrektywa może zawierać dwukropek (w Windows średnik) oddzielający ścieżki, podobnie jak w przypadku dyrektywy include_path, a nie tylko pojedyńczy katalog. Rejestrowanie ścieżki określane jest obecnie przez przedrostek, a nie nazwę katalogu. To oznacza, że "safe_mode_include_dir = /dir/incl" pozwala uzyskać dostęp do "/dir/include" i "/dir/incls" (jeżeli istnieją). Gdy chcemy ograniczyć dostęp tylko do określonego katalogu, dodajemy na końcu ukośnik. Na przykład: "safe_mode_include_dir = /dir/incl/" Jeśli wartość dyrektywy jest pusta, to żadne pliki - inne niż należące do UID/GID nie mogą być dołączone w PHP 4.2.3 i od PHP 4.3.3. We wcześniejszych wersjach mogły być dołączane wszystkie pliki. -
safe_mode_exec_dirstring -
Jeśli PHP działa w trybie bezpiecznym, system() i inne funkcje wykonujące programy systemowe otrzymają odmowę uruchomienia programów, tych które nie znajdują się w tym katalogu. Używamy / jako separatora katalogu dla wszystkich środowisk, włącznie z Windows.
-
safe_mode_allowed_env_varsstring -
Ustawienie pewnych zmiennych środowiskowych może być potencjalnym naruszeniem bezpieczeństwa. Ta dyrektywa zawiera listę przedrostków oddzielonych przecinkami. W trybie bezpiecznym użytkownik może wyłącznie zmieniać zmienne środowiskowe, których nazwy zaczynają się od przedrostków tutaj wymienionych. Domyślnie użytkownicy mają tylko możliwość ustawiania zmiennych środowiskowych zaczynających się od PHP_ (np. PHP_FOO=BAR).
Informacja:
Jeśli ta dyrektywa jest pusta, PHP pozwoli użytkownikowi zmieniać WSZYSTKIE zmienne środowiskowe!
-
safe_mode_protected_env_varsstring -
Ta dyretywa zawiera listę zmiennych środowiskowych oddzielonych przecinkami, których użytkownik końcowy nie może zmienić za pomocą putenv(). Te zmienne są zawsze chronione nawet jeśli safe_mode_allowed_env_vars pozwala na ich zmianę.
Patrz także: open_basedir, disable_functions, disable_classes, register_globals, display_errors, i log_errors.
Gdy opcja safe_mode jest włączona, PHP sprawdza czy właścicielem wykonywanego skryptu jest właściciel pliku, na którym chce operować funkcja, lub czy jest to katalog tego samego użytkownika. Na Przykład:
-rw-rw-r-- 1 rasmus rasmus 33 Jul 1 19:20 script.php -rw-r--r-- 1 root root 1116 May 26 18:01 /etc/passwd
<?php
readfile('/etc/passwd');
?>
Warning: SAFE MODE Restriction in effect. The script whose uid is 500 is not allowed to access /etc/passwd owned by uid 0 in /docroot/script.php on line 2
Jednakże mogą być środowiska, gdzie zbyt restrykcyjna weryfikacja UID nie jest stosownym rozwiązaniem, a łagodniejsze sprawdzanie GID jest w pełni wystarczające. Można to zmienić za pomocą safe_mode_gid. Ustawienie tej opcji na On włącza łagodniejsze sprawdzanie GID, a ustawienie na Off (domyślnie) przełącza na sprawdzanie UID.
Jeśli zamiast safe_mode ustawiamy katalog open_basedir wtedy wszystkie operacje na plikach będą ograniczone do plików znajdujących się w nim. Na przykład (Apache httpd.conf):
<Directory /docroot> php_admin_value open_basedir /docroot </Directory>
Warning: open_basedir restriction in effect. File is in wrong directory in /docroot/script.php on line 2
Możemy wyłączyć obsługę wybranych funkcji. Zauważmy, że dyrektywa disable_functions nie może być ustawiana poza plikiem php.ini co oznacza, że nie możemy wyłączyć funkcji dla wybranego wirtualnego hosta lub katalogu zdefiniowanego w pliku httpd.conf. Jeśli dodamy następującą dyrektywę do naszego pliku php.ini:
disable_functions = readfile,system
Warning: readfile() has been disabled for security reasons in /docroot/script.php on line 2
Naturalnie restrykcje PHP nie obowiązują w plikach wykonywalnych.
Funkcje ograniczane/wyłączone w trybie bezpiecznym
Jest to najprawdopodobniej wciąż niekompletna lista funkcji ograniczonych przez tryb bezpieczny.
| Funkcja | Ogranicznenia |
|---|---|
| dbmopen() | Sprawdza czy pliki lub katalogi, na których będą wykonane operacje, mają takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. |
| dbase_open() | Sprawdza czy pliki lub katalogi, na których będą wykonane operacje, mają takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. |
| filepro() | Sprawdza czy pliki lub katalogi, na których będą wykonane operacje, mają takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. |
| filepro_rowcount() | Sprawdza czy pliki lub katalogi, na których będą wykonane operacje, mają takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. |
| filepro_retrieve() | Sprawdza czy pliki lub katalogi, na których będą wykonane operacje, mają takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. |
| ifx_* | Podlega ograniczeniom narzuconym przez sql_safe_mode, (!= tryb bezpieczny) |
| ingres_* | Podlega ograniczeniom narzuconym przez sql_safe_mode, (!= tryb bezpieczny) |
| mysql_* | Podlega ograniczeniom narzuconym przez sql_safe_mode, (!= tryb bezpieczny) |
| pg_lo_import() | Sprawdza czy pliki lub katalogi, na których będą wykonane operacje, mają takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. |
| posix_mkfifo() | Sprawdza, czy katalog, na którym mają zostać wykonane operacje, ma takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. |
| putenv() | Podlega dyrektywom safe_mode_protected_env_vars i safe_mode_allowed_env_vars;. Zobacz również dokumantację do putenv() |
| move_uploaded_file() | Sprawdza czy pliki lub katalogi, na których będą wykonane operacje, mają takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. |
| chdir() | Sprawdza, czy katalog, na którym mają zostać wykonane operacje, ma takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. |
| dl() | Ta funkcja jest niedostępna jeśli PHP działa w trybie bezpiecznym |
| lewy apostrof | Ta funkcja jest niedostępna jeśli PHP działa w trybie bezpiecznym |
| shell_exec() (funkcja równoważna z lewym apostrofem) | Ta funkcja jest niedostępna jeśli PHP działa w trybie bezpiecznym |
| exec() | Możemy uruchamiać programy jedynie z katalogu zdefiniowanego za pomocą dyrektywy safe_mode_exec_dir. Ze względów praktycznych obecnie nie ma możliwości stosowania .. w ścieżce do programu. Wykonywana jest escapeshellcmd() na argumencie tej funkcji. |
| system() | Możemy uruchamiać programy jedynie z katalogu zdefiniowanego za pomocą dyrektywy safe_mode_exec_dir. Ze względów praktycznych obecnie nie ma możliwości stosowania .. w ścieżce do programu. Wykonywana jest escapeshellcmd() na argumencie tej funkcji. |
| passthru() | Możemy uruchamiać programy jedynie z katalogu zdefiniowanego za pomocą dyrektywy safe_mode_exec_dir. Ze względów praktycznych obecnie nie ma możliwości stosowania .. w ścieżce do programu. Wykonywana jest escapeshellcmd() na argumencie tej funkcji. |
| popen() | Możemy uruchamiać programy jedynie z katalogu zdefiniowanego za pomocą dyrektywy safe_mode_exec_dir. Ze względów praktycznych obecnie nie ma możliwości stosowania .. w ścieżce do programu. Wykonywana jest escapeshellcmd() na argumencie tej funkcji. |
| fopen() | Sprawdza, czy katalog, na którym mają zostać wykonane operacje, ma takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. |
| mkdir() | Sprawdza, czy katalog, na którym mają zostać wykonane operacje, ma takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. |
| rmdir() | Sprawdza, czy katalog, na którym mają zostać wykonane operacje, ma takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. |
| rename() | Sprawdza czy pliki lub katalogi, na których będą wykonane operacje, mają takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. Sprawdza, czy katalog, na którym mają zostać wykonane operacje, ma takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. |
| unlink() | Sprawdza czy pliki lub katalogi, na których będą wykonane operacje, mają takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. Sprawdza, czy katalog, na którym mają zostać wykonane operacje, ma takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. |
| copy() | Sprawdza czy pliki lub katalogi, na których będą
wykonane operacje, mają takie same UID (owner) jak skrypt, który jest
aktualnie wykonywany. Sprawdza, czy katalog, na którym mają zostać wykonane
operacje, ma takie same UID (owner) jak skrypt, który jest aktualnie
wykonywany. (dla
źródła i
przeznaczenia) |
| chgrp() | Sprawdza czy pliki lub katalogi, na których będą wykonane operacje, mają takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. |
| chown() | Sprawdza czy pliki lub katalogi, na których będą wykonane operacje, mają takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. |
| chmod() | Sprawdza czy pliki lub katalogi, na których będą wykonane operacje, mają takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. Dodatkowo, nie można ustawić bitów SUID, SGID i sticky bit |
| touch() | Sprawdza czy pliki lub katalogi, na których będą wykonane operacje, mają takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. Sprawdza, czy katalog, na którym mają zostać wykonane operacje, ma takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. |
| symlink() | Sprawdza czy pliki lub katalogi, na których będą wykonane operacje, mają takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. Sprawdza, czy katalog, na którym mają zostać wykonane operacje, ma takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. (notatka: sprawdzany jest jedynie element, do którego utworzone jest dowiązanie symboliczne) |
| link() | Sprawdza czy pliki lub katalogi, na których będą wykonane operacje, mają takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. Sprawdza, czy katalog, na którym mają zostać wykonane operacje, ma takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. (notatka: sprawdzany jest jedynie element, do którego utworzone jest dowiązanie) |
| apache_request_headers() | W trybie bezpiecznym, nie są zwracane nagłówki zaczynające się od 'authorization' (wielkość liter nie ma znaczenia). |
| header() | W trybie bezpiecznym UID skryptu jest dodawana do nazwy - części nagłówka Uwierzytelnienia-WWW, jeśli ustawimy ten nagłówek (używane w Uwierzytelnieniu HTTP). |
| PHP_AUTH variables | W trybie bezpiecznym zmienne PHP_AUTH_USER, PHP_AUTH_PW, i AUTH_TYPE nie są dostępne w $_SERVER. Niezależnie od tego, możemy nadal używać REMOTE_USER dla użytkownika. (notatka: dostępna tylko od PHP 4.3.0) |
| highlight_file(), show_source() | Sprawdza czy pliki lub katalogi, na których będą wykonane operacje, mają takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. Sprawdza, czy katalog, na którym mają zostać wykonane operacje, ma takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. (notatka: dostępna tylko od PHP 4.2.1) |
| parse_ini_file() | Sprawdza czy pliki lub katalogi, na których będą wykonane operacje, mają takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. Sprawdza, czy katalog, na którym mają zostać wykonane operacje, ma takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. (notatka: dostępna tylko od PHP 4.2.1) |
| set_time_limit() | Nie ma żadnego skutku, gdy PHP działa w trybie tryb bezpieczny. |
| max_execution_time | Nie ma żadnego skutku, gdy PHP działa w trybie tryb bezpieczny. |
| mail() | W trybie bezpiecznym, piąty parametr jest nieaktywny. (notatka: dostępna tylko od PHP 4.2.3) |
| session_start() | Właściciel skryptu musi być również właścicielem katalogusession.save_path, gdy wartość session.save_handler jest ustawiona na files. |
| Wszystkie funkcje systemu plików oraz strumieni. | Sprawdza czy pliki lub katalogi, na których będą wykonane operacje, mają takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. Sprawdza, czy katalog, na którym mają zostać wykonane operacje, ma takie same UID (owner) jak skrypt, który jest aktualnie wykonywany. (zobacz opcję safe_mode_include_dir php.ini. |
Using PHP from the command line
Spis treści
Introduction
PHP supports a CLI SAPI as of PHP 4.3.0. The main focus of this SAPI is for developing shell applications with PHP. There are quite a few differences between the CLI SAPI and other SAPIs which are explained in this chapter. It is worth mentioning that CLI and CGI are different SAPIs although they do share many of the same behaviors.
The CLI SAPI is enabled by default using --enable-cli , but may be disabled using the --disable-cli option when running ./configure.
The name, location and existence of the CLI/CGI binaries will differ depending on how PHP is installed on your system. By default when executing make, both the CGI and CLI are built and placed as sapi/cgi/php-cgi and sapi/cli/php respectively, in your PHP source directory. You will note that both are named php. What happens during make install depends on your configure line. If a module SAPI is chosen during configure, such as apxs, or the --disable-cgi option is used, the CLI is copied to {PREFIX}/bin/php during make install otherwise the CGI is placed there. So, for example, if --with-apxs is in your configure line then the CLI is copied to {PREFIX}/bin/php during make install. If you want to override the installation of the CGI binary, use make install-cli after make install. Alternatively you can specify --disable-cgi in your configure line.
Informacja:
Because both --enable-cli and --enable-cgi are enabled by default, simply having --enable-cli in your configure line does not necessarily mean the CLI will be copied as {PREFIX}/bin/php during make install.
As of PHP 5, the CLI binary is distributed in the main folder as php.exe on Windows. The CGI version is distributed as php-cgi.exe. Additionally, a php-win.exe is distributed if PHP is configured using --enable-cli-win32 . This does the same as the CLI version, except that it doesn't output anything and thus provides no console.
Informacja: What SAPI do I have?
From a shell, typing php -v will tell you whether php is CGI or CLI. See also the function php_sapi_name() and the constant
PHP_SAPI.
Informacja:
A Unix manual page is available by typing man php in the shell environment.
Differences to other SAPIs
Remarkable differences of the CLI SAPI compared to other SAPIs:
-
Unlike the CGI SAPI, no headers are written to the output.
Though the CGI SAPI provides a way to suppress HTTP headers, there's no equivalent switch to enable them in the CLI SAPI.
CLI is started up in quiet mode by default, though the -q and --no-header switches are kept for compatibility so that it is possible to use older CGI scripts.
It does not change the working directory to that of the script. (-C and --no-chdir switches kept for compatibility)
Plain text error messages (no HTML formatting).
-
There are certain php.ini directives which are overridden by the CLI SAPI because they do not make sense in shell environments:
Overridden php.ini directives Directive CLI SAPI default value Comment html_errors FALSEDefaults to FALSE, as it can be quite hard to read error messages in the shell enviroment when they are cluttered up with uninterpreted HTML tags.implicit_flush TRUEIn a shell environment, it is usually desirable for output, such as from print(), echo() and friends, to be displayed immediately, and not held in a buffer. Nonetheless, it is still possible to use output buffering to defer or manipulate standard output. max_execution_time 0 (unlimited) PHP in a shell environment tends to be used for a much more diverse range of purposes than typical Web-based scripts, and as these can be very long-running, the maximum execution time is set to unlimited. register_argc_argv TRUESetting this to
TRUEmeans that scripts executed via the CLI SAPI always have access to argc (number of arguments passed to the application) and argv (array of the actual arguments).The PHP variables $argc and $argv are automatically set to the appropriate values when using the CLI SAPI. These values can also be found in the $_SERVER array, for example: $_SERVER['argv'].
output_buffering FALSEAlthough the php.ini setting is hardcoded to
FALSE, the Output buffering functions are available.max_input_time FALSEThe PHP CLI doesn't not support GET, POST or file uploads.
Informacja:
These directives cannot be initialized with another value from the configuration file php.ini or a custom one (if specified). This limitation is because the values are applied after all configuration files have been parsed. However, their values can be changed during runtime (although this is not sensible for all of them, such as register_argc_argv).
Informacja:
It is recommended to set ignore_user_abort for command line scripts. See ignore_user_abort() for more information.
-
To ease working in the shell environment, a number of constants are defined for I/O streams .
-
The CLI SAPI does not change the current directory to the directory of the executed script.
Przykład #1 Example showing the difference to the CGI SAPI:
<?php
// Our simple test application named test.php
echo getcwd(), "\n";
?>When using the CGI version, the output is:
$ pwd /tmp $ php -q another_directory/test.php /tmp/another_directory
This clearly shows that PHP changes its current directory to the one of the executed script.
Using the CLI SAPI yields:
$ pwd /tmp $ php -f another_directory/test.php /tmp
This allows greater flexibility when writing shell tools in PHP.
Informacja:
The CGI SAPI supports this CLI SAPI behaviour by means of the -C switch when run from the command line.
Command line options
The list of command line options provided by the PHP binary can be queried at any time by running PHP with the -h switch:
Usage: php [options] [-f] <file> [--] [args...]
php [options] -r <code> [--] [args...]
php [options] [-B <begin_code>] -R <code> [-E <end_code>] [--] [args...]
php [options] [-B <begin_code>] -F <file> [-E <end_code>] [--] [args...]
php [options] -- [args...]
php [options] -a
-a Run interactively
-c <path>|<file> Look for php.ini file in this directory
-n No php.ini file will be used
-d foo[=bar] Define INI entry foo with value 'bar'
-e Generate extended information for debugger/profiler
-f <file> Parse and execute <file>.
-h This help
-i PHP information
-l Syntax check only (lint)
-m Show compiled in modules
-r <code> Run PHP <code> without using script tags <?..?>
-B <begin_code> Run PHP <begin_code> before processing input lines
-R <code> Run PHP <code> for every input line
-F <file> Parse and execute <file> for every input line
-E <end_code> Run PHP <end_code> after processing all input lines
-H Hide any passed arguments from external tools.
-S <addr>:<port> Run with built-in web server.
-t <docroot> Specify document root <docroot> for built-in web server.
-s Output HTML syntax highlighted source.
-v Version number
-w Output source with stripped comments and whitespace.
-z <file> Load Zend extension <file>.
args... Arguments passed to script. Use -- args when first argument
starts with - or script is read from stdin
--ini Show configuration file names
--rf <name> Show information about function <name>.
--rc <name> Show information about class <name>.
--re <name> Show information about extension <name>.
--rz <name> Show information about Zend extension <name>.
--ri <name> Show configuration for extension <name>.
| Option | Long Option | Description |
|---|---|---|
| -a | --interactive |
Run PHP interactively. For more information, see the Interactive shell section. |
| -b | --bindpath |
Bind Path for external FASTCGI Server mode (CGI only). |
| -C | --no-chdir |
Do not chdir to the script's directory (CGI only). |
| -q | --no-header |
Quiet-mode. Suppress HTTP header output (CGI only). |
| -T | --timing |
Measure execution time of script repeated count times (CGI only). |
| -c | --php-ini |
Specifies either a directory in which to look for php.ini, or a custom INI file (which does not need to be named php.ini), e.g.: $ php -c /custom/directory/ my_script.php $ php -c /custom/directory/custom-file.ini my_script.php If this option is not specified, php.ini is searched for in the default locations. |
| -n | --no-php-ini |
Ignore php.ini completely. |
| -d | --define |
Set a custom value for any of the configuration directives allowed in php.ini. The syntax is: -d configuration_directive[=value]
# Omitting the value part will set the given configuration directive to "1"
$ php -d max_execution_time
-r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(1) "1"
# Passing an empty value part will set the configuration directive to ""
php -d max_execution_time=
-r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(0) ""
# The configuration directive will be set to anything passed after the '=' character
$ php -d max_execution_time=20
-r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(2) "20"
$ php
-d max_execution_time=doesntmakesense
-r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(15) "doesntmakesense"
|
| -e | --profile-info |
Activate the extended information mode, to be used by a debugger/profiler. |
| -f | --file |
Parse and execute the specified file. The -f is optional and may be omitted - providing just the filename to execute is sufficient.
|
| -h and -? | --help and --usage | Output a list of command line options with one line descriptions of what they do. |
| -i | --info | Calls phpinfo(), and prints out the results. If PHP is not working correctly, it is advisable to use the command php -i and see whether any error messages are printed out before or in place of the information tables. Beware that when using the CGI mode the output is in HTML and therefore very large. |
| -l | --syntax-check |
Provides a convenient way to perform only a syntax check on the given PHP code. On success, the text No syntax errors detected in <filename> is written to standard output and the shell return code is 0. On failure, the text Errors parsing <filename> in addition to the internal parser error message is written to standard output and the shell return code is set to -1. This option won't find fatal errors (like undefined functions). Use the -f to test for fatal errors too.
|
| -m | --modules |
Przykład #1 Printing built in (and loaded) PHP and Zend modules $ php -m [PHP Modules] xml tokenizer standard session posix pcre overload mysql mbstring ctype [Zend Modules] |
| -r | --run |
Allows execution of PHP included directly on the command line. The PHP start and end tags (<?php and ?>) are not needed and will cause a parse error if present.
|
| -B | --process-begin |
PHP code to execute before processing stdin. Added in PHP 5. |
| -R | --process-code |
PHP code to execute for every input line. Added in PHP 5. There are two special variables available in this mode: $argn and $argi. $argn will contain the line PHP is processing at that moment, while $argi will contain the line number. |
| -F | --process-file |
PHP file to execute for every input line. Added in PHP 5. |
| -E | --process-end |
PHP code to execute after processing the input. Added in PHP 5. Przykład #4 Using the -B , -R and -E options to count the number of lines of a project. $ find my_proj | php -B '$l=0;' -R '$l += count(@file($argn));' -E 'echo "Total Lines: $l\n";' Total Lines: 37328 |
| -S | --server |
Starts built-in web server. Available as of PHP 5.4.0. |
| -t | --docroot | Specifies document root for built-in web server. Available as of PHP 5.4.0. |
| -s | --syntax-highlight and --syntax-highlighting |
Display colour syntax highlighted source. This option uses the internal mechanism to parse the file and writes an HTML highlighted version of it to standard output. Note that all it does is generate a block of <code> [...] </code> HTML tags, no HTML headers.
|
| -v | --version |
Przykład #5 Using -v to get the SAPI name and the version of PHP and Zend $ php -v PHP 5.3.1 (cli) (built: Dec 11 2009 19:55:07) Copyright (c) 1997-2009 The PHP Group Zend Engine v2.3.0, Copyright (c) 1998-2009 Zend Technologies |
| -w | --strip |
Display source with comments and whitespace stripped.
|
| -z | --zend-extension |
Load Zend extension. If only a filename is given, PHP tries to load this extension from the current default library path on your system (usually /etc/ld.so.conf on Linux systems, for example). Passing a filename with an absolute path will not use the system's library search path. A relative filename including directory information will tell PHP to try loading the extension relative to the current directory. |
| --ini |
Show configuration file names and scanned directories. Available as of PHP 5.2.3. Przykład #6 --ini example $ php --ini Configuration File (php.ini) Path: /usr/dev/php/5.2/lib Loaded Configuration File: /usr/dev/php/5.2/lib/php.ini Scan for additional .ini files in: (none) Additional .ini files parsed: (none) |
|
| --rf | --rfunction |
Show information about the given function or class method (e.g. number and name of the parameters). Available as of PHP 5.1.2. This option is only available if PHP was compiled with Reflection support.
Przykład #7 basic --rf usage $ php --rf var_dump
Function [ <internal> public function var_dump ] {
- Parameters [2] {
Parameter #0 [ <required> $var ]
Parameter #1 [ <optional> $... ]
}
}
|
| --rc | --rclass |
Show information about the given class (list of constants, properties and methods). Available as of PHP 5.1.2. This option is only available if PHP was compiled with Reflection support.
Przykład #8 --rc example $ php --rc Directory
Class [ <internal:standard> class Directory ] {
- Constants [0] {
}
- Static properties [0] {
}
- Static methods [0] {
}
- Properties [0] {
}
- Methods [3] {
Method [ <internal> public method close ] {
}
Method [ <internal> public method rewind ] {
}
Method [ <internal> public method read ] {
}
}
}
|
| --re | --rextension |
Show information about the given extension (list of php.ini options, defined functions, constants and classes). Available as of PHP 5.1.2. This option is only available if PHP was compiled with Reflection support.
Przykład #9 --re example $ php --re json
Extension [ <persistent> extension #19 json version 1.2.1 ] {
- Functions {
Function [ <internal> function json_encode ] {
}
Function [ <internal> function json_decode ] {
}
}
}
|
| --rz | --rzendextension |
Show the configuration information for the given Zend extension (the same information that is returned by phpinfo()). Available as of PHP 5.4.0. |
| --ri | --rextinfo |
Show the configuration information for the given extension (the same information that is returned by phpinfo()). Available as of PHP 5.2.2. The core configuration information is available using "main" as extension name.
Przykład #10 --ri example $ php --ri date date date/time support => enabled "Olson" Timezone Database Version => 2009.20 Timezone Database => internal Default timezone => Europe/Oslo Directive => Local Value => Master Value date.timezone => Europe/Oslo => Europe/Oslo date.default_latitude => 59.930972 => 59.930972 date.default_longitude => 10.776699 => 10.776699 date.sunset_zenith => 90.583333 => 90.583333 date.sunrise_zenith => 90.583333 => 90.583333 |
Informacja:
Options -rBRFEH, --ini and --r[fcezi] are available only in CLI.
Executing PHP files
There are three different ways of supplying the CLI SAPI with PHP code to be executed:
-
Tell PHP to execute a certain file.
$ php my_script.php $ php -f my_script.php
Both ways (whether using the -f switch or not) execute the file my_script.php. Note that there is no restriction on which files can be executed; in particular, the filename is not required have a .php extension.
Informacja:
If arguments need to be passed to the script when using -f , the first argument must be --.
-
Pass the PHP code to execute directly on the command line.
$ php -r 'print_r(get_defined_constants());'
Special care has to be taken with regard to shell variable substitution and usage of quotes.
Informacja:
Read the example carefully: there are no beginning or ending tags! The -r switch simply does not need them, and using them will lead to a parse error.
-
Provide the PHP code to execute via standard input (stdin).
This gives the powerful ability to create PHP code dynamically and feed it to the binary, as shown in this (fictional) example:
$ some_application | some_filter | php | sort -u > final_output.txt
As with every shell application, the PHP binary accepts a number of arguments; however, the PHP script can also receive further arguments. The number of arguments that can be passed to your script is not limited by PHP (and although the shell has a limit to the number of characters which can be passed, this is not in general likely to be hit). The arguments passed to the script are available in the global array $argv. The first index (zero) always contains the name of the script as called from the command line. Note that, if the code is executed in-line using the command line switch -r , the value of $argv[0] will be just a dash (-). The same is true if the code is executed via a pipe from STDIN.
A second global variable, $argc, contains the number of elements in the $argv array (not the number of arguments passed to the script).
As long as the arguments to be passed to the script do not start with the - character, there's nothing special to watch out for. Passing an argument to the script which starts with a - will cause trouble because the PHP interpreter thinks it has to handle it itself, even before executing the script. To prevent this, use the argument list separator --. After this separator has been parsed by PHP, every following argument is passed untouched to the script.
# This will not execute the given code but will show the PHP usage
$ php -r 'var_dump($argv);' -h
Usage: php [options] [-f] <file> [args...]
[...]
# This will pass the '-h' argument to the script and prevent PHP from showing its usage
$ php -r 'var_dump($argv);' -- -h
array(2) {
[0]=>
string(1) "-"
[1]=>
string(2) "-h"
}
However, on Unix systems there's another way of using PHP for shell scripting: make the first line of the script start with #!/usr/bin/php (or whatever the path to your PHP CLI binary is if different). The rest of the file should contain normal PHP code within the usual PHP starting and end tags. Once the execution attributes of the file are set appropriately (e.g. chmod +x test), the script can be executed like any other shell or perl script:
Przykład #1 Execute PHP script as shell script
#!/usr/bin/php
<?php
var_dump($argv);
?>
Assuming this file is named test in the current directory, it is now possible to do the following:
$ chmod +x test
$ ./test -h -- foo
array(4) {
[0]=>
string(6) "./test"
[1]=>
string(2) "-h"
[2]=>
string(2) "--"
[3]=>
string(3) "foo"
}
As can be seen, in this case no special care needs to be taken when passing parameters starting with -.
The PHP executable can be used to run PHP scripts absolutely independent of the web server. On Unix systems, the special #! (or "shebang") first line should be added to PHP scripts so that the system can automatically tell which program should run the script. On Windows platforms, it's possible to associate php.exe with the double click option of the .php extension, or a batch file can be created to run scripts through PHP. The special shebang first line for Unix does no harm on Windows (as it's formatted as a PHP comment), so cross platform programs can be written by including it. A simple example of writing a command line PHP program is shown below.
Przykład #2 Script intended to be run from command line (script.php)
#!/usr/bin/php
<?php
if ($argc != 2 || in_array($argv[1], array('--help', '-help', '-h', '-?'))) {
?>
This is a command line PHP script with one option.
Usage:
<?php echo $argv[0]; ?> <option>
<option> can be some word you would like
to print out. With the --help, -help, -h,
or -? options, you can get this help.
<?php
} else {
echo $argv[1];
}
?>
The script above includes the Unix shebang first line to indicate that this file should be run by PHP. We are working with a CLI version here, so no HTTP headers will be output.
The program first checks that there is the required one argument (in addition to the script name, which is also counted). If not, or if the argument was --help , -help , -h or -? , the help message is printed out, using $argv[0] to dynamically print the script name as typed on the command line. Otherwise, the argument is echoed out exactly as received.
To run the above script on Unix, it must be made executable, and called simply as script.php echothis or script.php -h. On Windows, a batch file similar to the following can be created for this task:
Przykład #3 Batch file to run a command line PHP script (script.bat)
@echo OFF "C:\php\php.exe" script.php %*
Assuming the above program is named script.php, and the CLI php.exe is in C:\php\php.exe, this batch file will run it, passing on all appended options: script.bat echothis or script.bat -h.
See also the Readline extension documentation for more functions which can be used to enhance command line applications in PHP.
On Windows, PHP can be configured to run without the need to supply the C:\php\php.exe or the .php extension, as described in Command Line PHP on Microsoft Windows.
Input/output streams
The CLI SAPI defines a few constants for I/O streams to make programming for the command line a bit easier.
| Constant | Description |
|---|---|
STDIN |
An already opened stream to stdin. This saves opening it with
<?php
<?php |
STDOUT |
An already opened stream to stdout. This saves opening it with
<?php |
STDERR |
An already opened stream to stderr. This saves opening it with
<?php |
Given the above, you don't need to open e.g. a stream for stderr yourself but simply use the constant instead of the stream resource:
php -r 'fwrite(STDERR, "stderr\n");'
Informacja:
These constants are not available if reading the PHP script from stdin.
Interactive shell
As of PHP 5.1.0, the CLI SAPI provides an interactive shell using the -a option if PHP is compiled with the --with-readline option.
Using the interactive shell you are able to type PHP code and have it executed directly.
Przykład #1 Executing code using the interactive shell
$ php -a
Interactive shell
php > echo 5+8;
13
php > function addTwo($n)
php > {
php { return $n + 2;
php { }
php > var_dump(addtwo(2));
int(4)
php >
The interactive shell also features tab completion for functions, constants, class names, variables, static method calls and class constants.
Przykład #2 Tab completion
Pressing the tab key twice when there are multiple possible completions will result in a list of these completions:
php > strp[TAB][TAB] strpbrk strpos strptime php > strp
When there is only one possible completion, pressing tab once will complete the rest on the same line:
php > strpt[TAB]ime(
Completion will also work for names that have been defined during the current interactive shell session:
php > $fooThisIsAReallyLongVariableName = 42; php > $foo[TAB]ThisIsAReallyLongVariableName
The interactive shell stores your history which can be accessed using the up and down keys. The history is saved in the ~/.php_history file.
As of PHP 5.4.0, the CLI SAPI provides
the php.ini settings cli.pager and
cli.prompt. The cli.pager
setting allows an external program (such as less) to
act as a pager for the output instead of being displayed directly on the
screen. The cli.prompt setting makes it possible to
change the php > prompt.
In PHP 5.4.0 it was also made possible to set php.ini settings in the interactive shell using a shorthand notation.
Przykład #3 Setting php.ini settings in the interactive shell
The cli.prompt setting:
php > #cli.prompt=hello world :> hello world :>
Using backticks it is possible to have PHP code executed in the prompt:
php > #cli.prompt=`echo date('H:i:s');` php >
15:49:35 php > echo 'hi';
hi
15:49:43 php > sleep(2);
15:49:45 php >
Setting the pager to less:
php > #cli.pager=less php > phpinfo(); (output displayed in less) php >
The cli.prompt setting supports a few escape
sequences:
| Sequence | Description |
|---|---|
| \e | Used for adding colors to the prompt. An example could be \e[032m\v \e[031m\b \e[34m\> \e[0m |
| \v | The PHP version. |
| \b | Indicates which block PHP is in. For instance /* to indicate being inside a multi-line comment. The outer scope is denoted by php. |
| \> | Indicates the prompt character. By default this is >, but changes when the shell is inside an unterminated block or string. Possible characters are: ' " { ( > |
Informacja:
Files included through auto_prepend_file and auto_append_file are parsed in this mode but with some restrictions - e.g. functions have to be defined before called.
Informacja:
Autoloading is not available if using PHP in CLI interactive mode.
Built-in web server
As of PHP 5.4.0, the CLI SAPI provides a built-in web server.
This web server is designed for developmental purposes only, and should not be used in production.
URI requests are served from the current working directory where PHP was started, unless the -t option is used to specify an explicit document root.
If a URI request does not specify a file, then either index.php or index.html in the given directory are returned. If neither file exists, then a 404 response code is returned.
If a PHP file is given on the command line when the web server is
started it is treated as a "router" script for the web server.
The script is run at the start of each HTTP request. If this
script returns FALSE, then the requested resource is returned
as-is. Otherwise the script's output is returned to the browser.
Przykład #1 Starting the web server
$ cd ~/public_html $ php -S localhost:8000
The terminal will show:
PHP 5.4.0 Development Server started at Thu Jul 21 10:43:28 2011 Listening on localhost:8000 Document root is /home/me/public_html Press Ctrl-C to quit
After URI requests for http://localhost:8000/ and http://localhost:8000/myscript.html the terminal will show something similar to:
PHP 5.4.0 Development Server started at Thu Jul 21 10:43:28 2011 Listening on localhost:8000 Document root is /home/me/public_html Press Ctrl-C to quit. [Thu Jul 21 10:48:48 2011] ::1:39144 GET /favicon.ico - Request read [Thu Jul 21 10:48:50 2011] ::1:39146 GET / - Request read [Thu Jul 21 10:48:50 2011] ::1:39147 GET /favicon.ico - Request read [Thu Jul 21 10:48:52 2011] ::1:39148 GET /myscript.html - Request read [Thu Jul 21 10:48:52 2011] ::1:39149 GET /favicon.ico - Request read
Przykład #2 Starting with a specific document root directory
$ cd ~/public_html $ php -S localhost:8000 -t foo/
The terminal will show:
PHP 5.4.0 Development Server started at Thu Jul 21 10:50:26 2011 Listening on localhost:8000 Document root is /home/me/public_html/foo Press Ctrl-C to quit
Przykład #3 Using a Router Script
Requests for images will display them, but requests for HTML files will display "Welcome to PHP"
<?php
// router.php
if (preg_match('/\.(?:png|jpg|jpeg|gif)$/', $_SERVER["REQUEST_URI"]))
return false; // serve the requested resource as-is.
else {
echo "<p>Welcome to PHP</p>";
}
?>
$ php -S localhost:8000 router.php
After several URI requests the terminal will show something similar to:
PHP 5.4.0 Development Server started at Thu Jul 21 10:53:19 2011 Listening on localhost:8000 Document root is /home/me/public_html Press Ctrl-C to quit. [Thu Jul 21 10:53:45 2011] ::1:55801 GET /mylogo.jpg - Request read [Thu Jul 21 10:53:52 2011] ::1:55803 GET /abc.html - Request read [Thu Jul 21 10:53:52 2011] ::1:55804 GET /favicon.ico - Request read
Garbage Collection
Spis treści
This section explains the merits of the new Garbage Collection (also known as GC) mechanism that is part of PHP 5.3.
Reference Counting Basics
A PHP variable is stored in a container called a "zval". A zval container contains, besides the variable's type and value, two additional bits of information. The first is called "is_ref" and is a boolean value indicating whether or not the variable is part of a "reference set". With this bit, PHP's engine knows how to differentiate between normal variables and references. Since PHP allows user-land references, as created by the & operator, a zval container also has an internal reference counting mechanism to optimize memory usage. This second piece of additional information, called "refcount", contains how many variable names (also called symbols) point to this one zval container. All symbols are stored in a symbol table, of which there is one per scope. There is a scope for the main script (i.e., the one requested through the browser), as well as one for every function or method.
A zval container is created when a new variable is created with a constant value, such as:
Przykład #1 Creating a new zval container
<?php
$a = "new string";
?>
In this case, the new symbol name, a, is created in the current scope,
and a new variable container is created with the type string and the value
new string. The "is_ref" bit is by default set to FALSE because no
user-land reference has been created. The "refcount" is set to 1 as
there is only one symbol that makes use of this variable container. Note
that if "refcount" is 1, "is_ref" is always FALSE. If you have » Xdebug installed, you can display this
information by calling xdebug_debug_zval().
Przykład #2 Displaying zval information
<?php
xdebug_debug_zval('a');
?>
Powyższy przykład wyświetli:
a: (refcount=1, is_ref=0)='new string'
Assigning this variable to another variable name will increase the refcount.
Przykład #3 Increasing refcount of a zval
<?php
$a = "new string";
$b = $a;
xdebug_debug_zval( 'a' );
?>
Powyższy przykład wyświetli:
a: (refcount=2, is_ref=0)='new string'
The refcount is 2 here, because the same variable container is linked with both a and b. PHP is smart enough not to copy the actual variable container when it is not necessary. Variable containers get destroyed when the "refcount" reaches zero. The "refcount" gets decreased by one when any symbol linked to the variable container leaves the scope (e.g. when the function ends) or when unset() is called on a symbol. The following example shows this:
Przykład #4 Decreasing zval refcount
<?php
$a = "new string";
$c = $b = $a;
xdebug_debug_zval( 'a' );
unset( $b, $c );
xdebug_debug_zval( 'a' );
?>
Powyższy przykład wyświetli:
a: (refcount=3, is_ref=0)='new string' a: (refcount=1, is_ref=0)='new string'
If we now call unset($a);, the variable container, including the type and value, will be removed from memory.
Compound Types
Things get a tad more complex with compound types such as arrays and objects. Instead of a scalar value, arrays and objects store their properties in a symbol table of their own. This means that the following example creates three zval containers:
Przykład #5 Creating a array zval
<?php
$a = array( 'meaning' => 'life', 'number' => 42 );
xdebug_debug_zval( 'a' );
?>
Powyższy przykład wyświetli coś podobnego do:
a: (refcount=1, is_ref=0)=array ( 'meaning' => (refcount=1, is_ref=0)='life', 'number' => (refcount=1, is_ref=0)=42 )
Or graphically
The three zval containers are: a, meaning, and number. Similar rules apply for increasing and decreasing "refcounts". Below, we add another element to the array, and set its value to the contents of an already existing element:
Przykład #6 Adding already existing element to an array
<?php
$a = array( 'meaning' => 'life', 'number' => 42 );
$a['life'] = $a['meaning'];
xdebug_debug_zval( 'a' );
?>
Powyższy przykład wyświetli coś podobnego do:
a: (refcount=1, is_ref=0)=array ( 'meaning' => (refcount=2, is_ref=0)='life', 'number' => (refcount=1, is_ref=0)=42, 'life' => (refcount=2, is_ref=0)='life' )
Or graphically
From the above Xdebug output, we see that both the old and new array elements now point to a zval container whose "refcount" is 2. Although Xdebug's output shows two zval containers with value 'life', they are the same one. The xdebug_debug_zval() function does not show this, but you could see it by also displaying the memory pointer.
Removing an element from the array is like removing a symbol from a scope. By doing so, the "refcount" of a container that an array element points to is decreased. Again, when the "refcount" reaches zero, the variable container is removed from memory. Again, an example to show this:
Przykład #7 Removing an element from an array
<?php
$a = array( 'meaning' => 'life', 'number' => 42 );
$a['life'] = $a['meaning'];
unset( $a['meaning'], $a['number'] );
xdebug_debug_zval( 'a' );
?>
Powyższy przykład wyświetli coś podobnego do:
a: (refcount=1, is_ref=0)=array ( 'life' => (refcount=1, is_ref=0)='life' )
Now, things get interesting if we add the array itself as an element of the array, which we do in the next example, in which we also sneak in a reference operator, since otherwise PHP would create a copy:
Przykład #8 Adding the array itself as an element of it self
<?php
$a = array( 'one' );
$a[] =& $a;
xdebug_debug_zval( 'a' );
?>
Powyższy przykład wyświetli coś podobnego do:
a: (refcount=2, is_ref=1)=array ( 0 => (refcount=1, is_ref=0)='one', 1 => (refcount=2, is_ref=1)=... )
Or graphically
You can see that the array variable (a) as well as the second element (1) now point to a variable container that has a "refcount" of 2. The "..." in the display above shows that there is recursion involved, which, of course, in this case means that the "..." points back to the original array.
Just like before, unsetting a variable removes the symbol, and the reference count of the variable container it points to is decreased by one. So, if we unset variable $a after running the above code, the reference count of the variable container that $a and element "1" point to gets decreased by one, from "2" to "1". This can be represented as:
Przykład #9 Unsetting $a
(refcount=1, is_ref=1)=array ( 0 => (refcount=1, is_ref=0)='one', 1 => (refcount=1, is_ref=1)=... )
Or graphically
Cleanup Problems
Although there is no longer a symbol in any scope pointing to this structure, it cannot be cleaned up because the array element "1" still points to this same array. Because there is no external symbol pointing to it, there is no way for a user to clean up this structure; thus you get a memory leak. Fortunately, PHP will clean up this data structure at the end of the request, but before then, this is taking up valuable space in memory. This situation happens often if you're implementing parsing algorithms or other things where you have a child point back at a "parent" element. The same situation can also happen with objects of course, where it actually is more likely to occur, as objects are always implicitly used by reference.
This might not be a problem if this only happens once or twice, but if there are thousands, or even millions, of these memory losses, this obviously starts being a problem. This is especially problematic in long running scripts, such as daemons where the request basically never ends, or in large sets of unit tests. The latter caused problems while running the unit tests for the Template component of the eZ Components library. In some cases, it would require over 2 GB of memory, which the test server didn't quite have.
Collecting Cycles
Traditionally, reference counting memory mechanisms, such as that used previously by PHP, fail to address circular reference memory leaks. As of 5.3.0 PHP however implements the synchronous algorithm from the » Concurrent Cycle Collection in Reference Counted Systems paper which addresses that issue.
A full explanation of how the algorithm works would be slightly beyond the scope of this section, but the basics are explained here. First of all, we have to establish a few ground rules. If a refcount is increased, it's still in use and therefore, not garbage. If the refcount is decreased and hits zero, the zval can be freed. This means that garbage cycles can only be created when a refcount argument is decreased to a non-zero value. Secondly, in a garbage cycle, it is possible to discover which parts are garbage by checking whether it is possible to decrease their refcount by one, and then checking which of the zvals have a refcount of zero.
To avoid having to call the checking of garbage cycles with every possible decrease of a refcount, the algorithm instead puts all possible roots (zvals) in the "root buffer" (marking them "purple"). It also makes sure that each possible garbage root ends up in the buffer only once. Only when the root buffer is full does the collection mechanism start for all the different zvals inside. See step A in the figure above.
In step B, the algorithm runs a depth-first search on all possible roots to decrease by one the refcounts of each zval it finds, making sure not to decrease a refcount on the same zval twice (by marking them as "grey"). In step C, the algorithm again runs a depth-first search from each root node, to check the refcount of each zval again. If it finds that the refcount is zero, the zval is marked "white" (blue in the figure). If it's larger than zero, it reverts the decreasing of the refcount by one with a depth-first search from that point on, and they are marked "black" again. In the last step (D), the algorithm walks over the root buffer removing the zval roots from there, and meanwhile, checks which zvals have been marked "white" in the previous step. Every zval marked as "white" will be freed.
Now that you have a basic understanding of how the algorithm works, we will look back at how this integrates with PHP. By default, PHP's garbage collector is turned on. There is, however, a php.ini setting that allows you to change this: zend.enable_gc .
When the garbage collector is turned on, the cycle-finding algorithm as described above is executed whenever the root buffer runs full. The root buffer has a fixed size of 10,000 possible roots (although you can alter this by changing the GC_ROOT_BUFFER_MAX_ENTRIES constant in Zend/zend_gc.c in the PHP source code, and re-compiling PHP). When the garbage collector is turned off, the cycle-finding algorithm will never run. However, possible roots will always be recorded in the root buffer, no matter whether the garbage collection mechanism has been activated with this configuration setting.
If the root buffer becomes full with possible roots while the garbage collection mechanism is turned off, further possible roots will simply not be recorded. Those possible roots that are not recorded will never be analyzed by the algorithm. If they were part of a circular reference cycle, they would never be cleaned up and would create a memory leak.
The reason why possible roots are recorded even if the mechanism has been disabled is because it's faster to record possible roots than to have to check whether the mechanism is turned on every time a possible root could be found. The garbage collection and analysis mechanism itself, however, can take a considerable amount of time.
Besides changing the zend.enable_gc configuration setting, it is also possible to turn the garbage collecting mechanism on and off by calling gc_enable() or gc_disable() respectively. Calling those functions has the same effect as turning on or off the mechanism with the configuration setting. It is also possible to force the collection of cycles even if the possible root buffer is not full yet. For this, you can use the gc_collect_cycles() function. This function will return how many cycles were collected by the algorithm.
The rationale behind the ability to turn the mechanism on and off, and to initiate cycle collection yourself, is that some parts of your application could be highly time-sensitive. In those cases, you might not want the garbage collection mechanism to kick in. Of course, by turning off the garbage collection for certain parts of your application, you do risk creating memory leaks because some possible roots might not fit into the limited root buffer. Therefore, it is probably wise to call gc_collect_cycles() just before you call gc_disable() to free up the memory that could be lost through possible roots that are already recorded in the root buffer. This then leaves an empty buffer so that there is more space for storing possible roots while the cycle collecting mechanism is turned off.
Performance Considerations
We have already mentioned in the previous section that simply collecting the possible roots had a very tiny performance impact, but this is when you compare PHP 5.2 against PHP 5.3. Although the recording of possible roots compared to not recording them at all, like in PHP 5.2, is slower, other changes to the PHP runtime in PHP 5.3 prevented this particular performance loss from even showing.
There are two major areas in which performance is affected. The first area is reduced memory usage, and the second area is run-time delay when the garbage collection mechanism performs its memory cleanups. We will look at both of those issues.
Reduced Memory Usage
First of all, the whole reason for implementing the garbage collection mechanism is to reduce memory usage by cleaning up circular-referenced variables as soon as the prerequisites are fulfilled. In PHP's implementation, this happens as soon as the root-buffer is full, or when the function gc_collect_cycles() is called. In the graph below, we display the memory usage of the script below, in both PHP 5.2 and PHP 5.3, excluding the base memory that PHP itself uses when starting up.
Przykład #1 Memory usage example
<?php
class Foo
{
public $var = '3.1415962654';
}
$baseMemory = memory_get_usage();
for ( $i = 0; $i <= 100000; $i++ )
{
$a = new Foo;
$a->self = $a;
if ( $i % 500 === 0 )
{
echo sprintf( '%8d: ', $i ), memory_get_usage() - $baseMemory, "\n";
}
}
?>
In this very academic example, we are creating an object in which a property is set to point back to the object itself. When the $a variable in the script is re-assigned in the next iteration of the loop, a memory leak would typically occur. In this case, two zval-containers are leaked (the object zval, and the property zval), but only one possible root is found: the variable that was unset. When the root-buffer is full after 10,000 iterations (with a total of 10,000 possible roots), the garbage collection mechanism kicks in and frees the memory associated with those possible roots. This can very clearly be seen in the jagged memory-usage graph for PHP 5.3. After each 10,000 iterations, the mechanism kicks in and frees the memory associated with the circular referenced variables. The mechanism itself does not have to do a whole lot of work in this example, because the structure that is leaked is extremely simple. From the diagram, you see that the maximum memory usage in PHP 5.3 is about 9 Mb, whereas in PHP 5.2 the memory usage keeps increasing.
Run-Time Slowdowns
The second area where the garbage collection mechanism influences performance is the time taken when the garbage collection mechanism kicks in to free the "leaked" memory. In order to see how much this is, we slightly modify the previous script to allow for a larger number of iterations and the removal of the intermediate memory usage figures. The second script is here:
Przykład #2 GC performance influences
<?php
class Foo
{
public $var = '3.1415962654';
}
for ( $i = 0; $i <= 1000000; $i++ )
{
$a = new Foo;
$a->self = $a;
}
echo memory_get_peak_usage(), "\n";
?>
We will run this script two times, once with the zend.enable_gc setting turned on, and once with it turned off:
Przykład #3 Running the above script
time php -dzend.enable_gc=0 -dmemory_limit=-1 -n example2.php # and time php -dzend.enable_gc=1 -dmemory_limit=-1 -n example2.php
On my machine, the first command seems to take consistently about 10.7 seconds, whereas the second command takes about 11.4 seconds. This is a slowdown of about 7%. However, the maximum amount of memory used by the script is reduced by 98% from 931Mb to 10Mb. This benchmark is not very scientific, or even representative of real-life applications, but it does demonstrate the memory usage benefits that this garbage collection mechanism provides. The good thing is that the slowdown is always the same 7%, for this particular script, while the memory saving capabilities save more and more memory as more circular references are found during script execution.
PHP's Internal GC Statistics
It is possible to coax a little bit more information about how the garbage collection mechanism is run from within PHP. But in order to do so, you will have to re-compile PHP to enable the benchmark and data-collecting code. You will have to set the CFLAGS environment variable to -DGC_BENCH=1 prior to running ./configure with your desired options. The following sequence should do the trick:
Przykład #4 Recompiling PHP to enable GC benchmarking
export CFLAGS=-DGC_BENCH=1 ./config.nice make clean make
When you run the above example code again with the newly built PHP binary, you will see the following being shown after PHP has finished execution:
Przykład #5 GC statistics
GC Statistics
-------------
Runs: 110
Collected: 2072204
Root buffer length: 0
Root buffer peak: 10000
Possible Remove from Marked
Root Buffered buffer grey
-------- -------- ----------- ------
ZVAL 7175487 1491291 1241690 3611871
ZOBJ 28506264 1527980 677581 1025731
The most informative statistics are displayed in the first block. You can see here that the garbage collection mechanism ran 110 times, and in total, more than 2 million memory allocations were freed during those 110 runs. As soon as the garbage collection mechanism has run at least one time, the "Root buffer peak" is always 10000.
Conclusion
In general the garbage collector in PHP will only cause a slowdown when the cycle collecting algorithm actually runs, whereas in normal (smaller) scripts there should be no performance hit at all.
However, in the cases where the cycle collection mechanism does run for normal scripts, the memory reduction it will provide allows more of those scripts to run concurrently on your server, since not so much memory is used in total.
The benefits are most apparent for longer-running scripts, such as lengthy test suites or daemon scripts. Also, for » PHP-GTK applications that generally tend to run longer than scripts for the Web, the new mechanism should make quite a bit of a difference regarding memory leaks creeping in over time.
- Uwierzytelnianie HTTP w PHP
- Ciasteczka (cookies)
- Sessions
- Dealing with XForms
- Handling file uploads
- Korzystanie ze zdalnych plików
- Obsługa połączeń
- Stałe połączenia z bazami danych
- Tryb bezpieczny
- Command line usage — Using PHP from the command line
- Introduction
- Differences to other SAPIs
- Options — Command line options
- Usage — Executing PHP files
- I/O streams — Input/output streams
- Interactive shell
- Built-in web server
- Garbage Collection
Opis funkcji
Zobacz też: Wykaz i klasyfikacja rozszerzeń.
Wpływ na zachowanie PHP
Alternative PHP Cache
Wstęp
The Alternative PHP Cache (APC) is a free and open opcode cache for PHP. Its goal is to provide a free, open, and robust framework for caching and optimizing PHP intermediate code.
Instalacja/Konfiguracja
Spis treści
Wymagania
Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.
Instalacja
To rozszerzenie » PECL nie jest dołączane do PHP.
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/apc.
DLL z tym rozszerzeniem PECL można pobrać zarówno ze strony » PHP Downloads lub z » http://pecl4win.php.net/
Informacja: On Windows, APC needs a temp path to exist, and be writable by the web server. It checks the TMP, TEMP and USERPROFILE environment variables in that order and finally tries the WINDOWS directory if none of those are set.
Informacja: For more in-depth, highly technical implementation details, see the » developer-supplied TECHNOTES file .
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
Although the default APC settings are fine for many installations, serious users should consider tuning the following parameters.
There are two primary decisions to be made configuring APC. First, how much memory is going to be allocated to APC; and second, whether APC will check if a file has been modified on every request. The two ini directives that control these settings are apc.shm_size and apc.stat, respectively. Read the sections on these two directive carefully below.
Once the server is running, the apc.php script that is bundled with the extension should be copied somewhere into the docroot and viewed with a browser as it provides a detailed analysis of the internal workings of APC. If GD is enabled in PHP, it will even display some interesting graphs. The first thing to ensure, of course, is that it is actually caching files. If APC is working, the Cache full count number (on the left) will display the number of times the cache has reached maximum capacity and has had to forcefully clean any entries that haven't been accessed in the last apc.ttl seconds. This number is minimized in a well-configured cache. If the cache is constantly being filled, and thusly forcefully freed, the resulting churning will have disparaging effects on script performance. The easiest way to minimize this number is to allocate more memory for APC. Barring that, the apc.filters ought to be used to cache fewer scripts.
When APC is compiled with mmap support (Memory Mapping), it will use only one memory segment, unlike when APC is built with SHM (SysV Shared Memory) support that uses multiple memory segments. MMAP does not have a maximum limit like SHM does in /proc/sys/kernel/shmmax. In general MMAP support is recommeded because it will reclaim the memory faster when the webserver is restarted and all in all reduces memory allocation impact at startup.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| apc.enabled | "1" | PHP_INI_SYSTEM | PHP_INI_SYSTEM in APC 2. PHP_INI_ALL in APC <= 3.0.12. |
| apc.shm_segments | "1" | PHP_INI_SYSTEM | |
| apc.shm_size | "32M" | PHP_INI_SYSTEM | |
| apc.optimization | "0" | PHP_INI_ALL | PHP_INI_SYSTEM in APC 2. Removed in APC 3.0.13. |
| apc.num_files_hint | "1000" | PHP_INI_SYSTEM | |
| apc.user_entries_hint | "4096" | PHP_INI_SYSTEM | Available since APC 3.0.0. |
| apc.ttl | "0" | PHP_INI_SYSTEM | Available since APC 3.0.0. |
| apc.user_ttl | "0" | PHP_INI_SYSTEM | Available since APC 3.0.0. |
| apc.gc_ttl | "3600" | PHP_INI_SYSTEM | |
| apc.cache_by_default | "1" | PHP_INI_ALL | PHP_INI_SYSTEM in APC <= 3.0.12. Available since APC 3.0.0. |
| apc.filters | NULL | PHP_INI_SYSTEM | |
| apc.mmap_file_mask | NULL | PHP_INI_SYSTEM | |
| apc.slam_defense | "1" | PHP_INI_SYSTEM | Available since APC 3.0.0. Prior to APC 3.1.4, the default value was "0" (disabled). |
| apc.file_update_protection | "2" | PHP_INI_SYSTEM | Available since APC 3.0.6. |
| apc.enable_cli | "0" | PHP_INI_SYSTEM | Available since APC 3.0.7. |
| apc.max_file_size | "1M" | PHP_INI_SYSTEM | Available since APC 3.0.7. |
| apc.use_request_time | "1" | PHP_INI_ALL | Available since APC 3.1.3. |
| apc.stat | "1" | PHP_INI_SYSTEM | Available since APC 3.0.10. |
| apc.write_lock | "1" | PHP_INI_SYSTEM | Available since APC 3.0.11. |
| apc.report_autofilter | "0" | PHP_INI_SYSTEM | Available since APC 3.0.11. |
| apc.include_once_override | "0" | PHP_INI_SYSTEM | Available since APC 3.0.12. |
| apc.rfc1867 | "0" | PHP_INI_SYSTEM | Available since APC 3.0.13. |
| apc.rfc1867_prefix | "upload_" | PHP_INI_SYSTEM | |
| apc.rfc1867_name | "APC_UPLOAD_PROGRESS" | PHP_INI_SYSTEM | |
| apc.rfc1867_freq | "0" | PHP_INI_SYSTEM | |
| apc.rfc1867_ttl | "3600" | PHP_INI_SYSTEM | Available since APC 3.1.1. |
| apc.localcache | "0" | PHP_INI_SYSTEM | Available since APC 3.0.14. |
| apc.localcache.size | "512" | PHP_INI_SYSTEM | Available since APC 3.0.14. |
| apc.coredump_unmap | "0" | PHP_INI_SYSTEM | Available since APC 3.0.16. |
| apc.stat_ctime | "0" | PHP_INI_SYSTEM | Available since APC 3.0.13. |
| apc.preload_path | NULL | PHP_INI_SYSTEM | Available since APC 3.1.1. |
| apc.file_md5 | "0" | PHP_INI_SYSTEM | Available since APC 3.1.1. |
| apc.canonicalize | "1" | PHP_INI_SYSTEM | Available since APC 3.1.1. |
| apc.lazy_functions | 0 | PHP_INI_SYSTEM | Available since APC 3.1.3. |
| apc.lazy_classes | 0 | PHP_INI_SYSTEM | Available since APC 3.1.3. |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
apc.enabledboolean -
apc.enabled can be set to 0 to disable APC. This is primarily useful when APC is statically compiled into PHP, since there is no other way to disable it (when compiled as a DSO, the extension line in php.ini can just be commented-out).
-
apc.shm_segmentsinteger -
The number of shared memory segments to allocate for the compiler cache. If APC is running out of shared memory but apc.shm_size is set as high as the system allows, raising this value might prevent APC from exhausting its memory.
-
apc.shm_sizeinteger -
The size of each shared memory segment in MB. By default, some systems (including most BSD variants) have very low limits on the size of a shared memory segment.
-
apc.optimizationinteger -
The optimization level. Zero disables the optimizer, and higher values use more aggressive optimizations. Expect very modest speed improvements. This is experimental.
-
apc.num_files_hintinteger -
A "hint" about the number of distinct source files that will be included or requested on your web server. Set to zero or omit if unsure; this setting is mainly useful for sites that have many thousands of source files.
-
apc.user_entries_hintinteger -
Just like apc.num_files_hint, a "hint" about the number of distinct user cache variables to store. Set to zero or omit if not sure.
-
apc.ttlinteger -
The number of seconds a cache entry is allowed to idle in a slot in case this cache entry slot is needed by another entry. Leaving this at zero means that APC's cache could potentially fill up with stale entries while newer entries won't be cached. In the event of a cache running out of available memory, the cache will be completely expunged if ttl is equal to 0. Otherwise, if the ttl is greater than 0, APC will attempt to remove expired entries.
-
apc.user_ttlinteger -
The number of seconds a cache entry is allowed to idle in a slot in case this cache entry slot is needed by another entry. Leaving this at zero means that APC's cache could potentially fill up with stale entries while newer entries won't be cached. In the event of a cache running out of available memory, the cache will be completely expunged if ttl is equal to 0. Otherwise, if the ttl is greater than 0, APC will attempt to remove expired entries.
-
apc.gc_ttlinteger -
The number of seconds that a cache entry may remain on the garbage-collection list. This value provides a fail-safe in the event that a server process dies while executing a cached source file; if that source file is modified, the memory allocated for the old version will not be reclaimed until this TTL reached. Set to zero to disable this feature.
-
apc.cache_by_defaultboolean -
On by default, but can be set to off and used in conjunction with positive apc.filters so that files are only cached if matched by a positive filter.
-
apc.filtersstring -
A comma-separated list of POSIX extended regular expressions. If any pattern matches the source filename, the file will not be cached. Note that the filename used for matching is the one passed to include/require, not the absolute path. If the first character of the expression is a + then the expression will be additive in the sense that any files matched by the expression will be cached, and if the first character is a - then anything matched will not be cached. The - case is the default, so it can be left off.
-
apc.mmap_file_maskstring -
If compiled with MMAP support by using --enable-mmap this is the mktemp-style file_mask to pass to the mmap module for determining whether your mmap'ed memory region is going to be file-backed or shared memory backed. For straight file-backed mmap, set it to something like /tmp/apc.XXXXXX (exactly 6 Xs). To use POSIX-style shm_open/mmap put a .shm somewhere in your mask. e.g. /apc.shm.XXXXXX You can also set it to /dev/zero to use your kernel's /dev/zero interface to anonymous mmap'ed memory. Leaving it undefined will force an anonymous mmap.
-
apc.slam_defenseinteger -
On very busy servers whenever you start the server or modify files you can create a race of many processes all trying to cache the same file at the same time. This option sets the percentage of processes that will skip trying to cache an uncached file. Or think of it as the probability of a single process to skip caching. For example, setting apc.slam_defense to 75 would mean that there is a 75% chance that the process will not cache an uncached file. So, the higher the setting the greater the defense against cache slams. Setting this to 0 disables this feature.
Deprecated by apc.write_lock.
-
apc.file_update_protectioninteger -
When a file is modified on a live web server it really ought to be done in an atomic manner. That is, written to a temporary file and renamed (mv) the file into its permanent position when it is ready. Many text editors, cp, tar and other such programs don't do this. This means that there is a chance that a file is accessed (and cached) while it is still being written to. This apc.file_update_protection setting puts a delay on caching brand new files. The default is 2 seconds, which means that if the modification timestamp (mtime) on a file shows that it is less than 2 seconds old when it is accessed, it will not be cached. The unfortunate person who accessed this half-written file will still see weirdness, but at least it won't persist. If all of the webserver's files are atomically updated, via some method like rsync (which updates correctly), this protection can be disabled by setting this directive to 0. If the system is flooded with i/o and some update procedures are taking longer than 2 seconds, this setting should be increased to enable the protection on those slower update operations.
-
apc.enable_cliinteger -
Mostly for testing and debugging. Setting this enables APC for the CLI version of PHP. Under normal circumstances, it is not ideal to create, populate and destroy the APC cache on every CLI request, but for various test scenarios it is useful to be able to enable APC for the CLI version of PHP easily.
-
apc.max_file_sizeinteger -
Prevent files larger than this value from getting cached. Defaults to 1M.
-
apc.statinteger -
Be careful changing this setting. This defaults to on, forcing APC to stat (check) the script on each request to determine if it has been modified. If it has been modified it will recompile and cache the new version. If this setting is off, APC will not check, which usually means that to force APC to recheck files, the web server will have to be restarted or the cache will have to be manually cleared. Note that FastCGI web server configurations may not clear the cache on restart. On a production server where the script files rarely change, a significant performance boost can be achieved by disabled stats.
For included/required files this option applies as well, but note that for relative path includes (any path that doesn't start with / on Unix) APC has to check in order to uniquely identify the file. If you use absolute path includes APC can skip the stat and use that absolute path as the unique identifier for the file.
-
apc.write_lockboolean -
On busy servers, when the web server is first started, or when many files have been modified at the same time, APC may try to compile and cache the same file multiple times. Write_lock guarantees that only one process will attempt to compile and cache an uncached script. The other processes attempting to use the script will run without using the opcode cache, rather than locking and waiting for the cache to prime.
-
apc.report_autofilterboolean -
Logs any scripts that were automatically excluded from being cached due to early/late binding issues.
-
apc.include_once_overrideboolean -
Optimize include_once() and require_once() calls and avoid the expensive system calls used.
OstrzeżenieThis feature is EXPERIMENTAL. The behaviour of this directive, its name, and surrounding documentation may change without notice in a future release of APC. This feature should be used at your own risk.
-
apc.rfc1867boolean -
RFC1867 File Upload Progress hook handler is only available if APC was compiled against PHP 5.2.0 or later. When enabled, any file uploads which includes a field called APC_UPLOAD_PROGRESS before the file field in an upload form will cause APC to automatically create an upload_key user cache entry where key is the value of the APC_UPLOAD_PROGRESS form entry.
Note that the hidden field specified by APC_UPLOAD_PROGRESS must come before the file field, otherwise the upload progress will not work correctly.
Note that the file upload tracking is not threadsafe at this point, so new uploads that happen while a previous one is still going will disable the tracking for the previous.
Note that the rate is only available once all file transfers are completed.
Przykład #1 An apc.rfc1867 example
<?php
print_r(apc_fetch("upload_$_POST[APC_UPLOAD_PROGRESS]"));
?>Powyższy przykład wyświetli coś podobnego do:
Array ( [total] => 1142543 [current] => 1142543 [rate] => 1828068.8 [filename] => test [name] => file [temp_filename] => /tmp/php8F [cancel_upload] => 0 [done] => 1 ) -
apc.rfc1867_prefixstring -
Key prefix to use for the user cache entry generated by rfc1867 upload progress functionality.
-
apc.rfc1867_namestring -
Specify the hidden form entry name that activates APC upload progress and specifies the user cache key suffix.
-
apc.rfc1867_freqstring -
The frequency that updates should be made to the user cache entry for upload progress. This can take the form of a percentage of the total file size or a size in bytes optionally suffixed with "k", "m", or "g" for kilobytes, megabytes, or gigabytes respectively (case insensitive). A setting of 0 updates as often as possible, which may cause slower uploads.
-
apc.rfc1867_ttlbool -
TTL for rfc1867 entries.
-
apc.localcacheboolean -
This enables a lock-free local process shadow-cache which reduces lock contention when the cache is being written to.
-
apc.localcache.sizeinteger -
The size of the local process shadow-cache, should be set to a sufficiently large value, approximately half of apc.num_files_hint.
-
apc.coredump_unmapboolean -
Enables APC handling of signals, such as SIGSEGV, that write core files when signaled. When these signals are received, APC will attempt to unmap the shared memory segment in order to exclude it from the core file. This setting may improve system stability when fatal signals are received and a large APC shared memory segment is configured.
OstrzeżenieThis feature is potentially dangerous. Unmapping the shared memory segment in a fatal signal handler may cause undefined behaviour if a fatal error occurs.
Informacja:
Although some kernels may provide a facility to ignore various types of shared memory when generating a core dump file, these implementations may also ignore important shared memory segments such as the Apache scoreboard.
-
apc.stat_ctimeinteger -
Verification with ctime will avoid problems caused by programs such as svn or rsync by making sure inodes haven't changed since the last stat. APC will normally only check mtime.
-
apc.canonicalizebool -
If on, then relative paths are canonicalized in no-stat mode. If set, then files included via stream wrappers can not be cached as realpath() does not support stream wrappers.
-
apc.preload_pathstring -
-
apc.use_request_timebool -
Use the SAPI request start time for TTL.
-
apc.file_md5bool -
Records a md5 hash of files.
-
apc.lazy_functionsinteger -
Enables lazy loading for functions.
-
apc.lazy_classesinteger -
Enables lazy loading for classes.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
-
APC_BIN_VERIFY_CRC32(integer) -
APC_BIN_VERIFY_MD5(integer) -
APC_ITER_ALL(integer) -
APC_ITER_ATIME(integer) -
APC_ITER_CTIME(integer) -
APC_ITER_DEVICE(integer) -
APC_ITER_DTIME(integer) -
APC_ITER_FILENAME(integer) -
APC_ITER_INODE(integer) -
APC_ITER_KEY(integer) -
APC_ITER_MD5(integer) -
APC_ITER_MEM_SIZE(integer) -
APC_ITER_MTIME(integer) -
APC_ITER_NONE(integer) -
APC_ITER_NUM_HITS(integer) -
APC_ITER_REFCOUNT(integer) -
APC_ITER_TTL(integer) -
APC_ITER_TYPE(integer) -
APC_ITER_VALUE(integer) -
APC_LIST_ACTIVE(integer) -
APC_LIST_DELETED(integer)
APC Funkcje
apc_add
(PECL apc >= 3.0.13)
apc_add — Cache a new variable in the data store
Opis
Caches a variable in the data store, only if it's not already stored.
Informacja: Unlike many other mechanisms in PHP, variables stored using apc_add() will persist between requests (until the value is removed from the cache).
Parametry
-
key -
Store the variable using this name.
keys are cache-unique, so attempting to use apc_add() to store data with a key that already exists will not overwrite the existing data, and will instead returnFALSE. (This is the only difference between apc_add() and apc_store().) -
var -
The variable to store
-
ttl -
Time To Live; store
varin the cache forttlseconds. After thettlhas passed, the stored variable will be expunged from the cache (on the next request). If nottlis supplied (or if thettlis 0), the value will persist until it is removed from the cache manually, or otherwise fails to exist in the cache (clear, restart, etc.). -
values -
Names in key, variables in value.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Second syntax returns array with error keys.
Przykłady
Przykład #1 A apc_add() example
<?php
$bar = 'BAR';
apc_add('foo', $bar);
var_dump(apc_fetch('foo'));
echo "\n";
$bar = 'NEVER GETS SET';
apc_add('foo', $bar);
var_dump(apc_fetch('foo'));
echo "\n";
?>
Powyższy przykład wyświetli:
string(3) "BAR" string(3) "BAR"
Zobacz też:
- apc_store() - Cache a variable in the data store
- apc_fetch() - Fetch a stored variable from the cache
- apc_delete() - Removes a stored variable from the cache
apc_bin_dump
(PECL apc >= 3.1.4)
apc_bin_dump — Get a binary dump of the given files and user variables
Opis
$files
[, array $user_vars
]] )
Returns a binary dump of the given files and user variables from the APC cache.
A NULL for files or user_vars signals a dump of every entry, whereas array() will dump
nothing.
Parametry
Zwracane wartości
Returns a binary dump of the given files and user variables from the APC cache,
FALSE if APC is not enabled, or NULL if an unknown error is encountered.
Zobacz też:
- apc_bin_dumpfile() - Output a binary dump of cached files and user variables to a file
- apc_bin_load() - Load a binary dump into the APC file/user cache
apc_bin_dumpfile
(PECL apc >= 3.1.4)
apc_bin_dumpfile — Output a binary dump of cached files and user variables to a file
Opis
$files
, array $user_vars
, string $filename
[, int $flags = 0
[, resource $context
]] )Outputs a binary dump of the given files and user variables from the APC cache to the named file.
Parametry
-
files -
The file names being dumped.
-
user_vars -
The user variables being dumped.
-
filename -
The filename where the dump is being saved.
-
flags -
Flags passed to the
filenamestream. See the file_put_contents() documentation for details. -
context -
The context passed to the
filenamestream. See the file_put_contents() documentation for details.
Zwracane wartości
The number of bytes written to the file, otherwise
FALSE if APC is not enabled, filename is an invalid file name,
filename can't be opened, the file dump can't be completed
(e.g., the hard drive is out of disk space), or an unknown error was encountered.
Zobacz też:
- apc_bin_dump() - Get a binary dump of the given files and user variables
- apc_bin_load() - Load a binary dump into the APC file/user cache
apc_bin_load
(PECL apc >= 3.1.4)
apc_bin_load — Load a binary dump into the APC file/user cache
Opis
$data
[, int $flags = 0
] )Loads the given binary dump into the APC file/user cache.
Parametry
-
data -
The binary dump being loaded, likely from apc_bin_dump().
-
flags -
Either
APC_BIN_VERIFY_CRC32,APC_BIN_VERIFY_MD5, or both.
Zwracane wartości
Returns TRUE if the binary dump data was loaded
with success, otherwise FALSE is returned. FALSE is returned if APC
is not enabled, or if the data is not a valid APC
binary dump (e.g., unexpected size).
Przykłady
Przykład #1 apc_bin_load() example
<?php
$data = apc_bin_dump(NULL, NULL);
apc_bin_load($data, APC_BIN_VERIFY_MD5 | APC_BIN_VERIFY_CRC32);
?>
Zobacz też:
- apc_bin_dump() - Get a binary dump of the given files and user variables
- apc_bin_loadfile() - Load a binary dump from a file into the APC file/user cache
apc_bin_loadfile
(PECL apc >= 3.1.4)
apc_bin_loadfile — Load a binary dump from a file into the APC file/user cache
Opis
$filename
[, resource $context
[, int $flags
]] )Loads a binary dump from a file into the APC file/user cache.
Parametry
-
filename -
The file name containing the dump, likely from apc_bin_dumpfile().
-
context -
The files context.
-
flags -
Either
APC_BIN_VERIFY_CRC32,APC_BIN_VERIFY_MD5, or both.
Zwracane wartości
Returns TRUE on success, otherwise FALSE Reasons it may return FALSE include
APC is not enabled, filename is an invalid file name or empty,
filename can't be opened, the file dump can't be completed, or
if the data is not a valid APC binary dump (e.g., unexpected
size).
Zobacz też:
- apc_bin_dumpfile() - Output a binary dump of cached files and user variables to a file
- apc_bin_load() - Load a binary dump into the APC file/user cache
apc_cache_info
(PECL apc >= 2.0.0)
apc_cache_info — Retrieves cached information from APC's data store
Opis
$cache_type
[, bool $limited = false
]] )Retrieves cached information and meta-data from APC's data store.
Parametry
-
cache_type -
If
cache_typeis "user", information about the user cache will be returned.If
cache_typeis "filehits", information about which files have been served from the bytecode cache for the current request will be returned. This feature must be enabled at compile time using --enable-filehits .If an invalid or no
cache_typeis specified, information about the system cache (cached files) will be returned. -
limited -
If
limitedisTRUE, the return value will exclude the individual list of cache entries. This is useful when trying to optimize calls for statistics gathering.
Zwracane wartości
Array of cached data (and meta-data) lub FALSE w przypadku niepowodzenia
Informacja: apc_cache_info() will raise a warning if it is unable to retrieve APC cache data. This typically occurs when APC is not enabled.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 3.0.11 |
The limited parameter was introduced.
|
| 3.0.16 |
The "filehits" option for the
cache_type parameter was introduced.
|
Przykłady
Przykład #1 A apc_cache_info() example
<?php
print_r(apc_cache_info());
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[num_slots] => 2000
[ttl] => 0
[num_hits] => 9
[num_misses] => 3
[start_time] => 1123958803
[cache_list] => Array
(
[0] => Array
(
[filename] => /path/to/apc_test.php
[device] => 29954
[inode] => 1130511
[type] => file
[num_hits] => 1
[mtime] => 1123960686
[creation_time] => 1123960696
[deletion_time] => 0
[access_time] => 1123962864
[ref_count] => 1
[mem_size] => 677
)
[1] => Array (...iterates for each cached file)
)
Zobacz też:
- APC configuration directives
- APCIterator::getTotalSize() - Get total cache size
- APCIterator::getTotalHits() - Get total cache hits
- APCIterator::getTotalCount() - Get total count
apc_cas
(PECL apc >= 3.1.1)
apc_cas — Updates an old value with a new value
Opis
$key
, int $old
, int $new
)
apc_cas() updates an already existing integer value if the
old parameter matches the currently stored value
with the value of the new parameter.
Parametry
-
key -
The key of the value being updated.
-
old -
The old value (the value currently stored).
-
new -
The new value to update to.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 apc_cas() example
<?php
apc_store('foobar', 2);
echo '$foobar = 2', PHP_EOL;
echo '$foobar == 1 ? 2 : 1 = ', (apc_cas('foobar', 1, 2) ? 'ok' : 'fail'), PHP_EOL;
echo '$foobar == 2 ? 1 : 2 = ', (apc_cas('foobar', 2, 1) ? 'ok' : 'fail'), PHP_EOL;
echo '$foobar = ', apc_fetch('foobar'), PHP_EOL;
echo '$f__bar == 1 ? 2 : 1 = ', (apc_cas('f__bar', 1, 2) ? 'ok' : 'fail'), PHP_EOL;
apc_store('perfection', 'xyz');
echo '$perfection == 2 ? 1 : 2 = ', (apc_cas('perfection', 2, 1) ? 'ok' : 'epic fail'), PHP_EOL;
echo '$foobar = ', apc_fetch('foobar'), PHP_EOL;
?>
Powyższy przykład wyświetli coś podobnego do:
$foobar = 2 $foobar == 1 ? 2 : 1 = fail $foobar == 2 ? 1 : 2 = ok $foobar = 1 $f__bar == 1 ? 2 : 1 = fail $perfection == 2 ? 1 : 2 = epic fail $foobar = 1
Zobacz też:
- apc_dec() - Decrease a stored number
- apc_store() - Cache a variable in the data store
apc_clear_cache
(PECL apc >= 2.0.0)
apc_clear_cache — Clears the APC cache
Opis
$cache_type
] )Clears the user/system cache.
Parametry
-
cache_type -
If
cache_typeis "user", the user cache will be cleared; otherwise, the system cache (cached files) will be cleared.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
apc_compile_file
(PECL apc >= 3.0.13)
apc_compile_file — Stores a file in the bytecode cache, bypassing all filters.
Opis
Stores a file in the bytecode cache, bypassing all filters.
Parametry
-
filename -
Full or relative path to a PHP file that will be compiled and stored in the bytecode cache.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- apc_bin_dumpfile() - Output a binary dump of cached files and user variables to a file
- apc_bin_loadfile() - Load a binary dump from a file into the APC file/user cache
apc_dec
(PECL apc >= 3.1.1)
apc_dec — Decrease a stored number
Opis
$key
[, int $step = 1
[, bool &$success
]] )Decreases a stored integer value.
Parametry
-
key -
The key of the value being decreased.
-
step -
The step, or value to decrease.
-
success -
Optionally pass the success or fail boolean value to this referenced variable.
Zwracane wartości
Returns the current value of key's value on success,
lub FALSE w przypadku niepowodzenia
Przykłady
Przykład #1 apc_dec() example
<?php
echo "Let's do something with success", PHP_EOL;
apc_store('anumber', 42);
echo apc_fetch('anumber'), PHP_EOL;
echo apc_dec('anumber'), PHP_EOL;
echo apc_dec('anumber', 10), PHP_EOL;
echo apc_dec('anumber', 10, $success), PHP_EOL;
var_dump($success);
echo "Now, let's fail", PHP_EOL, PHP_EOL;
apc_store('astring', 'foo');
$ret = apc_dec('astring', 1, $fail);
var_dump($ret);
var_dump($fail);
?>
Powyższy przykład wyświetli coś podobnego do:
Let's do something with success 42 41 31 21 bool(true) Now, let's fail bool(false) bool(false)
Zobacz też:
- apc_inc() - Increase a stored number
apc_define_constants
(PECL apc >= 3.0.0)
apc_define_constants — Defines a set of constants for retrieval and mass-definition
Opis
$key
, array $constants
[, bool $case_sensitive = true
] )define() is notoriously slow. Since the main benefit of APC is to increase the performance of scripts/applications, this mechanism is provided to streamline the process of mass constant definition. However, this function does not perform as well as anticipated.
For a better-performing solution, try the » hidef extension from PECL.
Informacja: To remove a set of stored constants (without clearing the entire cache), an empty array may be passed as the
constantsparameter, effectively clearing the stored value(s).
Parametry
-
key -
The
keyserves as the name of the constant set being stored. Thiskeyis used to retrieve the stored constants in apc_load_constants(). -
constants -
An associative array of constant_name => value pairs. The constant_name must follow the normal constant naming rules. value must evaluate to a scalar value.
-
case_sensitive -
The default behaviour for constants is to be declared case-sensitive; i.e. CONSTANT and Constant represent different values. If this parameter evaluates to
FALSEthe constants will be declared as case-insensitive symbols.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 apc_define_constants() example
<?php
$constants = array(
'ONE' => 1,
'TWO' => 2,
'THREE' => 3,
);
apc_define_constants('numbers', $constants);
echo ONE, TWO, THREE;
?>
Powyższy przykład wyświetli:
123
Zobacz też:
- apc_load_constants() - Loads a set of constants from the cache
- define() - Defines a named constant
- constant() - Returns the value of a constant
- Or the PHP constants reference
apc_delete_file
(PECL apc >= 3.1.1)
apc_delete_file — Deletes files from the opcode cache
Parametry
-
keys -
The files to be deleted. Accepts a string, array of strings, or an APCIterator object.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Or if keys is an array, then
an empty array is returned on success, or an array of failed files
is returned.
Przykłady
Przykład #1 apc_delete_file() example
<?php
$filename = 'file.php';
if (apc_compile_file($filename)) {
if (apc_delete_file($filename)) {
echo "Successfully deleted file $filename from APC cache.", PHP_EOL;
}
}
if (apc_compile_file($filename)) {
if ($good = apc_delete_file(array($filename, 'donotexist.php'))) {
var_dump($good);
}
}
$bad = apc_delete_file('donotexist.php');
var_dump($bad);
?>
Powyższy przykład wyświetli coś podobnego do:
Successfully deleted file file.php from APC cache.
[Mon May 24 09:30:33 2010] [apc-warning] Could not stat file donotexist.php, unable to delete from cache. in /tmp/test.php on line 13.
array(1) {
[0]=>
string(14) "donotexist.php"
}
[Mon May 24 09:30:33 2010] [apc-warning] Could not stat file donotexist.php, unable to delete from cache. in /tmp/test.php on line 18.
bool(false)
Zobacz też:
- apc_clear_cache() - Clears the APC cache
- apc_delete() - Removes a stored variable from the cache
- apc_exists() - Checks if APC key exists
apc_delete
(PECL apc >= 3.0.0)
apc_delete — Removes a stored variable from the cache
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 A apc_delete() example
<?php
$bar = 'BAR';
apc_store('foo', $bar);
apc_delete('foo');
// this is obviously useless in this form
?>
Zobacz też:
- apc_store() - Cache a variable in the data store
- apc_fetch() - Fetch a stored variable from the cache
apc_exists
(PECL apc >= 3.1.4)
apc_exists — Checks if APC key exists
Zwracane wartości
Returns TRUE if the key exists, otherwise FALSE Or if an
array was passed to keys, then
an array is returned that contains all existing keys, or an empty
array if none exist.
Przykłady
Przykład #1 apc_exists() example
<?php
$fruit = 'apple';
$veggie = 'carrot';
apc_store('foo', $fruit);
apc_store('bar', $veggie);
if (apc_exists('foo')) {
echo "Foo exists: ";
echo apc_fetch('foo');
} else {
echo "Foo does not exist";
}
echo PHP_EOL;
if (apc_exists('baz')) {
echo "Baz exists.";
} else {
echo "Baz does not exist";
}
echo PHP_EOL;
$ret = apc_exists(array('foo', 'donotexist', 'bar'));
var_dump($ret);
?>
Powyższy przykład wyświetli coś podobnego do:
Foo exists: apple
Baz does not exist
array(2) {
["foo"]=>
bool(true)
["bar"]=>
bool(true)
}
Zobacz też:
- apc_cache_info() - Retrieves cached information from APC's data store
- apc_fetch() - Fetch a stored variable from the cache
apc_fetch
(PECL apc >= 3.0.0)
apc_fetch — Fetch a stored variable from the cache
Parametry
-
key -
The
keyused to store the value (with apc_store()). If an array is passed then each element is fetched and returned. -
success -
Set to
TRUEin success andFALSEin failure.
Zwracane wartości
The stored variable or array of variables on success; FALSE on failure
Przykłady
Przykład #1 A apc_fetch() example
<?php
$bar = 'BAR';
apc_store('foo', $bar);
var_dump(apc_fetch('foo'));
?>
Powyższy przykład wyświetli:
string(3) "BAR"
Rejestr zmian
| Wersja | Opis |
|---|---|
| 3.0.17 |
The success parameter was added.
|
Zobacz też:
- apc_store() - Cache a variable in the data store
- apc_delete() - Removes a stored variable from the cache
- APCIterator
apc_inc
(PECL apc >= 3.1.1)
apc_inc — Increase a stored number
Opis
$key
[, int $step = 1
[, bool &$success
]] )Increases a stored number.
Parametry
-
key -
The key of the value being increased.
-
step -
The step, or value to increase.
-
success -
Optionally pass the success or fail boolean value to this referenced variable.
Zwracane wartości
Returns the current value of key's value on success,
lub FALSE w przypadku niepowodzenia
Przykłady
Przykład #1 apc_inc() example
<?php
echo "Let's do something with success", PHP_EOL;
apc_store('anumber', 42);
echo apc_fetch('anumber'), PHP_EOL;
echo apc_inc('anumber'), PHP_EOL;
echo apc_inc('anumber', 10), PHP_EOL;
echo apc_inc('anumber', 10, $success), PHP_EOL;
var_dump($success);
echo "Now, let's fail", PHP_EOL, PHP_EOL;
apc_store('astring', 'foo');
$ret = apc_inc('astring', 1, $fail);
var_dump($ret);
var_dump($fail);
?>
Powyższy przykład wyświetli coś podobnego do:
42 43 53 63 bool(true) Now, let's fail bool(false) bool(false)
Zobacz też:
- apc_dec() - Decrease a stored number
apc_load_constants
(PECL apc >= 3.0.0)
apc_load_constants — Loads a set of constants from the cache
Opis
$key
[, bool $case_sensitive = true
] )Loads a set of constants from the cache.
Parametry
-
key -
The name of the constant set (that was stored with apc_define_constants()) to be retrieved.
-
case_sensitive -
The default behaviour for constants is to be declared case-sensitive; i.e. CONSTANT and Constant represent different values. If this parameter evaluates to
FALSEthe constants will be declared as case-insensitive symbols.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 apc_load_constants() example
<?php
$constants = array(
'ONE' => 1,
'TWO' => 2,
'THREE' => 3,
);
apc_define_constants('numbers', $constants);
apc_load_constants('numbers');
echo ONE, TWO, THREE;
?>
Powyższy przykład wyświetli:
123
Zobacz też:
- apc_define_constants() - Defines a set of constants for retrieval and mass-definition
- define() - Defines a named constant
- constant() - Returns the value of a constant
- Or the PHP constants reference
apc_sma_info
(PECL apc >= 2.0.0)
apc_sma_info — Retrieves APC's Shared Memory Allocation information
Opis
$limited = false
] )Retrieves APC's Shared Memory Allocation information.
Parametry
-
limited -
When set to
FALSE(default) apc_sma_info() will return a detailed information about each segment.
Zwracane wartości
Array of Shared Memory Allocation data; FALSE on failure.
Przykłady
Przykład #1 A apc_sma_info() example
<?php
print_r(apc_sma_info());
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[num_seg] => 1
[seg_size] => 31457280
[avail_mem] => 31448408
[block_lists] => Array
(
[0] => Array
(
[0] => Array
(
[size] => 31448408
[offset] => 8864
)
)
)
)
apc_store
(PECL apc >= 3.0.0)
apc_store — Cache a variable in the data store
Opis
Cache a variable in the data store.
Informacja: Unlike many other mechanisms in PHP, variables stored using apc_store() will persist between requests (until the value is removed from the cache).
Parametry
-
key -
Store the variable using this name.
keys are cache-unique, so storing a second value with the samekeywill overwrite the original value. -
var -
The variable to store
-
ttl -
Time To Live; store
varin the cache forttlseconds. After thettlhas passed, the stored variable will be expunged from the cache (on the next request). If nottlis supplied (or if thettlis 0), the value will persist until it is removed from the cache manually, or otherwise fails to exist in the cache (clear, restart, etc.). -
values -
Names in key, variables in value.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Second syntax returns array with error keys.
Przykłady
Przykład #1 A apc_store() example
<?php
$bar = 'BAR';
apc_store('foo', $bar);
var_dump(apc_fetch('foo'));
?>
Powyższy przykład wyświetli:
string(3) "BAR"
Zobacz też:
- apc_add() - Cache a new variable in the data store
- apc_fetch() - Fetch a stored variable from the cache
- apc_delete() - Removes a stored variable from the cache
Spis treści
- apc_add — Cache a new variable in the data store
- apc_bin_dump — Get a binary dump of the given files and user variables
- apc_bin_dumpfile — Output a binary dump of cached files and user variables to a file
- apc_bin_load — Load a binary dump into the APC file/user cache
- apc_bin_loadfile — Load a binary dump from a file into the APC file/user cache
- apc_cache_info — Retrieves cached information from APC's data store
- apc_cas — Updates an old value with a new value
- apc_clear_cache — Clears the APC cache
- apc_compile_file — Stores a file in the bytecode cache, bypassing all filters.
- apc_dec — Decrease a stored number
- apc_define_constants — Defines a set of constants for retrieval and mass-definition
- apc_delete_file — Deletes files from the opcode cache
- apc_delete — Removes a stored variable from the cache
- apc_exists — Checks if APC key exists
- apc_fetch — Fetch a stored variable from the cache
- apc_inc — Increase a stored number
- apc_load_constants — Loads a set of constants from the cache
- apc_sma_info — Retrieves APC's Shared Memory Allocation information
- apc_store — Cache a variable in the data store
The APCIterator class
(PECL apc >= 3.1.1)
Wstęp
The APCIterator class makes it easier to iterate over large APC caches. This is helpful as it allows iterating over large caches in steps, while grabbing a defined number of entries per lock instance, so it frees the cache locks for other activities rather than hold up the entire cache to grab 100 (the default) entries. Also, using regular expression matching is more efficient as it's been moved to the C level.
Krótki opis klasy
$cache
[, mixed $search = null
[, int $format
[, int $chunk_size = 100
[, int $list
]]]] )APCIterator::__construct
(PECL apc >= 3.1.1)
APCIterator::__construct — Constructs an APCIterator iterator object
Opis
$cache
[, mixed $search = null
[, int $format
[, int $chunk_size = 100
[, int $list
]]]] )Constructs an APCIterator object.
Parametry
-
cache -
The cache type, which will be user or file.
-
search -
A PCRE regular expression that matches against APC key names, either as a string for a single regular expression, or as an array of regular expressions. Or, optionally pass in
NULLto skip the search. -
format -
The desired format, as configured with one ore more of the APC_ITER_* constants.
-
chunk_size -
The chunk size. Must be a value greater than 0. The default value is 100.
-
list -
The type to list. Either pass in
APC_LIST_ACTIVEorAPC_LIST_DELETED.
Zwracane wartości
An APCIterator object on success,
or NULL on failure.
Przykłady
Przykład #1 A APCIterator::__construct() example
<?php
foreach (new APCIterator('user', '/^counter\./') as $counter) {
echo "$counter[key]: $counter[value]\n";
apc_dec($counter['key'], $counter['value']);
}
?>
Zobacz też:
- apc_exists() - Checks if APC key exists
- apc_cache_info() - Retrieves cached information from APC's data store
APCIterator::current
(PECL apc >= 3.1.1)
APCIterator::current — Get current item
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the current item on success, or FALSE if no
more items or exist, or on failure.
Zobacz też:
- APCIterator::next() - Move pointer to next item
- Iterator::current() - Return the current element
APCIterator::getTotalCount
(PECL apc >= 3.1.1)
APCIterator::getTotalCount — Get total count
Opis
Get the total count.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
The total count.
Zobacz też:
- APCIterator::getTotalHits() - Get total cache hits
- APCIterator::getTotalSize() - Get total cache size
- apc_cache_info() - Retrieves cached information from APC's data store
APCIterator::getTotalHits
(PECL apc >= 3.1.1)
APCIterator::getTotalHits — Get total cache hits
Opis
Gets the total number of cache hits.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
The number of hits on success, or FALSE on failure.
Zobacz też:
- APCIterator::getTotalCount() - Get total count
- APCIterator::getTotalSize() - Get total cache size
- apc_cache_info() - Retrieves cached information from APC's data store
APCIterator::getTotalSize
(PECL apc >= 3.1.1)
APCIterator::getTotalSize — Get total cache size
Opis
Gets the total cache size.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
The total cache size.
Zobacz też:
- APCIterator::getTotalCount() - Get total count
- APCIterator::getTotalHits() - Get total cache hits
- apc_cache_info() - Retrieves cached information from APC's data store
APCIterator::key
(PECL apc >= 3.1.1)
APCIterator::key — Get iterator key
Opis
Gets the current iterator key.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the key on success, or FALSE upon failure.
Zobacz też:
- APCIterator::current() - Get current item
- Iterator::key() - Return the key of the current element
APCIterator::next
(PECL apc >= 3.1.1)
APCIterator::next — Move pointer to next item
Opis
Moves the iterator pointer to the next element.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- APCIterator::current() - Get current item
- APCIterator::rewind() - Rewinds iterator
- Iterator::next() - Move forward to next element
APCIterator::rewind
(PECL apc >= 3.1.1)
APCIterator::rewind — Rewinds iterator
Opis
Rewinds back the iterator to the first element.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Nie jest zwracana żadna wartość.
Zobacz też:
- APCIterator::next() - Move pointer to next item
- Iterator::next() - Move forward to next element
APCIterator::valid
(PECL apc >= 3.1.1)
APCIterator::valid — Checks if current position is valid
Opis
Checks if the current iterator position is valid.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns TRUE if the current iterator position is valid, otherwise FALSE.
Zobacz też:
- APCIterator::current() - Get current item
- Iterator::valid() - Checks if current position is valid
Spis treści
- APCIterator::__construct — Constructs an APCIterator iterator object
- APCIterator::current — Get current item
- APCIterator::getTotalCount — Get total count
- APCIterator::getTotalHits — Get total cache hits
- APCIterator::getTotalSize — Get total cache size
- APCIterator::key — Get iterator key
- APCIterator::next — Move pointer to next item
- APCIterator::rewind — Rewinds iterator
- APCIterator::valid — Checks if current position is valid
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- APC Funkcje
- apc_add — Cache a new variable in the data store
- apc_bin_dump — Get a binary dump of the given files and user variables
- apc_bin_dumpfile — Output a binary dump of cached files and user variables to a file
- apc_bin_load — Load a binary dump into the APC file/user cache
- apc_bin_loadfile — Load a binary dump from a file into the APC file/user cache
- apc_cache_info — Retrieves cached information from APC's data store
- apc_cas — Updates an old value with a new value
- apc_clear_cache — Clears the APC cache
- apc_compile_file — Stores a file in the bytecode cache, bypassing all filters.
- apc_dec — Decrease a stored number
- apc_define_constants — Defines a set of constants for retrieval and mass-definition
- apc_delete_file — Deletes files from the opcode cache
- apc_delete — Removes a stored variable from the cache
- apc_exists — Checks if APC key exists
- apc_fetch — Fetch a stored variable from the cache
- apc_inc — Increase a stored number
- apc_load_constants — Loads a set of constants from the cache
- apc_sma_info — Retrieves APC's Shared Memory Allocation information
- apc_store — Cache a variable in the data store
- APCIterator — The APCIterator class
- APCIterator::__construct — Constructs an APCIterator iterator object
- APCIterator::current — Get current item
- APCIterator::getTotalCount — Get total count
- APCIterator::getTotalHits — Get total cache hits
- APCIterator::getTotalSize — Get total cache size
- APCIterator::key — Get iterator key
- APCIterator::next — Move pointer to next item
- APCIterator::rewind — Rewinds iterator
- APCIterator::valid — Checks if current position is valid
Advanced PHP debugger
Wstęp
APD is the Advanced PHP Debugger. It was written to provide profiling and debugging capabilities for PHP code, as well as to provide the ability to print out a full stack backtrace. APD supports interactive debugging, but by default it writes data to trace files. It also offers event based logging so that varying levels of information (including function calls, arguments passed, timings, etc.) can be turned on or off for individual scripts.
APD is a Zend Extension, modifying the way the internals of PHP handle function calls, and thus may or may not be compatible with other Zend Extensions (for example Zend Optimizer).
Instalacja/Konfiguracja
Spis treści
Wymagania
Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.
Instalacja
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/apd.
DLL z tym rozszerzeniem PECL można pobrać zarówno ze strony » PHP Downloads lub z » http://pecl4win.php.net/
In your INI file, add the following lines:
zend_extension = /absolute/path/to/apd.so apd.dumpdir = /absolute/path/to/trace/directory apd.statement_tracing = 0
Depending on your PHP build, the zend_extension directive can be one of the following:
zend_extension (non ZTS, non debug build) zend_extension_ts ( ZTS, non debug build) zend_extension_debug (non ZTS, debug build) zend_extension_debug_ts ( ZTS, debug build)
Building on Win32
To build APD under Windows you need a working PHP compilation environment as described on http://php.net/ -- basically, it requires you to have Microsoft Visual C++, win32build.zip, bison/flex, and some know how to get it to work. Also ensure that adp.dsp has DOS line endings; if it has unix line endings, Microsoft Visual C++ will complain about it.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| apd.dumpdir | NULL | PHP_INI_ALL | |
| apd.statement_tracing | "0" | PHP_INI_ALL | Available since apd 0.9. |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
apd.dumpdirstring -
Sets the directory in which APD writes profile dump files. You can specify an absolute path or a relative path.
You can specify a different directory as an argument to apd_set_pprof_trace().
-
apd.statement_tracingboolean -
Specfies whether or not to do per-line tracings. Turning this on (1) will impact the performance of your application.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
| Constant | Value | Description |
|---|---|---|
FUNCTION_TRACE
(integer)
|
1 | |
ARGS_TRACE
(integer)
|
2 | |
ASSIGNMENT_TRACE
(integer)
|
4 | |
STATEMENT_TRACE
(integer)
|
8 | |
MEMORY_TRACE
(integer)
|
16 | |
TIMING_TRACE
(integer)
|
32 | |
SUMMARY_TRACE
(integer)
|
64 | |
ERROR_TRACE
(integer)
|
128 | |
PROF_TRACE
(integer)
|
256 | |
APD_VERSION
(string)
|
example: 1.0.2-dev |
Przykłady
Spis treści
How to use PHP-APD in your scripts
-
As the first line of your PHP script, call the apd_set_pprof_trace() function to start the trace:
<?php
apd_set_pprof_trace();
?>You can insert the line anywhere in your script, but if you do not start tracing at the beginning of your script you discard profile data that might otherwise lead you to a performance bottleneck.
-
Now run your script. The dump output will be written to apd.dumpdir/pprof_pid.ext.
WskazówkaIf you're running the CGI version of PHP, you will need to add the '-e' flag to enable extended information for apd to work properly. For example:
php -e -f script.php -
To display formatted profile data, issue the pprofp command with the sort and display options of your choice. The formatted output will look something like:
bash-2.05b$ pprofp -R /tmp/pprof.22141.0 Trace for /home/dan/testapd.php Total Elapsed Time = 0.00 Total System Time = 0.00 Total User Time = 0.00 Real User System secs/ cumm %Time (excl/cumm) (excl/cumm) (excl/cumm) Calls call s/call Memory Usage Name -------------------------------------------------------------------------------------- 100.0 0.00 0.00 0.00 0.00 0.00 0.00 1 0.0000 0.0009 0 main 56.9 0.00 0.00 0.00 0.00 0.00 0.00 1 0.0005 0.0005 0 apd_set_pprof_trace 28.0 0.00 0.00 0.00 0.00 0.00 0.00 10 0.0000 0.0000 0 preg_replace 14.3 0.00 0.00 0.00 0.00 0.00 0.00 10 0.0000 0.0000 0 str_replace
The -R option used in this example sorts the profile table by the amount of real time the script spent executing a given function. The "cumm call" column reveals how many times each function was called, and the "s/call" column reveals how many seconds each call to the function required, on average.
-
To generate a calltree file that you can import into the KCacheGrind profile analysis application, issue the pprof2calltree comand.
APD Funkcje
Contact information
If you have comments, bugfixes, enhancements or want to help developing this beast, you can send an mail to » apd@mail.communityconnect.com. Any help is very welcome.
apd_breakpoint
(PECL apd >= 0.2)
apd_breakpoint — Stops the interpreter and waits on a CR from the socket
Opis
$debug_level
)This can be used to stop the running of your script, and await responses on the connected socket. To step the program, just send enter (a blank line), or enter a php command to be executed.
Parametry
-
poziom_debugowania -
Liczba, która powstaje poprzez dodanie do siebie stałych XXX_TRACE.
Użycie
MEMORY_TRACEnie jest zalecane. Jest bardzo powolne i nie wydaje się zbyt dokładne. StałaASSIGNMENT_TRACEnie jest jeszcze zaimplementowana.Aby włączyć wszystkie funkcjonalne śledzenia (TIMING, FUNCTIONS, ARGS SUMMARY (takie jak strace -c)) użyj wartości 99
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Typical session using tcplisten
bash#tcplisten localhost 7777
APD - Advanced PHP Debugger Trace File
---------------------------------------------------------------------------
Process Pid (6118)
Trace Begun at Sun Mar 10 23:13:12 2002
---------------------------------------------------------------------------
( 0.000000): apd_set_session_trace called at /home/alan/Projects/project2/test.
php:5
( 0.074824): apd_set_session_trace_socket() at /home/alan/Projects/project2/tes
t.php:5 returned. Elapsed (0.074824)
( 0.074918): apd_breakpoint() /home/alan/Projects/project2/test.php:7
++ argv[0] $(??) = 9
apd_breakpoint() at /home/alan/Projects/project2/test.php:7 returned. Elapsed (
-2089521468.1073275368)
>\n
statement: /home/alan/Projects/project2/test.php:8
>\n
statement: /home/alan/Projects/project2/test.php:8
>\n
statement: /home/alan/Projects/project2/test.php:10
>apd_echo($i);
EXEC: apd_echo($i);
0
>apd_echo(serialize(apd_get_active_symbols()));
EXEC: apd_echo(serialize(apd_get_active_symbols()));
a:47:{i:0;s:4:"PWD";i:1;s:10:"COLORFGBG";i:2;s:11:"XAUTHORITY";i:3;s:14:"
COLORTERM_BCE";i:4;s:9:"WINDOWID";i:5;s:14:"ETERM_VERSION";i:6;s:16:"SE
SSION_MANAGER";i:7;s:4:"PS1";i:8;s:11:"GDMSESSION";i:9;s:5:"USER";i:10;s:5:"
MAIL";i:11;s:7:"OLDPWD";i:12;s:5:"LANG";i:13;s:10:"COLORTERM";i:14;s:8:"DISP
LAY";i:15;s:8:"LOGNAME";i:16;s:6:"
>apd_echo(system('ls /home/mydir'));
........
>apd_continue(0);
apd_callstack
(PECL apd 0.2-0.4)
apd_callstack — Returns the current call stack as an array
Opis
Returns the current call stack as an array
Zwracane wartości
An array containing the current call stack.
Przykłady
Przykład #1 apd_callstack() example
<?php
print_r(apd_callstack());
?>
apd_clunk
(PECL apd 0.2-0.4)
apd_clunk — Throw a warning and a callstack
Opis
$warning
[, string $delimiter
] )Behaves like perl's Carp::cluck. Throw a warning and a callstack.
Parametry
-
warning -
The warning to throw.
-
delimiter -
The delimiter. Default to <BR />.
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 apd_clunk() example
<?php
apd_clunk("Some Warning", "<br/>");
?>
apd_continue
(PECL apd >= 0.2)
apd_continue — Restarts the interpreter
Opis
$debug_level
)Usually sent via the socket to restart the interpreter.
Parametry
-
poziom_debugowania -
Liczba, która powstaje poprzez dodanie do siebie stałych XXX_TRACE.
Użycie
MEMORY_TRACEnie jest zalecane. Jest bardzo powolne i nie wydaje się zbyt dokładne. StałaASSIGNMENT_TRACEnie jest jeszcze zaimplementowana.Aby włączyć wszystkie funkcjonalne śledzenia (TIMING, FUNCTIONS, ARGS SUMMARY (takie jak strace -c)) użyj wartości 99
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 apd_continue() example
<?php
apd_continue(0);
?>
apd_croak
(PECL apd 0.2-0.4)
apd_croak — Throw an error, a callstack and then exit
Opis
$warning
[, string $delimiter
] )Behaves like perl's Carp::croak. Throw an error, a callstack and then exit.
Parametry
-
warning -
The warning to throw.
-
delimiter -
The delimiter. Default to <BR />.
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 apd_croak() example
<?php
apd_croak("Some Warning","<P>");
?>
apd_dump_function_table
(Unknown)
apd_dump_function_table — Outputs the current function table
Opis
Outputs the current function table.
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 apd_dump_function_table() example
<?php
apd_dump_function_table();
?>
apd_dump_persistent_resources
(PECL apd 0.2-0.4)
apd_dump_persistent_resources — Return all persistent resources as an array
Opis
Return all persistent resources as an array.
Zwracane wartości
An array containing the current call stack.
Przykłady
Przykład #1 apd_dump_persistent_resources() example
<?php
print_r(apd_dump_persistent_resources());
?>
apd_dump_regular_resources
(PECL apd 0.2-0.4)
apd_dump_regular_resources — Return all current regular resources as an array
Opis
Return all current regular resources as an array.
Zwracane wartości
An array containing the current regular resources.
Przykłady
Przykład #1 apd_dump_regular_resources() example
<?php
print_r(apd_dump_regular_resources());
?>
apd_echo
(PECL apd >= 0.2)
apd_echo — Echo to the debugging socket
Opis
$output
)Usually sent via the socket to request information about the running script.
Parametry
-
output -
The debugged variable.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 apd_echo() example
<?php
apd_echo($i);
?>
apd_get_active_symbols
(PECL apd 0.2)
apd_get_active_symbols — Get an array of the current variables names in the local scope
Opis
Returns the names of all the variables defined in the active scope, (not their values).
Zwracane wartości
A multidimensional array with all the variables.
Przykłady
Przykład #1 apd_get_active_symbols() example
<?php
apd_echo(apd_get_active_symbols());
?>
apd_set_pprof_trace
(PECL apd >= 0.2)
apd_set_pprof_trace — Starts the session debugging
Opis
$dump_directory
[, string $fragment = "pprof"
]] )Starts debugging to pprof_{process_id} in the dump directory.
Parametry
-
dump_directory -
The directory in which the profile dump file is written. If not set, the apd.dumpdir setting from the php.ini file is used.
-
fragment -
Zwracane wartości
Returns path of the destination file.
Przykłady
Przykład #1 apd_set_pprof_trace() example
<?php
apd_set_pprof_trace();
?>
apd_set_session_trace_socket
(PECL apd >= 0.2)
apd_set_session_trace_socket — Starts the remote session debugging
Opis
$tcp_server
, int $socket_type
, int $port
, int $debug_level
)
Connects to the specified tcp_server (eg. tcplisten)
and sends debugging data to the socket.
Parametry
-
tcp_server -
IP or Unix Domain socket (like a file) of the TCP server.
-
socket_type -
Can be
AF_UNIXfor file based sockets orAPD_AF_INETfor standard tcp/ip. -
port -
You can use any port, but higher numbers are better as most of the lower numbers may be used by other system services.
-
poziom_debugowania -
Liczba, która powstaje poprzez dodanie do siebie stałych XXX_TRACE.
Użycie
MEMORY_TRACEnie jest zalecane. Jest bardzo powolne i nie wydaje się zbyt dokładne. StałaASSIGNMENT_TRACEnie jest jeszcze zaimplementowana.Aby włączyć wszystkie funkcjonalne śledzenia (TIMING, FUNCTIONS, ARGS SUMMARY (takie jak strace -c)) użyj wartości 99
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 apd_set_session_trace_socket() example
<?php
apd_set_session_trace_socket("127.0.0.1",APD_AF_INET,7112,0);
?>
apd_set_session_trace
(PECL apd 0.2-0.4)
apd_set_session_trace — Starts the session debugging
Opis
$debug_level
[, string $dump_directory
] )Starts debugging to apd_dump_{process_id} in the dump directory.
Parametry
-
poziom_debugowania -
Liczba, która powstaje poprzez dodanie do siebie stałych XXX_TRACE.
Użycie
MEMORY_TRACEnie jest zalecane. Jest bardzo powolne i nie wydaje się zbyt dokładne. StałaASSIGNMENT_TRACEnie jest jeszcze zaimplementowana.Aby włączyć wszystkie funkcjonalne śledzenia (TIMING, FUNCTIONS, ARGS SUMMARY (takie jak strace -c)) użyj wartości 99
-
dump_directory -
The directory in which the profile dump file is written. If not set, the apd.dumpdir setting from the php.ini file is used.
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 apd_set_session_trace() example
<?php
apd_set_session_trace(99);
?>
apd_set_session
(PECL apd 0.2-0.4)
apd_set_session — Changes or sets the current debugging level
Opis
$debug_level
)This can be used to increase or decrease debugging in a different area of your application.
Parametry
-
poziom_debugowania -
Liczba, która powstaje poprzez dodanie do siebie stałych XXX_TRACE.
Użycie
MEMORY_TRACEnie jest zalecane. Jest bardzo powolne i nie wydaje się zbyt dokładne. StałaASSIGNMENT_TRACEnie jest jeszcze zaimplementowana.Aby włączyć wszystkie funkcjonalne śledzenia (TIMING, FUNCTIONS, ARGS SUMMARY (takie jak strace -c)) użyj wartości 99
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 apd_set_session() example
<?php
apd_set_session(9);
?>
override_function
(PECL apd >= 0.2)
override_function — Overrides built-in functions
Opis
$function_name
, string $function_args
, string $function_code
)Overrides built-in functions by replacing them in the symbol table.
Parametry
-
function_name -
The function to override.
-
function_args -
The function arguments, as a comma separated string.
Usually you will want to pass this parameter, as well as the
function_codeparameter, as a single quote delimited string. The reason for using single quoted strings, is to protect the variable names from parsing, otherwise, if you use double quotes there will be a need to escape the variable names, e.g. \$your_var. -
function_code -
The new code for the function.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 override_function() example
<?php
override_function('test', '$a,$b', 'echo "DOING TEST"; return $a * $b;');
?>
rename_function
(PECL apd >= 0.2)
rename_function — Renames orig_name to new_name in the global function table
Opis
$original_name
, string $new_name
)Renames a orig_name to new_name in the global function table. Useful for temporarily overriding built-in functions.
Parametry
-
original_name -
The original function name.
-
new_name -
The new name for the
original_namefunction.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 rename_function() example
<?php
rename_function('mysql_connect', 'debug_mysql_connect' );
?>
Spis treści
- apd_breakpoint — Stops the interpreter and waits on a CR from the socket
- apd_callstack — Returns the current call stack as an array
- apd_clunk — Throw a warning and a callstack
- apd_continue — Restarts the interpreter
- apd_croak — Throw an error, a callstack and then exit
- apd_dump_function_table — Outputs the current function table
- apd_dump_persistent_resources — Return all persistent resources as an array
- apd_dump_regular_resources — Return all current regular resources as an array
- apd_echo — Echo to the debugging socket
- apd_get_active_symbols — Get an array of the current variables names in the local scope
- apd_set_pprof_trace — Starts the session debugging
- apd_set_session_trace_socket — Starts the remote session debugging
- apd_set_session_trace — Starts the session debugging
- apd_set_session — Changes or sets the current debugging level
- override_function — Overrides built-in functions
- rename_function — Renames orig_name to new_name in the global function table
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Przykłady
- APD Funkcje
- apd_breakpoint — Stops the interpreter and waits on a CR from the socket
- apd_callstack — Returns the current call stack as an array
- apd_clunk — Throw a warning and a callstack
- apd_continue — Restarts the interpreter
- apd_croak — Throw an error, a callstack and then exit
- apd_dump_function_table — Outputs the current function table
- apd_dump_persistent_resources — Return all persistent resources as an array
- apd_dump_regular_resources — Return all current regular resources as an array
- apd_echo — Echo to the debugging socket
- apd_get_active_symbols — Get an array of the current variables names in the local scope
- apd_set_pprof_trace — Starts the session debugging
- apd_set_session_trace_socket — Starts the remote session debugging
- apd_set_session_trace — Starts the session debugging
- apd_set_session — Changes or sets the current debugging level
- override_function — Overrides built-in functions
- rename_function — Renames orig_name to new_name in the global function table
PHP bytecode Compiler
Wstęp
Ten moduł jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie tych funkcji, ich nazw, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tego modułu na własne ryzyko.
Bcompiler was written for several reasons:
- To encode entire script in a proprietary PHP application
- To encode some classes and/or functions in a proprietary PHP application
- To enable the production of php-gtk applications that could be used on client desktops, without the need for a php.exe.
- To do the feasibility study for a PHP to C converter
The second of these goals is achieved using the bcompiler_write_header(), bcompiler_write_class(), bcompiler_write_footer(), bcompiler_read(), and bcompiler_load() functions. The bytecode files can be written as either uncompressed or plain. The bcompiler_load() reads a bzip compressed bytecode file, which tends to be 1/3 of the size of the original file.
To create EXE type files, bcompiler has to be used with a modified sapi file or a version of PHP which has been compiled as a shared library. In this scenario, bcompiler reads the compressed bytecode from the end of the exe file.
bcompiler can improve performance by about 30% when used with uncompressed bytecodes only. But keep in mind that uncompressed bytecode can be up to 5 times larger than the original source code. Using bytecode compression can save your space, but decompression requires much more time than parsing a source. bcompiler also does not do any bytecode optimization, this could be added in the future...
In terms of code protection, it is safe to say that it would be impossible to recreate the exact source code that it was built from, and without the accompanying source code comments. It would effectively be useless to use the bcompiler bytecodes to recreate and modify a class. However it is possible to retrieve data from a bcompiled bytecode file - so don't put your private passwords or anything in it.
Instalacja/Konfiguracja
Spis treści
Wymagania
Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.
Instalacja
To rozszerzenie » PECL nie jest dołączane do PHP.
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/bcompiler.
DLL z tym rozszerzeniem PECL można pobrać zarówno ze strony » PHP Downloads lub z » http://pecl4win.php.net/
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
To rozszerzenie nie posiada żadnych stałych.
bcompiler Funkcje
Contact Information
If you have comments, bugfixes, enhancements or want to help developing this beast, you can drop me a mail at » alan_k@php.net. Any help is very welcome.
bcompiler_load_exe
(PECL bcompiler >= 0.4)
bcompiler_load_exe — Reads and creates classes from a bcompiler exe file
Opis
$filename
)Reads data from a bcompiler exe file and creates classes from the bytecodes.
Parametry
-
filename -
The exe file path, as a string.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 bcompiler_load_exe() example
<?php
bcompiler_load_exe("/tmp/example.exe");
print_r(get_defined_classes());
?>
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
bcompiler_load
(PECL bcompiler >= 0.4)
bcompiler_load — Reads and creates classes from a bz compressed file
Opis
$filename
)Reads data from a bzcompressed file and creates classes from the bytecodes.
Parametry
-
filename -
The bzcompressed file path, as a string.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 bcompiler_load() example
<?php
bcompiler_load("/tmp/example");
print_r(get_defined_classes());
?>
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Informacja:
Please use include or require statements to parse bytecodes, it's more portable and convenient way than using this function.
Please note that this function won't execute script body code contained in the bytecode file.
bcompiler_parse_class
(PECL bcompiler >= 0.4)
bcompiler_parse_class — Reads the bytecodes of a class and calls back to a user function
Opis
$class
, string $callback
)Reads the bytecodes of a class and calls back to a user function.
Parametry
-
class -
The class name, as a string.
-
callback -
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 bcompiler_parse_class() example
<?php
function readByteCodes($data) {
print_r($data);
}
bcompiler_parse_class("DB","readByteCodes");
?>
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Informacja:
This function has been removed from bcompiler and is no longer available as of bcompiler 0.5.
bcompiler_read
(PECL bcompiler >= 0.4)
bcompiler_read — Reads and creates classes from a filehandle
Opis
$filehandle
)Reads data from a open file handle and creates classes from the bytecodes.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 bcompiler_read() example
<?php
$fh = fopen("/tmp/example","r");
bcompiler_read($fh);
fclose($fh);
print_r(get_defined_classes());
?>
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Informacja:
Please use include or require statements to parse bytecodes, it's more portable and convenient way than using this function.
Please note that this function won't execute script body code contained in the bytecode file.
bcompiler_write_class
(PECL bcompiler >= 0.4)
bcompiler_write_class — Writes a defined class as bytecodes
Opis
$filehandle
, string $className
[, string $extends
] )Reads the bytecodes from PHP for an existing class, and writes them to the open file handle.
Parametry
-
filehandle -
A file handle as returned by fopen().
-
className -
The class name, as a string.
-
extends -
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 bcompiler_write_class() example
<?php
$fh = fopen("/tmp/example","w");
bcompiler_write_header($fh);
bcompiler_write_class($fh,"DB");
// you must write DB_common before DB_mysql, as DB_mysql extends DB_common.
bcompiler_write_class($fh,"DB_common");
bcompiler_write_class($fh,"DB_mysql");
bcompiler_write_footer($fh);
fclose($fh);
?>
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Informacja:
This function does not perform dependency checking, so make sure you write the classes in an order that will not result in an undefined class error occurring when you load it.
Zobacz też:
- bcompiler_write_header() - Writes the bcompiler header
- bcompiler_write_footer() - Writes the single character \x00 to indicate End of compiled data
bcompiler_write_constant
(PECL bcompiler >= 0.5)
bcompiler_write_constant — Writes a defined constant as bytecodes
Opis
$filehandle
, string $constantName
)Reads the bytecodes from PHP for an existing constant, and writes them to the open file handle.
Parametry
-
filehandle -
A file handle as returned by fopen().
-
constantName -
The name of the defined constant, as a string.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 bcompiler_write_constant() example
<?php
define("MODULE_MAX", 30);
$fh = fopen("/tmp/example","w");
bcompiler_write_header($fh);
bcompiler_write_constant($fh,"MODULE_MAX");
bcompiler_write_footer($fh);
fclose($fh);
?>
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Zobacz też:
- bcompiler_write_header() - Writes the bcompiler header
- bcompiler_write_footer() - Writes the single character \x00 to indicate End of compiled data
bcompiler_write_file
(PECL bcompiler >= 0.6)
bcompiler_write_file — Writes a php source file as bytecodes
Opis
$filehandle
, string $filename
)This function complies specified source file into bytecodes, and writes them to the open file handle.
Parametry
-
filehandle -
A file handle as returned by fopen().
-
filename -
The source file path, as a string.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 bcompiler_write_file() example
<?php
$fh = fopen("example.phb", "w");
bcompiler_write_header($fh);
bcompiler_write_file($fh, "example.php");
bcompiler_write_footer($fh);
fclose($fh);
/* the following should be equivalent:
include "example.php";
and
include "example.phb";
*/
?>
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Zobacz też:
- bcompiler_write_header() - Writes the bcompiler header
- bcompiler_write_footer() - Writes the single character \x00 to indicate End of compiled data
bcompiler_write_function
(PECL bcompiler >= 0.5)
bcompiler_write_function — Writes a defined function as bytecodes
Opis
$filehandle
, string $functionName
)Reads the bytecodes from PHP for an existing function, and writes them to the open file handle. Order is not important, (eg. if function b uses function a, and you compile it like the example below, it will work perfectly OK).
Parametry
-
filehandle -
A file handle as returned by fopen().
-
functionName -
The function name, as a string.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 bcompiler_write_function() example
<?php
$fh = fopen("/tmp/example","w");
bcompiler_write_header($fh);
bcompiler_write_function($fh,"my_function_a");
bcompiler_write_function($fh,"my_function_b");
bcompiler_write_footer($fh);
fclose($fh);
?>
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Zobacz też:
- bcompiler_write_header() - Writes the bcompiler header
- bcompiler_write_footer() - Writes the single character \x00 to indicate End of compiled data
bcompiler_write_functions_from_file
(PECL bcompiler >= 0.5)
bcompiler_write_functions_from_file — Writes all functions defined in a file as bytecodes
Opis
$filehandle
, string $fileName
)Searches for all functions declared in the given file, and writes their correspondent bytecodes to the open file handle.
Parametry
-
filehandle -
A file handle as returned by fopen().
-
fileName -
The file to be compiled. You must always include or require the file you intend to compile.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 bcompiler_write_functions_from_file() example
<?php
require('module.php');
$fh = fopen("/tmp/example","w");
bcompiler_write_header($fh);
bcompiler_write_functions_from_file($fh,'module.php');
bcompiler_write_footer($fh);
fclose($fh);
?>
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Zobacz też:
- bcompiler_write_header() - Writes the bcompiler header
- bcompiler_write_footer() - Writes the single character \x00 to indicate End of compiled data
bcompiler_write_header
(PECL bcompiler >= 0.3)
bcompiler_write_header — Writes the bcompiler header
Opis
$filehandle
[, string $write_ver
] )Writes the header part of a bcompiler file.
Parametry
-
filehandle -
A file handle as returned by fopen().
-
write_ver -
Can be used to write bytecode in a previously used format, so that you can use it with older versions of bcompiler.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 bcompiler_write_header() example
<?php
$fh = fopen("/tmp/example","w");
bcompiler_write_header($fh);
bcompiler_write_class($fh,"DB");
bcompiler_write_footer($fh);
fclose($fh);
?>
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Zobacz też:
- bcompiler_write_footer() - Writes the single character \x00 to indicate End of compiled data
bcompiler_write_included_filename
(PECL bcompiler >= 0.5)
bcompiler_write_included_filename — Writes an included file as bytecodes
Opis
$filehandle
, string $filename
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Spis treści
- bcompiler_load_exe — Reads and creates classes from a bcompiler exe file
- bcompiler_load — Reads and creates classes from a bz compressed file
- bcompiler_parse_class — Reads the bytecodes of a class and calls back to a user function
- bcompiler_read — Reads and creates classes from a filehandle
- bcompiler_write_class — Writes a defined class as bytecodes
- bcompiler_write_constant — Writes a defined constant as bytecodes
- bcompiler_write_exe_footer — Writes the start pos, and sig to the end of a exe type file
- bcompiler_write_file — Writes a php source file as bytecodes
- bcompiler_write_footer — Writes the single character \x00 to indicate End of compiled data
- bcompiler_write_function — Writes a defined function as bytecodes
- bcompiler_write_functions_from_file — Writes all functions defined in a file as bytecodes
- bcompiler_write_header — Writes the bcompiler header
- bcompiler_write_included_filename — Writes an included file as bytecodes
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- bcompiler Funkcje
- bcompiler_load_exe — Reads and creates classes from a bcompiler exe file
- bcompiler_load — Reads and creates classes from a bz compressed file
- bcompiler_parse_class — Reads the bytecodes of a class and calls back to a user function
- bcompiler_read — Reads and creates classes from a filehandle
- bcompiler_write_class — Writes a defined class as bytecodes
- bcompiler_write_constant — Writes a defined constant as bytecodes
- bcompiler_write_exe_footer — Writes the start pos, and sig to the end of a exe type file
- bcompiler_write_file — Writes a php source file as bytecodes
- bcompiler_write_footer — Writes the single character \x00 to indicate End of compiled data
- bcompiler_write_function — Writes a defined function as bytecodes
- bcompiler_write_functions_from_file — Writes all functions defined in a file as bytecodes
- bcompiler_write_header — Writes the bcompiler header
- bcompiler_write_included_filename — Writes an included file as bytecodes
Error Handling and Logging
Wstęp
These are functions dealing with error handling and logging. They allow you to define your own error handling rules, as well as modify the way the errors can be logged. This allows you to change and enhance error reporting to suit your needs.
With the logging functions, you can send messages directly to other machines, to an email (or email to pager gateway!), to system logs, etc., so you can selectively log and monitor the most important parts of your applications and websites.
The error reporting functions allow you to customize what level and kind of error feedback is given, ranging from simple notices to customized functions returned during errors.
Instalacja/Konfiguracja
Spis treści
Wymagania
Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.
Instalacja
By używać tych funkcji, nie trzeba niczego instalować. Są one częścią jądra PHP.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| error_reporting | NULL | PHP_INI_ALL | |
| display_errors | "1" | PHP_INI_ALL | |
| display_startup_errors | "0" | PHP_INI_ALL | |
| log_errors | "0" | PHP_INI_ALL | |
| log_errors_max_len | "1024" | PHP_INI_ALL | Available since PHP 4.3.0. |
| ignore_repeated_errors | "0" | PHP_INI_ALL | Available since PHP 4.3.0. |
| ignore_repeated_source | "0" | PHP_INI_ALL | Available since PHP 4.3.0. |
| report_memleaks | "1" | PHP_INI_ALL | Available since PHP 4.3.0. |
| track_errors | "0" | PHP_INI_ALL | |
| html_errors | "1" | PHP_INI_ALL | PHP_INI_SYSTEM in PHP <= 4.2.3. |
| xmlrpc_errors | "0" | PHP_INI_SYSTEM | Available since PHP 4.1.0. |
| xmlrpc_error_number | "0" | PHP_INI_ALL | Available since PHP 4.1.0. |
| docref_root | "" | PHP_INI_ALL | Available since PHP 4.3.0. |
| docref_ext | "" | PHP_INI_ALL | Available since PHP 4.3.2. |
| error_prepend_string | NULL | PHP_INI_ALL | |
| error_append_string | NULL | PHP_INI_ALL | |
| error_log | NULL | PHP_INI_ALL |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
error_reportinginteger -
Set the error reporting level. The parameter is either an integer representing a bit field, or named constants. The error_reporting levels and constants are described in Predefined Constants, and in php.ini. To set at runtime, use the error_reporting() function. See also the display_errors directive.
In PHP 4 and PHP 5 the default value is
E_ALL& ~E_NOTICE. This setting does not showE_NOTICElevel errors. You may want to show them during development.Informacja:
Enabling
E_NOTICEduring development has some benefits. For debugging purposes: NOTICE messages will warn you about possible bugs in your code. For example, use of unassigned values is warned. It is extremely useful to find typos and to save time for debugging. NOTICE messages will warn you about bad style. For example, $arr[item] is better to be written as $arr['item'] since PHP tries to treat "item" as constant. If it is not a constant, PHP assumes it is a string index for the array.Informacja:
In PHP 5 a new error level
E_STRICTis available. AsE_STRICTis not included withinE_ALLyou have to explicitly enable this kind of error level. EnablingE_STRICTduring development has some benefits. STRICT messages will help you to use the latest and greatest suggested method of coding, for example warn you about using deprecated functions.Informacja: PHP Constants outside of PHP
Using PHP Constants outside of PHP, like in httpd.conf, will have no useful meaning so in such cases the integer values are required. And since error levels will be added over time, the maximum value (for
E_ALL) will likely change. So in place ofE_ALLconsider using a larger value to cover all bit fields from now and well into the future, a numeric value like 2147483647 (includes all errors, not justE_ALL). -
display_errorsstring -
This determines whether errors should be printed to the screen as part of the output or if they should be hidden from the user.
Value "stderr" sends the errors to stderr instead of stdout. The value is available as of PHP 5.2.4. In earlier versions, this directive was of type boolean.
Informacja:
This is a feature to support your development and should never be used on production systems (e.g. systems connected to the internet).
Informacja:
Although display_errors may be set at runtime (with ini_set()), it won't have any affect if the script has fatal errors. This is because the desired runtime action does not get executed.
-
display_startup_errorsboolean -
Even when display_errors is on, errors that occur during PHP's startup sequence are not displayed. It's strongly recommended to keep display_startup_errors off, except for debugging.
-
log_errorsboolean -
Tells whether script error messages should be logged to the server's error log or error_log. This option is thus server-specific.
Informacja:
You're strongly advised to use error logging in place of error displaying on production web sites.
-
log_errors_max_leninteger -
Set the maximum length of log_errors in bytes. In error_log information about the source is added. The default is 1024 and 0 allows to not apply any maximum length at all. This length is applied to logged errors, displayed errors and also to $php_errormsg.
Jeśli użyty zostanie typ integer, wartość zostanie liczona w bajtach. Można także użyć notacji skrótowej opisanej w FAQ. -
ignore_repeated_errorsboolean -
Do not log repeated messages. Repeated errors must occur in the same file on the same line unless ignore_repeated_source is set true.
-
ignore_repeated_sourceboolean -
Ignore source of message when ignoring repeated messages. When this setting is On you will not log errors with repeated messages from different files or sourcelines.
-
report_memleaksboolean -
If this parameter is set to On (the default), this parameter will show a report of memory leaks detected by the Zend memory manager. This report will be send to stderr on Posix platforms. On Windows, it will be send to the debugger using OutputDebugString(), and can be viewed with tools like » DbgView. This parameter only has effect in a debug build, and if error_reporting includes
E_WARNINGin the allowed list. -
track_errorsboolean -
If enabled, the last error message will always be present in the variable $php_errormsg.
-
html_errorsboolean -
Turn off HTML tags in error messages. The new format for HTML errors produces clickable messages that direct the user to a page describing the error or function in causing the error. These references are affected by docref_root and docref_ext.
-
xmlrpc_errorsboolean -
Turns off normal error reporting and formats errors as XML-RPC error message.
-
xmlrpc_error_numberinteger -
Used as the value of the XML-RPC faultCode element.
-
docref_rootstring -
The new error format contains a reference to a page describing the error or function causing the error. In case of manual pages you can download the manual in your language and set this ini directive to the URL of your local copy. If your local copy of the manual can be reached by "/manual/" you can simply use
docref_root=/manual/. Additional you have to set docref_ext to match the fileextensions of your copydocref_ext=.html. It is possible to use external references. For example you can usedocref_root=http://manual/en/ordocref_root="http://landonize.it/?how=url&theme=classic&filter=Landon &url=http%3A%2F%2Fwww.php.net%2F"Most of the time you want the docref_root value to end with a slash "/". But see the second example above which does not have nor need it.
Informacja:
This is a feature to support your development since it makes it easy to lookup a function description. However it should never be used on production systems (e.g. systems connected to the internet).
-
docref_extstring -
See docref_root.
Informacja:
The value of docref_ext must begin with a dot ".".
-
error_prepend_stringstring -
String to output before an error message.
-
error_append_stringstring -
String to output after an error message.
-
error_logstring -
Name of the file where script errors should be logged. The file should be writable by the web server's user. If the special value syslog is used, the errors are sent to the system logger instead. On Unix, this means syslog(3) and on Windows NT it means the event log. The system logger is not supported on Windows 95. See also: syslog(). If this directive is not set, errors are sent to the SAPI error logger. For example, it is an error log in Apache or stderr in CLI.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
Poniższe stałe są częścią jądra PHP a więc są zawsze widoczne.
Informacja: You may use these constant names in php.ini but not outside of PHP, like in httpd.conf, where you'd use the bitmask values instead.
| Value | Constant | Description | Note |
|---|---|---|---|
| 1 |
E_ERROR
(integer)
|
Fatal run-time errors. These indicate errors that can not be recovered from, such as a memory allocation problem. Execution of the script is halted. | |
| 2 |
E_WARNING
(integer)
|
Run-time warnings (non-fatal errors). Execution of the script is not halted. | |
| 4 |
E_PARSE
(integer)
|
Compile-time parse errors. Parse errors should only be generated by the parser. | |
| 8 |
E_NOTICE
(integer)
|
Run-time notices. Indicate that the script encountered something that could indicate an error, but could also happen in the normal course of running a script. | |
| 16 |
E_CORE_ERROR
(integer)
|
Fatal errors that occur during PHP's initial startup. This is like an
E_ERROR, except it is generated by the core of PHP.
|
|
| 32 |
E_CORE_WARNING
(integer)
|
Warnings (non-fatal errors) that occur during PHP's initial startup.
This is like an E_WARNING, except it is generated
by the core of PHP.
|
|
| 64 |
E_COMPILE_ERROR
(integer)
|
Fatal compile-time errors. This is like an E_ERROR,
except it is generated by the Zend Scripting Engine.
|
|
| 128 |
E_COMPILE_WARNING
(integer)
|
Compile-time warnings (non-fatal errors). This is like an
E_WARNING, except it is generated by the Zend
Scripting Engine.
|
|
| 256 |
E_USER_ERROR
(integer)
|
User-generated error message. This is like an
E_ERROR, except it is generated in PHP code by
using the PHP function trigger_error().
|
|
| 512 |
E_USER_WARNING
(integer)
|
User-generated warning message. This is like an
E_WARNING, except it is generated in PHP code by
using the PHP function trigger_error().
|
|
| 1024 |
E_USER_NOTICE
(integer)
|
User-generated notice message. This is like an
E_NOTICE, except it is generated in PHP code by
using the PHP function trigger_error().
|
|
| 2048 |
E_STRICT
(integer)
|
Enable to have PHP suggest changes to your code which will ensure the best interoperability and forward compatibility of your code. | Since PHP 5 but not included in E_ALL until PHP 5.4.0 |
| 4096 |
E_RECOVERABLE_ERROR
(integer)
|
Catchable fatal error. It indicates that a probably dangerous error
occured, but did not leave the Engine in an unstable state. If the error
is not caught by a user defined handle (see also
set_error_handler()), the application aborts as it
was an E_ERROR.
|
Since PHP 5.2.0 |
| 8192 |
E_DEPRECATED
(integer)
|
Run-time notices. Enable this to receive warnings about code that will not work in future versions. | Since PHP 5.3.0 |
| 16384 |
E_USER_DEPRECATED
(integer)
|
User-generated warning message. This is like an
E_DEPRECATED, except it is generated in PHP code by
using the PHP function trigger_error().
|
Since PHP 5.3.0 |
| 32767 |
E_ALL
(integer)
|
All errors and warnings, as supported, except of level
E_STRICT prior to PHP 5.4.0.
|
32767 in PHP 5.4.x, 30719 in PHP 5.3.x, 6143 in PHP 5.2.x, 2047 previously |
The above values (either numerical or symbolic) are used to build up a bitmask that specifies which errors to report. You can use the bitwise operators to combine these values or mask out certain types of errors. Note that only '|', '~', '!', '^' and '&' will be understood within php.ini.
Przykłady
Below we can see an example of using the error handling capabilities in PHP. We define an error handling function which logs the information into a file (using an XML format), and e-mails the developer if a critical error in the logic happens.
Przykład #1 Using error handling in a script
<?php
// we will do our own error handling
error_reporting(0);
// user defined error handling function
function userErrorHandler($errno, $errmsg, $filename, $linenum, $vars)
{
// timestamp for the error entry
$dt = date("Y-m-d H:i:s (T)");
// define an assoc array of error string
// in reality the only entries we should
// consider are E_WARNING, E_NOTICE, E_USER_ERROR,
// E_USER_WARNING and E_USER_NOTICE
$errortype = array (
E_ERROR => 'Error',
E_WARNING => 'Warning',
E_PARSE => 'Parsing Error',
E_NOTICE => 'Notice',
E_CORE_ERROR => 'Core Error',
E_CORE_WARNING => 'Core Warning',
E_COMPILE_ERROR => 'Compile Error',
E_COMPILE_WARNING => 'Compile Warning',
E_USER_ERROR => 'User Error',
E_USER_WARNING => 'User Warning',
E_USER_NOTICE => 'User Notice',
E_STRICT => 'Runtime Notice',
E_RECOVERABLE_ERROR => 'Catchable Fatal Error'
);
// set of errors for which a var trace will be saved
$user_errors = array(E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE);
$err = "<errorentry>\n";
$err .= "\t<datetime>" . $dt . "</datetime>\n";
$err .= "\t<errornum>" . $errno . "</errornum>\n";
$err .= "\t<errortype>" . $errortype[$errno] . "</errortype>\n";
$err .= "\t<errormsg>" . $errmsg . "</errormsg>\n";
$err .= "\t<scriptname>" . $filename . "</scriptname>\n";
$err .= "\t<scriptlinenum>" . $linenum . "</scriptlinenum>\n";
if (in_array($errno, $user_errors)) {
$err .= "\t<vartrace>" . wddx_serialize_value($vars, "Variables") . "</vartrace>\n";
}
$err .= "</errorentry>\n\n";
// for testing
// echo $err;
// save to the error log, and e-mail me if there is a critical user error
error_log($err, 3, "/usr/local/php4/error.log");
if ($errno == E_USER_ERROR) {
mail("phpdev@example.com", "Critical User Error", $err);
}
}
function distance($vect1, $vect2)
{
if (!is_array($vect1) || !is_array($vect2)) {
trigger_error("Incorrect parameters, arrays expected", E_USER_ERROR);
return NULL;
}
if (count($vect1) != count($vect2)) {
trigger_error("Vectors need to be of the same size", E_USER_ERROR);
return NULL;
}
for ($i=0; $i<count($vect1); $i++) {
$c1 = $vect1[$i]; $c2 = $vect2[$i];
$d = 0.0;
if (!is_numeric($c1)) {
trigger_error("Coordinate $i in vector 1 is not a number, using zero",
E_USER_WARNING);
$c1 = 0.0;
}
if (!is_numeric($c2)) {
trigger_error("Coordinate $i in vector 2 is not a number, using zero",
E_USER_WARNING);
$c2 = 0.0;
}
$d += $c2*$c2 - $c1*$c1;
}
return sqrt($d);
}
$old_error_handler = set_error_handler("userErrorHandler");
// undefined constant, generates a warning
$t = I_AM_NOT_DEFINED;
// define some "vectors"
$a = array(2, 3, "foo");
$b = array(5.5, 4.3, -1.6);
$c = array(1, -3);
// generate a user error
$t1 = distance($c, $b) . "\n";
// generate another user error
$t2 = distance($b, "i am not an array") . "\n";
// generate a warning
$t3 = distance($a, $b) . "\n";
?>
Error Handling Funkcje
Zobacz też:
See also syslog().
debug_backtrace
(PHP 4 >= 4.3.0, PHP 5)
debug_backtrace — Generates a backtrace
Opis
$options = DEBUG_BACKTRACE_PROVIDE_OBJECT
[, int $limit = 0
]] )debug_backtrace() generates a PHP backtrace.
Parametry
-
options -
As of 5.3.6, this parameter is a bitmask for the following options:
Before 5.3.6, the only values recognized aredebug_backtrace() options DEBUG_BACKTRACE_PROVIDE_OBJECT Whether or not to populate the "object" index. DEBUG_BACKTRACE_IGNORE_ARGS Whether or not to omit the "args" index, and thus all the function/method arguments, to save memory. TRUEorFALSE, which are the same as setting or not setting theDEBUG_BACKTRACE_PROVIDE_OBJECToption respectively. -
limit -
As of 5.4.0, this parameter can be used to limit the number of stack frames returned. By default (
limit=0) it returns all stack frames.
Zwracane wartości
Returns an array of associative arrays. The possible returned elements are as follows:
| Nazwa | Typ | Opis |
|---|---|---|
| function | string | The current function name. See also __FUNCTION__. |
| line | integer | The current line number. See also __LINE__. |
| file | string | The current file name. See also __FILE__. |
| class | string | The current class name. See also __CLASS__ |
| object | object | The current object. |
| type | string | The current call type. If a method call, "->" is returned. If a static method call, "::" is returned. If a function call, nothing is returned. |
| args | array | If inside a function, this lists the functions arguments. If inside an included file, this lists the included file name(s). |
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.4.0 |
Added the optional parameter limit.
|
| 5.3.6 |
The parameter provide_object changed to options and additional option
DEBUG_BACKTRACE_IGNORE_ARGS is added.
|
| 5.2.5 |
Added the optional parameter provide_object.
|
| 5.1.1 | Added the current object as a possible return element. |
Przykłady
Przykład #1 debug_backtrace() example
<?php
// filename: /tmp/a.php
function a_test($str)
{
echo "\nHi: $str";
var_dump(debug_backtrace());
}
a_test('friend');
?>
<?php
// filename: /tmp/b.php
include_once '/tmp/a.php';
?>
Results similar to the following when executing /tmp/b.php:
Hi: friend
array(2) {
[0]=>
array(4) {
["file"] => string(10) "/tmp/a.php"
["line"] => int(10)
["function"] => string(6) "a_test"
["args"]=>
array(1) {
[0] => &string(6) "friend"
}
}
[1]=>
array(4) {
["file"] => string(10) "/tmp/b.php"
["line"] => int(2)
["args"] =>
array(1) {
[0] => string(10) "/tmp/a.php"
}
["function"] => string(12) "include_once"
}
}
Zobacz też:
- trigger_error() - Generates a user-level error/warning/notice message
- debug_print_backtrace() - Prints a backtrace
debug_print_backtrace
(PHP 5)
debug_print_backtrace — Prints a backtrace
Opis
$options = 0
[, int $limit = 0
]] )debug_print_backtrace() prints a PHP backtrace. It prints the function calls, included/required files and eval()ed stuff.
Parametry
-
options -
As of 5.3.6, this parameter is a bitmask for the following options:
debug_print_backtrace() options DEBUG_BACKTRACE_IGNORE_ARGS Whether or not to omit the "args" index, and thus all the function/method arguments, to save memory. -
limit -
As of 5.4.0, this parameter can be used to limit the number of stack frames printed. By default (
limit=0) it prints all stack frames.
Zwracane wartości
Nie jest zwracana żadna wartość.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.4.0 |
Added the optional parameter limit.
|
| 5.3.6 |
Added the optional parameter options.
|
Przykłady
Przykład #1 debug_print_backtrace() example
<?php
// include.php file
function a() {
b();
}
function b() {
c();
}
function c(){
debug_print_backtrace();
}
a();
?>
<?php
// test.php file
// this is the file you should run
include 'include.php';
?>
Powyższy przykład wyświetli coś podobnego do:
#0 c() called at [/tmp/include.php:10] #1 b() called at [/tmp/include.php:6] #2 a() called at [/tmp/include.php:17] #3 include(/tmp/include.php) called at [/tmp/test.php:3]
error_get_last
(PHP 5 >= 5.2.0)
error_get_last — Get the last occurred error
Opis
Gets information about the last error that occurred.
Zwracane wartości
Returns an associative array describing the last error with keys "type",
"message", "file" and "line". If the error has been caused by a PHP
internal function then the "message" begins with its name.
Returns NULL if there hasn't been an error yet.
Przykłady
Przykład #1 An error_get_last() example
<?php
echo $a;
print_r(error_get_last());
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[type] => 8
[message] => Undefined variable: a
[file] => C:\WWW\index.php
[line] => 2
)
Zobacz też:
error_log
(PHP 4, PHP 5)
error_log — Send an error message somewhere
Opis
$message
[, int $message_type = 0
[, string $destination
[, string $extra_headers
]]] )Sends an error message to the web server's error log or to a file.
Parametry
-
message -
The error message that should be logged.
-
message_type -
Says where the error should go. The possible message types are as follows:
error_log() log types 0 messageis sent to PHP's system logger, using the Operating System's system logging mechanism or a file, depending on what the error_log configuration directive is set to. This is the default option.1 messageis sent by email to the address in thedestinationparameter. This is the only message type where the fourth parameter,extra_headersis used.2 No longer an option. 3 messageis appended to the filedestination. A newline is not automatically added to the end of themessagestring.4 messageis sent directly to the SAPI logging handler. -
destination -
The destination. Its meaning depends on the
message_typeparameter as described above. -
extra_headers -
The extra headers. It's used when the
message_typeparameter is set to 1. This message type uses the same internal function as mail() does.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.2.7 |
The possible value of 4 was added to message_type.
|
Przykłady
Przykład #1 error_log() examples
<?php
// Send notification through the server log if we can not
// connect to the database.
if (!Ora_Logon($username, $password)) {
error_log("Oracle database not available!", 0);
}
// Notify administrator by email if we run out of FOO
if (!($foo = allocate_new_foo())) {
error_log("Big trouble, we're all out of FOOs!", 1,
"operator@example.com");
}
// another way to call error_log():
error_log("You messed up!", 3, "/var/tmp/my-errors.log");
?>
error_reporting
(PHP 4, PHP 5)
error_reporting — Sets which PHP errors are reported
Opis
$level
] )
The error_reporting() function sets the
error_reporting
directive at runtime. PHP has many levels of errors, using
this function sets that level for the duration (runtime) of
your script. If the optional level is
not set, error_reporting() will just return
the current error reporting level.
Parametry
-
level -
The new error_reporting level. It takes on either a bitmask, or named constants. Using named constants is strongly encouraged to ensure compatibility for future versions. As error levels are added, the range of integers increases, so older integer-based error levels will not always behave as expected.
The available error level constants and the actual meanings of these error levels are described in the predefined constants.
Zwracane wartości
Returns the old error_reporting
level or the current level if no level parameter is
given.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.4.0 | E_STRICT became part of E_ALL. |
| 5.3.0 | E_DEPRECATED and E_USER_DEPRECATED introduced. |
| 5.2.0 | E_RECOVERABLE_ERROR introduced. |
| 5.0.0 | E_STRICT introduced (not part of E_ALL). |
Przykłady
Przykład #1 error_reporting() examples
<?php
// Turn off all error reporting
error_reporting(0);
// Report simple running errors
error_reporting(E_ERROR | E_WARNING | E_PARSE);
// Reporting E_NOTICE can be good too (to report uninitialized
// variables or catch variable name misspellings ...)
error_reporting(E_ERROR | E_WARNING | E_PARSE | E_NOTICE);
// Report all errors except E_NOTICE
// This is the default value set in php.ini
error_reporting(E_ALL ^ E_NOTICE);
// Report all PHP errors (see changelog)
error_reporting(E_ALL);
// Report all PHP errors
error_reporting(-1);
// Same as error_reporting(E_ALL);
ini_set('error_reporting', E_ALL);
?>
Notatki
Most of E_STRICT errors are evaluated at the
compile time thus such errors are not reported in the file where
error_reporting is enhanced
to include E_STRICT errors (and vice versa).
Passing in the value -1 will show every possible error,
even when new levels and constants are added in future PHP versions. The
E_ALL constant also behaves this way as of PHP 5.4.
Zobacz też:
- The display_errors directive
- The html_errors directive
- The xmlrpc_errors directive
- ini_set() - Sets the value of a configuration option
restore_error_handler
(PHP 4 >= 4.0.1, PHP 5)
restore_error_handler — Restores the previous error handler function
Opis
Used after changing the error handler function using set_error_handler(), to revert to the previous error handler (which could be the built-in or a user defined function).
Zwracane wartości
This function always returns TRUE.
Przykłady
Przykład #1 restore_error_handler() example
Decide if unserialize() caused an error, then restore the original error handler.
<?php
function unserialize_handler($errno, $errstr)
{
echo "Invalid serialized value.\n";
}
$serialized = 'foo';
set_error_handler('unserialize_handler');
$original = unserialize($serialized);
restore_error_handler();
?>
Powyższy przykład wyświetli:
Invalid serialized value.
Notatki
Informacja:
Calling restore_error_handler() from the error_handler function is ignored.
Zobacz też:
- error_reporting() - Sets which PHP errors are reported
- set_error_handler() - Sets a user-defined error handler function
- restore_exception_handler() - Restores the previously defined exception handler function
- trigger_error() - Generates a user-level error/warning/notice message
restore_exception_handler
(PHP 5)
restore_exception_handler — Restores the previously defined exception handler function
Opis
Used after changing the exception handler function using set_exception_handler(), to revert to the previous exception handler (which could be the built-in or a user defined function).
Zwracane wartości
This function always returns TRUE.
Przykłady
Przykład #1 restore_exception_handler() example
<?php
function exception_handler_1(Exception $e)
{
echo '[' . __FUNCTION__ . '] ' . $e->getMessage();
}
function exception_handler_2(Exception $e)
{
echo '[' . __FUNCTION__ . '] ' . $e->getMessage();
}
set_exception_handler('exception_handler_1');
set_exception_handler('exception_handler_2');
restore_exception_handler();
throw new Exception('This triggers the first exception handler...');
?>
Powyższy przykład wyświetli:
[exception_handler_1] This triggers the first exception handler...
Zobacz też:
- set_exception_handler() - Sets a user-defined exception handler function
- set_error_handler() - Sets a user-defined error handler function
- restore_error_handler() - Restores the previous error handler function
- error_reporting() - Sets which PHP errors are reported
set_error_handler
(PHP 4 >= 4.0.1, PHP 5)
set_error_handler — Sets a user-defined error handler function
Opis
Sets a user function (error_handler) to handle
errors in a script.
This function can be used for defining your own way of handling errors during runtime, for example in applications in which you need to do cleanup of data/files when a critical error happens, or when you need to trigger an error under certain conditions (using trigger_error()).
It is important to remember that the standard PHP error handler is completely
bypassed for the error types specified by error_types
unless the callback function returns FALSE.
error_reporting() settings will have no effect and your
error handler will be called regardless - however you are still able to read
the current value of
error_reporting and act
appropriately. Of particular note is that this value will be 0 if the
statement that caused the error was prepended by the
@ error-control
operator.
Also note that it is your responsibility to die() if necessary. If the error-handler function returns, script execution will continue with the next statement after the one that caused an error.
The following error types cannot be handled with a user defined
function: E_ERROR, E_PARSE,
E_CORE_ERROR, E_CORE_WARNING,
E_COMPILE_ERROR,
E_COMPILE_WARNING, and
most of E_STRICT raised in the file where
set_error_handler() is called.
If errors occur before the script is executed (e.g. on file uploads) the custom error handler cannot be called since it is not registered at that time.
Parametry
-
error_handler -
The user function needs to accept two parameters: the error code, and a string describing the error. Then there are three optional parameters that may be supplied: the filename in which the error occurred, the line number in which the error occurred, and the context in which the error occurred (an array that points to the active symbol table at the point the error occurred). The function can be shown as:
handler ( int$errno, string$errstr[, string$errfile[, int$errline[, array$errcontext]]] )-
errno -
The first parameter,
errno, contains the level of the error raised, as an integer. -
errstr -
The second parameter,
errstr, contains the error message, as a string. -
errfile -
The third parameter is optional,
errfile, which contains the filename that the error was raised in, as a string. -
errline -
The fourth parameter is optional,
errline, which contains the line number the error was raised at, as an integer. -
errcontext -
The fifth parameter is optional,
errcontext, which is an array that points to the active symbol table at the point the error occurred. In other words,errcontextwill contain an array of every variable that existed in the scope the error was triggered in. User error handler must not modify error context.
If the function returns
FALSEthen the normal error handler continues. -
-
error_types -
Can be used to mask the triggering of the
error_handlerfunction just like the error_reporting ini setting controls which errors are shown. Without this mask set theerror_handlerwill be called for every error regardless to the setting of the error_reporting setting.
Zwracane wartości
Returns a string containing the previously defined error handler (if any). If
the built-in error handler is used NULL is returned. NULL is also returned
in case of an error such as an invalid callback. If the previous error handler
was a class method, this function will return an indexed array with the class
and the method name.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.2.0 |
The error handler must return FALSE to populate
$php_errormsg.
|
| 5.0.0 |
The error_types parameter was introduced.
|
| 4.3.0 |
Instead of a function name, an array containing an object reference
and a method name can also be supplied as the
error_handler.
|
| 4.0.2 |
Three optional parameters for the error_handler
user function was introduced. These are the filename, the line number,
and the context.
|
Przykłady
Przykład #1 Error handling with set_error_handler() and trigger_error()
The example below shows the handling of internal exceptions by triggering errors and handling them with a user defined function:
<?php
// error handler function
function myErrorHandler($errno, $errstr, $errfile, $errline)
{
if (!(error_reporting() & $errno)) {
// This error code is not included in error_reporting
return;
}
switch ($errno) {
case E_USER_ERROR:
echo "<b>My ERROR</b> [$errno] $errstr<br />\n";
echo " Fatal error on line $errline in file $errfile";
echo ", PHP " . PHP_VERSION . " (" . PHP_OS . ")<br />\n";
echo "Aborting...<br />\n";
exit(1);
break;
case E_USER_WARNING:
echo "<b>My WARNING</b> [$errno] $errstr<br />\n";
break;
case E_USER_NOTICE:
echo "<b>My NOTICE</b> [$errno] $errstr<br />\n";
break;
default:
echo "Unknown error type: [$errno] $errstr<br />\n";
break;
}
/* Don't execute PHP internal error handler */
return true;
}
// function to test the error handling
function scale_by_log($vect, $scale)
{
if (!is_numeric($scale) || $scale <= 0) {
trigger_error("log(x) for x <= 0 is undefined, you used: scale = $scale", E_USER_ERROR);
}
if (!is_array($vect)) {
trigger_error("Incorrect input vector, array of values expected", E_USER_WARNING);
return null;
}
$temp = array();
foreach($vect as $pos => $value) {
if (!is_numeric($value)) {
trigger_error("Value at position $pos is not a number, using 0 (zero)", E_USER_NOTICE);
$value = 0;
}
$temp[$pos] = log($scale) * $value;
}
return $temp;
}
// set to the user defined error handler
$old_error_handler = set_error_handler("myErrorHandler");
// trigger some errors, first define a mixed array with a non-numeric item
echo "vector a\n";
$a = array(2, 3, "foo", 5.5, 43.3, 21.11);
print_r($a);
// now generate second array
echo "----\nvector b - a notice (b = log(PI) * a)\n";
/* Value at position $pos is not a number, using 0 (zero) */
$b = scale_by_log($a, M_PI);
print_r($b);
// this is trouble, we pass a string instead of an array
echo "----\nvector c - a warning\n";
/* Incorrect input vector, array of values expected */
$c = scale_by_log("not array", 2.3);
var_dump($c); // NULL
// this is a critical error, log of zero or negative number is undefined
echo "----\nvector d - fatal error\n";
/* log(x) for x <= 0 is undefined, you used: scale = $scale" */
$d = scale_by_log($a, -2.5);
var_dump($d); // Never reached
?>
Powyższy przykład wyświetli coś podobnego do:
vector a
Array
(
[0] => 2
[1] => 3
[2] => foo
[3] => 5.5
[4] => 43.3
[5] => 21.11
)
----
vector b - a notice (b = log(PI) * a)
<b>My NOTICE</b> [1024] Value at position 2 is not a number, using 0 (zero)<br />
Array
(
[0] => 2.2894597716988
[1] => 3.4341896575482
[2] => 0
[3] => 6.2960143721717
[4] => 49.566804057279
[5] => 24.165247890281
)
----
vector c - a warning
<b>My WARNING</b> [512] Incorrect input vector, array of values expected<br />
NULL
----
vector d - fatal error
<b>My ERROR</b> [256] log(x) for x <= 0 is undefined, you used: scale = -2.5<br />
Fatal error on line 35 in file trigger_error.php, PHP 5.2.1 (FreeBSD)<br />
Aborting...<br />
Zobacz też:
- ErrorException
- error_reporting() - Sets which PHP errors are reported
- restore_error_handler() - Restores the previous error handler function
- trigger_error() - Generates a user-level error/warning/notice message
- error level constants
- informacje o typie callback
set_exception_handler
(PHP 5)
set_exception_handler — Sets a user-defined exception handler function
Opis
$exception_handler
)
Sets the default exception handler if an exception is not caught within a
try/catch block. Execution will stop after the
exception_handler is called.
Parametry
-
exception_handler -
Name of the function to be called when an uncaught exception occurs. This function must be defined before calling set_exception_handler(). This handler function needs to accept one parameter, which will be the exception object that was thrown.
Informacja:
NULLmay be passed instead, to reset this handler to its default state.
Zwracane wartości
Returns the name of the previously defined exception handler, or NULL on error. If
no previous handler was defined, NULL is also returned. If NULL is passed,
resetting the handler to its default state, TRUE is returned.
Przykłady
Przykład #1 set_exception_handler() example
<?php
function exception_handler($exception) {
echo "Uncaught exception: " , $exception->getMessage(), "\n";
}
set_exception_handler('exception_handler');
throw new Exception('Uncaught Exception');
echo "Not Executed\n";
?>
Zobacz też:
- restore_exception_handler() - Restores the previously defined exception handler function
- restore_error_handler() - Restores the previous error handler function
- error_reporting() - Sets which PHP errors are reported
- informacje o typie callback
- PHP 5 Exceptions
trigger_error
(PHP 4 >= 4.0.1, PHP 5)
trigger_error — Generates a user-level error/warning/notice message
Opis
$error_msg
[, int $error_type = E_USER_NOTICE
] )Used to trigger a user error condition, it can be used by in conjunction with the built-in error handler, or with a user defined function that has been set as the new error handler (set_error_handler()).
This function is useful when you need to generate a particular response to an exception at runtime.
Parametry
-
error_msg -
The designated error message for this error. It's limited to 1024 characters in length. Any additional characters beyond 1024 will be truncated.
-
error_type -
The designated error type for this error. It only works with the E_USER family of constants, and will default to
E_USER_NOTICE.
Zwracane wartości
This function returns FALSE if wrong error_type is
specified, TRUE otherwise.
Przykłady
Przykład #1 trigger_error() example
See set_error_handler() for a more extensive example.
<?php
if ($divisor == 0) {
trigger_error("Cannot divide by zero", E_USER_ERROR);
}
?>
Notatki
HTML entities in error_msg are not
escaped. Use htmlentities() on the message if
the error is to be displayed in a browser.
Zobacz też:
- error_reporting() - Sets which PHP errors are reported
- set_error_handler() - Sets a user-defined error handler function
- restore_error_handler() - Restores the previous error handler function
- The error level constants
Opis
Ta funkcja jest aliasem dla: trigger_error().
Spis treści
- debug_backtrace — Generates a backtrace
- debug_print_backtrace — Prints a backtrace
- error_get_last — Get the last occurred error
- error_log — Send an error message somewhere
- error_reporting — Sets which PHP errors are reported
- restore_error_handler — Restores the previous error handler function
- restore_exception_handler — Restores the previously defined exception handler function
- set_error_handler — Sets a user-defined error handler function
- set_exception_handler — Sets a user-defined exception handler function
- trigger_error — Generates a user-level error/warning/notice message
- user_error — Alias of trigger_error
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Przykłady
- Error Handling Funkcje
- debug_backtrace — Generates a backtrace
- debug_print_backtrace — Prints a backtrace
- error_get_last — Get the last occurred error
- error_log — Send an error message somewhere
- error_reporting — Sets which PHP errors are reported
- restore_error_handler — Restores the previous error handler function
- restore_exception_handler — Restores the previously defined exception handler function
- set_error_handler — Sets a user-defined error handler function
- set_exception_handler — Sets a user-defined exception handler function
- trigger_error — Generates a user-level error/warning/notice message
- user_error — Alias of trigger_error
htaccess-like support for all SAPIs
Wstęp
The htscanner extension gives the possibility to use htaccess-like file to configure PHP per directory, just like apache's htaccess. It is especially useful with fastcgi (ISS5/6/7, lighttpd, etc.).
Instalacja/Konfiguracja
Spis treści
Wymagania
PHP version 5.2.0 or greater.
Instalacja
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/htscanner
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Changelog |
|---|---|---|---|
| htscanner.config_file | ".htscanner" | PHP_INI_SYSTEM | |
| htscanner.default_docroot | "/" | PHP_INI_SYSTEM | |
| htscanner.default_ttl | "300" | PHP_INI_SYSTEM | |
| htscanner."stop_on_error" | "Off" | PHP_INI_SYSTEM |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Inclusion hierarchy viewer
Wstęp
Traces through and dumps the hierarchy of file inclusions and class inheritance at runtime.
The files may have been included using include(), include_once(), require(), or require_once().
Class inheritance dependencies are also reported.
Instalacja/Konfiguracja
Spis treści
Wymagania
PHP version 5.1.0 or greater.
The included gengraph.php file utilizes the » graphviz library, however, this is not required.
Instalacja
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/inclued
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| inclued.enabled | Off | PHP_INI_SYSTEM | |
| inclued.dumpdir | NULL |
PHP_INI_SYSTEM |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
inclued.enabledbool -
Whether or not to enable inclued.
-
inclued.dumpdirstring -
Location (path) to the directory that stores inclued files. If set, each PHP request will create a file. These files are serialized versions of what inclued_get_data() would produce, so may be unserialized with unserialize().
UwagaBecause every request creates a file, this directory may fill up fast!
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
To rozszerzenie nie posiada żadnych stałych.
Przykłady
Spis treści
Example that implements inclued into an application
This example demonstrates the process of implementing inclued into an existing application, and viewing the results.
Przykład #1 Getting the data within the PHP application itself (function)
<?php
// File to store the inclued information
$fp = fopen('/tmp/wp.ser', 'w');
if ($fp) {
$clue = inclued_get_data();
if ($clue) {
fwrite($fp, serialize($clue));
}
fclose($fp);
}
?>
Now that some data exists, it's time to make sense of it in the form of a graph. The inclued extension includes a PHP file named gengraph.php that creates a dot file that requires the » graphviz library. However, this form is not required.
Przykład #2 Example use of gengraph.php
This example creates an image named inclued.png that shows the inclued data.
# First, create the dot file $ php graphviz.php -i /tmp/wp.ser -o wp.dot # Next, create the image $ dot -Tpng -o inclued.png wp.dot
Przykład #3 Listing data via inclued dumps (configuration)
When using the inclued.dumpdir directive, files (include clues) are dumped with every request. Here's one way to list those files, and unserialize() them.
<?php
$path = ini_get('inclued.dumpdir');
if ($path && is_dir($path)) {
echo "Path: $path", PHP_EOL;
$inclues = new GlobIterator($path . DIRECTORY_SEPARATOR . 'inclued*');
if ($inclues->count() === 0) {
echo 'No clues today', PHP_EOL;
exit;
}
foreach ($inclues as $inclue) {
echo 'Inclued file: ', $inclue->getFilename(), PHP_EOL;
$data = file_get_contents($inclue->getPathname());
if ($data) {
$inc = unserialize($data);
echo ' -- filename: ', $inc['request']['SCRIPT_FILENAME'], PHP_EOL;
echo ' -- number of includes: ', count($inc['includes']), PHP_EOL;
}
echo PHP_EOL;
}
} else {
echo 'I am totally clueless today.', PHP_EOL;
}
?>
Powyższy przykład wyświetli coś podobnego do:
PATH: /tmp/inclued Inclued file: inclued.56521.1 -- filename: /Users/philip/test.php -- number of includes: 1 Inclued file: inclued.56563.1 -- filename: /tmp/none.php -- number of includes: 0 Inclued file: inclued.56636.1 -- filename: /tmp/three.php -- number of includes: 3
inclued Funkcje
inclued_get_data
(PECL inclued >= 0.1.0)
inclued_get_data — Get the inclued data
Opis
Get the inclued data.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
The inclued data.
Przykłady
Przykład #1 inclued_get_data() example
See the inclued examples section for ways to create graphs with this data.
<?php
include 'x.php';
$clue = inclued_get_data();
print_r($clue);
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[includes] => Array
(
[0] => Array
(
[operation] => include
[op_type] => 2
[filename] => x.php
[opened_path] => /tmp/x.php
[fromfile] => /tmp/z.php
[fromline] => 2
)
)
)
Spis treści
- inclued_get_data — Get the inclued data
Memtrack
Wstęp
The purpose of this extension is to detect the most memory hungry scripts and functions.
memtrack tracks memory consumption in PHP scripts and produces reports (warnings) when the consumption reaches certain levels set by the user. This is achieved by replacing default executor function by a special function which compares memory usage before and after running the original executor - this way we can tell how much the memory usage has changed during the execution of the current part of the code.
Zend Engine runs its executor for each opcode array (op_array), which usually means function, plain script and such, so memtrack doesn't have any noticeable effect on performance.
memtrack doesn't provide any functions, there are only INI directives which allow you to configure the way it should work.
Ten moduł jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie tych funkcji, ich nazw, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tego modułu na własne ryzyko.
Instalacja/Konfiguracja
Spis treści
Wymagania
Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.
Instalacja
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/memtrack
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian |
|---|---|---|
| memtrack.enabled | "0" | PHP_INI_SYSTEM |
| memtrack.soft_limit | "0" | PHP_INI_ALL |
| memtrack.hard_limit | "0" | PHP_INI_ALL |
| memtrack.vm_limit | "0" | PHP_INI_ALL |
| memtrack.ignore_functions | "" | PHP_INI_SYSTEM |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
memtrack.enabledboolean -
Disables or enables the extension. Default value is 0, i.e. disabled.
-
memtrack.soft_limitint -
Soft memory limit.
The extension checks memory consumption before and after executing an op_array and produces a warning is the difference between the two values is equal to or greater than the soft limit, but only if the function is not ignored.
Setting this option to 0 also disables both soft and hard limit warnings. Default value is 0, i.e. no warnings is produced.
-
memtrack.hard_limitint -
Hard memory limit.
The extension checks memory consumption before and after executing an op_array and produces a warning is the difference between the two values is equal to or greater than the hard limit, even if the function is ignored. Setting this option to 0 disables hard limit warnings completely. Default value is 0, i.e. no hard limit warnings is produced.
-
memtrack.vm_limitint -
Virtual memory limit (set on a process).
This limit is checked only on shutdown and a warning is produced if the value is greater than or equal to the limit.
This option is currently supported only on OSes where mallinfo() function is available (i.e. Linux).
-
memtrack.ignore_functionsstring -
A comma or whitespace-separated list of functions which are to be ignored by soft_limit. The values are case-insensitive, for class methods use class::method syntax.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
To rozszerzenie nie posiada żadnych stałych.
Przykłady
Spis treści
Basic usage
Basic example on using memtrack extension:
Przykład #1 Creating large array in a function
<?php
/* /tmp/example1.php */
function foo() {
$a = array();
for ($i = 0; $i < 10000; $i++) $a[] = "test";
return $a;
}
$arr = foo();
?>
Run the example with the following command:
php -d memtrack.enabled=1 -d memtrack.soft_limit=1M -d memtrack.vm_limit=3M /tmp/example1.php
Powyższy przykład wyświetli coś podobnego do:
Warning: [memtrack] [pid 26177] user function foo() executed in /tmp/example1.php on line 10 allocated 4194304 bytes in /tmp/example1.php on line 0 Warning: [memtrack] [pid 26177] virtual memory usage on shutdown: 32911360 bytes in Unknown on line 0
Output Buffering Control
Wstęp
The Output Control functions allow you to control when output is sent from the script. This can be useful in several different situations, especially if you need to send headers to the browser after your script has began outputting data. The Output Control functions do not affect headers sent using header() or setcookie(), only functions such as echo() and data between blocks of PHP code.
Informacja:
When upgrading from PHP 4.1.x (and 4.2.x) to 4.3.x due to a bug in earlier versions you must ensure that implicit_flush is OFF in your php.ini, otherwise any output with ob_start() will not be hidden from output.
Instalacja/Konfiguracja
Spis treści
Wymagania
Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.
Instalacja
By używać tych funkcji, nie trzeba niczego instalować. Są one częścią jądra PHP.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| output_buffering | "0" | PHP_INI_PERDIR | |
| output_handler | NULL | PHP_INI_PERDIR | Available since PHP 4.0.4. |
| implicit_flush | "0" | PHP_INI_ALL | PHP_INI_PERDIR in PHP <= 4.2.3. |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
output_bufferingboolean/integer -
You can enable output buffering for all files by setting this directive to 'On'. If you wish to limit the size of the buffer to a certain size - you can use a maximum number of bytes instead of 'On', as a value for this directive (e.g., output_buffering=4096). As of PHP 4.3.5, this directive is always Off in PHP-CLI.
-
output_handlerstring -
You can redirect all of the output of your scripts to a function. For example, if you set output_handler to mb_output_handler(), character encoding will be transparently converted to the specified encoding. Setting any output handler automatically turns on output buffering.
Informacja:
You cannot use both mb_output_handler() with ob_iconv_handler() and you cannot use both ob_gzhandler() and zlib.output_compression.
Informacja:
Only built-in functions can be used with this directive. For user defined functions, use ob_start().
-
implicit_flushboolean -
FALSEby default. Changing this toTRUEtells PHP to tell the output layer to flush itself automatically after every output block. This is equivalent to calling the PHP function flush() after each and every call to print() or echo() and each and every HTML block.When using PHP within an web environment, turning this option on has serious performance implications and is generally recommended for debugging purposes only. This value defaults to
TRUEwhen operating under the CLI SAPI.See also ob_implicit_flush().
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
To rozszerzenie nie posiada żadnych stałych.
Przykłady
Spis treści
Basic usage
Przykład #1 Output Control example
<?php
ob_start();
echo "Hello\n";
setcookie("cookiename", "cookiedata");
ob_end_flush();
?>
In the above example, the output from echo() would be stored in the output buffer until ob_end_flush() was called. In the mean time, the call to setcookie() successfully stored a cookie without causing an error. (You can not normally send headers to the browser after data has already been sent.)
Output Control Funkcje
Zobacz też:
See also header() and setcookie().
flush
(PHP 4, PHP 5)
flush — Flush the output buffer
Opis
Flushes the write buffers of PHP and whatever backend PHP is using (CGI, a web server, etc). This attempts to push current output all the way to the browser with a few caveats.
flush() may not be able to override the buffering scheme of your web server and it has no effect on any client-side buffering in the browser. It also doesn't affect PHP's userspace output buffering mechanism. This means you will have to call both ob_flush() and flush() to flush the ob output buffers if you are using those.
Several servers, especially on Win32, will still buffer the output from your script until it terminates before transmitting the results to the browser.
Server modules for Apache like mod_gzip may do buffering of their own that will cause flush() to not result in data being sent immediately to the client.
Even the browser may buffer its input before displaying it. Netscape, for example, buffers text until it receives an end-of-line or the beginning of a tag, and it won't render tables until the </table> tag of the outermost table is seen.
Some versions of Microsoft Internet Explorer will only start to display the page after they have received 256 bytes of output, so you may need to send extra whitespace before flushing to get those browsers to display the page.
Zwracane wartości
Nie jest zwracana żadna wartość.
ob_clean
(PHP 4 >= 4.2.0, PHP 5)
ob_clean — Clean (erase) the output buffer
Opis
This function discards the contents of the output buffer.
This function does not destroy the output buffer like ob_end_clean() does.
Zwracane wartości
Nie jest zwracana żadna wartość.
Zobacz też:
- ob_flush() - Flush (send) the output buffer
- ob_end_flush() - Flush (send) the output buffer and turn off output buffering
- ob_end_clean() - Clean (erase) the output buffer and turn off output buffering
ob_end_clean
(PHP 4, PHP 5)
ob_end_clean — Clean (erase) the output buffer and turn off output buffering
Opis
This function discards the contents of the topmost output buffer and turns off this output buffering. If you want to further process the buffer's contents you have to call ob_get_contents() before ob_end_clean() as the buffer contents are discarded when ob_end_clean() is called.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu. Reasons for failure are first that you called the
function without an active buffer or that for some reason a buffer could
not be deleted (possible for special buffer).
Błędy/Wyjątki
If the function fails it generates an E_NOTICE.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.2.0 | The boolean return value was added. |
Przykłady
The following example shows an easy way to get rid of all output buffers:
Przykład #1 ob_end_clean() example
<?php
ob_start();
echo 'Text that won\'t get displayed.';
ob_end_clean();
?>
Zobacz też:
- ob_start() - Turn on output buffering
- ob_get_contents() - Return the contents of the output buffer
- ob_flush() - Flush (send) the output buffer
ob_end_flush
(PHP 4, PHP 5)
ob_end_flush — Flush (send) the output buffer and turn off output buffering
Opis
This function will send the contents of the topmost output buffer (if any) and turn this output buffer off. If you want to further process the buffer's contents you have to call ob_get_contents() before ob_end_flush() as the buffer contents are discarded after ob_end_flush() is called.
Informacja: This function is similar to ob_get_flush(), except that ob_get_flush() returns the buffer as a string.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu. Reasons for failure are first that you called the
function without an active buffer or that for some reason a buffer could
not be deleted (possible for special buffer).
Błędy/Wyjątki
If the function fails it generates an E_NOTICE.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.2.0 | The boolean return value was added. |
Przykłady
Przykład #1 ob_end_flush() example
The following example shows an easy way to flush and end all output buffers:
<?php
while (@ob_end_flush());
?>
Zobacz też:
- ob_start() - Turn on output buffering
- ob_get_contents() - Return the contents of the output buffer
- ob_get_flush() - Flush the output buffer, return it as a string and turn off output buffering
- ob_flush() - Flush (send) the output buffer
- ob_end_clean() - Clean (erase) the output buffer and turn off output buffering
ob_flush
(PHP 4 >= 4.2.0, PHP 5)
ob_flush — Flush (send) the output buffer
Opis
This function will send the contents of the output buffer (if any). If you want to further process the buffer's contents you have to call ob_get_contents() before ob_flush() as the buffer contents are discarded after ob_flush() is called.
This function does not destroy the output buffer like ob_end_flush() does.
Zwracane wartości
Nie jest zwracana żadna wartość.
Zobacz też:
- ob_get_contents() - Return the contents of the output buffer
- ob_clean() - Clean (erase) the output buffer
- ob_end_flush() - Flush (send) the output buffer and turn off output buffering
- ob_end_clean() - Clean (erase) the output buffer and turn off output buffering
ob_get_clean
(PHP 4 >= 4.3.0, PHP 5)
ob_get_clean — Get current buffer contents and delete current output buffer
Opis
Gets the current buffer contents and delete current output buffer.
ob_get_clean() essentially executes both ob_get_contents() and ob_end_clean().
Zwracane wartości
Returns the contents of the output buffer and end output buffering.
If output buffering isn't active then FALSE is returned.
Przykłady
Przykład #1 A simple ob_get_clean() example
<?php
ob_start();
echo "Hello World";
$out = ob_get_clean();
$out = strtolower($out);
var_dump($out);
?>
Powyższy przykład wyświetli:
string(11) "hello world"
Zobacz też:
- ob_get_contents() - Return the contents of the output buffer
- ob_start() - Turn on output buffering
ob_get_contents
(PHP 4, PHP 5)
ob_get_contents — Return the contents of the output buffer
Opis
Gets the contents of the output buffer without clearing it.
Zwracane wartości
This will return the contents of the output buffer or FALSE, if output
buffering isn't active.
Przykłady
Przykład #1 A simple ob_get_contents() example
<?php
ob_start();
echo "Hello ";
$out1 = ob_get_contents();
echo "World";
$out2 = ob_get_contents();
ob_end_clean();
var_dump($out1, $out2);
?>
Powyższy przykład wyświetli:
string(6) "Hello " string(11) "Hello World"
Zobacz też:
- ob_start() - Turn on output buffering
- ob_get_length() - Return the length of the output buffer
ob_get_flush
(PHP 4 >= 4.3.0, PHP 5)
ob_get_flush — Flush the output buffer, return it as a string and turn off output buffering
Opis
ob_get_flush() flushes the output buffer, return it as a string and turns off output buffering.
Informacja: This function is similar to ob_end_flush(), except that this function returns the buffer as a string.
Zwracane wartości
Returns the output buffer or FALSE if no buffering is active.
Przykłady
Przykład #1 ob_get_flush() example
<?php
//using output_buffering=On
print_r(ob_list_handlers());
//save buffer in a file
$buffer = ob_get_flush();
file_put_contents('buffer.txt', $buffer);
print_r(ob_list_handlers());
?>
Powyższy przykład wyświetli:
Array
(
[0] => default output handler
)
Array
(
)
Zobacz też:
- ob_end_clean() - Clean (erase) the output buffer and turn off output buffering
- ob_end_flush() - Flush (send) the output buffer and turn off output buffering
- ob_list_handlers() - List all output handlers in use
ob_get_length
(PHP 4 >= 4.0.2, PHP 5)
ob_get_length — Return the length of the output buffer
Opis
This will return the length of the contents in the output buffer.
Zwracane wartości
Returns the length of the output buffer contents or FALSE if no
buffering is active.
Przykłady
Przykład #1 A simple ob_get_length() example
<?php
ob_start();
echo "Hello ";
$len1 = ob_get_length();
echo "World";
$len2 = ob_get_length();
ob_end_clean();
echo $len1 . ", ." . $len2;
?>
Powyższy przykład wyświetli:
6, 11
Zobacz też:
- ob_start() - Turn on output buffering
- ob_get_contents() - Return the contents of the output buffer
ob_get_level
(PHP 4 >= 4.2.0, PHP 5)
ob_get_level — Return the nesting level of the output buffering mechanism
Opis
Returns the nesting level of the output buffering mechanism.
Zwracane wartości
Returns the level of nested output buffering handlers or zero if output buffering is not active.
Zobacz też:
- ob_start() - Turn on output buffering
- ob_get_contents() - Return the contents of the output buffer
ob_get_status
(PHP 4 >= 4.2.0, PHP 5)
ob_get_status — Get status of output buffers
Opis
$full_status = FALSE
] )
ob_get_status() returns status information on either
the top level output buffer or all active output buffer levels if
full_status is set to TRUE.
Parametry
-
full_status -
TRUEto return all active output buffer levels. IfFALSEor not set, only the top level output buffer is returned.
Zwracane wartości
If called without the full_status parameter
or with full_status = FALSE a simple array
with the following elements is returned:
Array
(
[level] => 2
[type] => 0
[status] => 0
[name] => URL-Rewriter
[del] => 1
)
If called with full_status = TRUE an array
with one element for each active output buffer level is returned.
The output level is used as key of the top level array and each array
element itself is another array holding status information
on one active output level.
Array
(
[0] => Array
(
[chunk_size] => 0
[size] => 40960
[block_size] => 10240
[type] => 1
[status] => 0
[name] => default output handler
[del] => 1
)
[1] => Array
(
[chunk_size] => 0
[size] => 40960
[block_size] => 10240
[type] => 0
[buffer_size] => 0
[status] => 0
[name] => URL-Rewriter
[del] => 1
)
)
The full output contains these additional elements:
Zobacz też:
- ob_get_level() - Return the nesting level of the output buffering mechanism
- ob_list_handlers() - List all output handlers in use
ob_gzhandler
(PHP 4 >= 4.0.4, PHP 5)
ob_gzhandler — ob_start callback function to gzip output buffer
Opis
$buffer
, int $mode
)
ob_gzhandler() is intended to be used as a callback
function for ob_start() to help facilitate sending
gz-encoded data to web browsers that support compressed web pages.
Before ob_gzhandler() actually sends compressed data,
it determines what type of content encoding the browser will accept
("gzip", "deflate" or none at all) and will return its output accordingly.
All browsers are supported since it's up to the browser to send the
correct header saying that it accepts compressed web pages. If a browser
doesn't support compressed pages this function returns FALSE.
Parametry
-
buffer -
-
mode -
Zwracane wartości
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.0.5 |
The mode parameter was added.
|
Przykłady
Przykład #1 ob_gzhandler() example
<?php
ob_start("ob_gzhandler");
?>
<html>
<body>
<p>This should be a compressed page.</p>
</body>
</html>
Notatki
Informacja:
ob_gzhandler() requires the zlib extension.
Informacja:
You cannot use both ob_gzhandler() and zlib.output_compression. Also note that using zlib.output_compression is preferred over ob_gzhandler().
Zobacz też:
- ob_start() - Turn on output buffering
- ob_end_flush() - Flush (send) the output buffer and turn off output buffering
ob_implicit_flush
(PHP 4, PHP 5)
ob_implicit_flush — Turn implicit flush on/off
Opis
$flag = true
] )ob_implicit_flush() will turn implicit flushing on or off. Implicit flushing will result in a flush operation after every output call, so that explicit calls to flush() will no longer be needed.
Parametry
-
flag -
TRUEto turn implicit flushing on,FALSEotherwise.
Zwracane wartości
Nie jest zwracana żadna wartość.
Zobacz też:
- flush() - Flush the output buffer
- ob_start() - Turn on output buffering
- ob_end_flush() - Flush (send) the output buffer and turn off output buffering
ob_list_handlers
(PHP 4 >= 4.3.0, PHP 5)
ob_list_handlers — List all output handlers in use
Opis
Lists all output handlers in use.
Zwracane wartości
This will return an array with the output handlers in use (if any). If output_buffering is enabled or an anonymous function was used with ob_start(), ob_list_handlers() will return "default output handler".
Przykłady
Przykład #1 ob_list_handlers() example
<?php
//using output_buffering=On
print_r(ob_list_handlers());
ob_end_flush();
ob_start("ob_gzhandler");
print_r(ob_list_handlers());
ob_end_flush();
// anonymous functions
ob_start(create_function('$string', 'return $string;'));
print_r(ob_list_handlers());
ob_end_flush();
?>
Powyższy przykład wyświetli:
Array
(
[0] => default output handler
)
Array
(
[0] => ob_gzhandler
)
Array
(
[0] => default output handler
)
Zobacz też:
- ob_end_clean() - Clean (erase) the output buffer and turn off output buffering
- ob_end_flush() - Flush (send) the output buffer and turn off output buffering
- ob_get_flush() - Flush the output buffer, return it as a string and turn off output buffering
- ob_start() - Turn on output buffering
ob_start
(PHP 4, PHP 5)
ob_start — Turn on output buffering
Opis
$output_callback
[, int $chunk_size = 0
[, bool $erase = true
]]] )This function will turn output buffering on. While output buffering is active no output is sent from the script (other than headers), instead the output is stored in an internal buffer.
The contents of this internal buffer may be copied into a string variable using ob_get_contents(). To output what is stored in the internal buffer, use ob_end_flush(). Alternatively, ob_end_clean() will silently discard the buffer contents.
Some web servers (e.g. Apache) change the working directory of a script when calling the callback function. You can change it back by e.g. chdir(dirname($_SERVER['SCRIPT_FILENAME'])) in the callback function.
Output buffers are stackable, that is, you may call ob_start() while another ob_start() is active. Just make sure that you call ob_end_flush() the appropriate number of times. If multiple output callback functions are active, output is being filtered sequentially through each of them in nesting order.
Parametry
-
output_callback -
An optional
output_callbackfunction may be specified. This function takes a string as a parameter and should return a string. The function will be called when the output buffer is flushed (sent) or cleaned (with ob_flush(), ob_clean() or similar function) or when the output buffer is flushed to the browser at the end of the request. Whenoutput_callbackis called, it will receive the contents of the output buffer as its parameter and is expected to return a new output buffer as a result, which will be sent to the browser. If theoutput_callbackis not a callable function, this function will returnFALSE.If the callback function has two parameters, the second parameter is filled with a bit-field consisting of
PHP_OUTPUT_HANDLER_START,PHP_OUTPUT_HANDLER_CONTandPHP_OUTPUT_HANDLER_END.If
output_callbackreturnsFALSEoriginal input is sent to the browser.The
output_callbackparameter may be bypassed by passing aNULLvalue.ob_end_clean(), ob_end_flush(), ob_clean(), ob_flush() and ob_start() may not be called from a callback function. If you call them from callback function, the behavior is undefined. If you would like to delete the contents of a buffer, return "" (a null string) from callback function. You can't even call functions using the output buffering functions like print_r($expression, true) or highlight_file($filename, true) from a callback function.
Informacja:
In PHP 4.0.4, ob_gzhandler() was introduced to facilitate sending gz-encoded data to web browsers that support compressed web pages. ob_gzhandler() determines what type of content encoding the browser will accept and will return its output accordingly.
-
chunk_size -
If the optional parameter
chunk_sizeis passed, the buffer will be flushed after any output call which causes the buffer's length to equal or exceedchunk_size. The default value 0 means that the output function will only be called when the output buffer is closed.Prior to PHP 5.4.0, the value 1 was a special case value that set the chunk size to 4096 bytes.
-
erase -
If the optional parameter
eraseis set toFALSE, the buffer will not be deleted until the script finishes. This causes that flushing and cleaning functions would issue a notice and returnFALSEif called.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.4.0 | A chunk size of 1 now results in chunks of 1 byte being sent to the output buffer. |
| 4.3.2 |
This function was changed to return FALSE in case the passed
output_callback can not be executed.
|
| 4.2.0 |
Added the erase parameter.
|
Przykłady
Przykład #1 User defined callback function example
<?php
function callback($buffer)
{
// replace all the apples with oranges
return (str_replace("apples", "oranges", $buffer));
}
ob_start("callback");
?>
<html>
<body>
<p>It's like comparing apples to oranges.</p>
</body>
</html>
<?php
ob_end_flush();
?>
Powyższy przykład wyświetli:
<html> <body> <p>It's like comparing oranges to oranges.</p> </body> </html>
Zobacz też:
- ob_get_contents() - Return the contents of the output buffer
- ob_end_clean() - Clean (erase) the output buffer and turn off output buffering
- ob_end_flush() - Flush (send) the output buffer and turn off output buffering
- ob_implicit_flush() - Turn implicit flush on/off
- ob_gzhandler() - ob_start callback function to gzip output buffer
- ob_iconv_handler() - Konwersja kodowania znaków jako uchwyt buforu wyjścia
- mb_output_handler() - Callback function converts character encoding in output buffer
- ob_tidyhandler() - Funkcja zwrotna do czyszczenia bufora wyjścia dla funkcji ob_start
output_add_rewrite_var
(PHP 4 >= 4.3.0, PHP 5)
output_add_rewrite_var — Add URL rewriter values
Opis
$name
, string $value
)This function adds another name/value pair to the URL rewrite mechanism. The name and value will be added to URLs (as GET parameter) and forms (as hidden input fields) the same way as the session ID when transparent URL rewriting is enabled with session.use_trans_sid. Please note that absolute URLs (http://example.com/..) aren't rewritten.
This function's behavior is controlled by the url_rewriter.tags php.ini parameter.
Informacja: Calling this function will implicitly start output buffering if it is not active already.
Parametry
-
name -
The variable name.
-
value -
The variable value.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 output_add_rewrite_var() example
<?php
output_add_rewrite_var('var', 'value');
// some links
echo '<a href="file.php">link</a>
<a href="http://example.com">link2</a>';
// a form
echo '<form action="script.php" method="post">
<input type="text" name="var2" />
</form>';
print_r(ob_list_handlers());
?>
Powyższy przykład wyświetli:
<a href="file.php?var=value">link</a>
<a href="http://example.com">link2</a>
<form action="script.php" method="post">
<input type="hidden" name="var" value="value" />
<input type="text" name="var2" />
</form>
Array
(
[0] => URL-Rewriter
)
Zobacz też:
- output_reset_rewrite_vars() - Reset URL rewriter values
- ob_flush() - Flush (send) the output buffer
- ob_list_handlers() - List all output handlers in use
output_reset_rewrite_vars
(PHP 4 >= 4.3.0, PHP 5)
output_reset_rewrite_vars — Reset URL rewriter values
Opis
This function resets the URL rewriter and removes all rewrite variables previously set by the output_add_rewrite_var() function or the session mechanism (if session.use_trans_sid was set on session_start()).
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 output_reset_rewrite_vars() example
<?php
session_start();
output_add_rewrite_var('var', 'value');
echo '<a href="file.php">link</a>';
ob_flush();
output_reset_rewrite_vars();
echo '<a href="file.php">link</a>';
?>
Powyższy przykład wyświetli:
<a href="file.php?PHPSESSID=xxx&var=value">link</a> <a href="file.php">link</a>
Zobacz też:
- output_add_rewrite_var() - Add URL rewriter values
- ob_flush() - Flush (send) the output buffer
- ob_list_handlers() - List all output handlers in use
- session_start() - Inicjalizuj dane sesji
Spis treści
- flush — Flush the output buffer
- ob_clean — Clean (erase) the output buffer
- ob_end_clean — Clean (erase) the output buffer and turn off output buffering
- ob_end_flush — Flush (send) the output buffer and turn off output buffering
- ob_flush — Flush (send) the output buffer
- ob_get_clean — Get current buffer contents and delete current output buffer
- ob_get_contents — Return the contents of the output buffer
- ob_get_flush — Flush the output buffer, return it as a string and turn off output buffering
- ob_get_length — Return the length of the output buffer
- ob_get_level — Return the nesting level of the output buffering mechanism
- ob_get_status — Get status of output buffers
- ob_gzhandler — ob_start callback function to gzip output buffer
- ob_implicit_flush — Turn implicit flush on/off
- ob_list_handlers — List all output handlers in use
- ob_start — Turn on output buffering
- output_add_rewrite_var — Add URL rewriter values
- output_reset_rewrite_vars — Reset URL rewriter values
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Przykłady
- Output Control Funkcje
- flush — Flush the output buffer
- ob_clean — Clean (erase) the output buffer
- ob_end_clean — Clean (erase) the output buffer and turn off output buffering
- ob_end_flush — Flush (send) the output buffer and turn off output buffering
- ob_flush — Flush (send) the output buffer
- ob_get_clean — Get current buffer contents and delete current output buffer
- ob_get_contents — Return the contents of the output buffer
- ob_get_flush — Flush the output buffer, return it as a string and turn off output buffering
- ob_get_length — Return the length of the output buffer
- ob_get_level — Return the nesting level of the output buffering mechanism
- ob_get_status — Get status of output buffers
- ob_gzhandler — ob_start callback function to gzip output buffer
- ob_implicit_flush — Turn implicit flush on/off
- ob_list_handlers — List all output handlers in use
- ob_start — Turn on output buffering
- output_add_rewrite_var — Add URL rewriter values
- output_reset_rewrite_vars — Reset URL rewriter values
Object property and method call overloading
Wstęp
The purpose of this extension is to allow overloading of object property access and method calls. Only one function is defined in this extension, overload() which takes the name of the class that should have this functionality enabled. The class named has to define appropriate methods if it wants to have this functionality: __get(), __set() and __call() respectively for getting/setting a property, or calling a method. This way overloading can be selective. Inside these handler functions the overloading is disabled so you can access object properties normally.
Ten moduł jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie tych funkcji, ich nazw, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tego modułu na własne ryzyko.
This extension is not a part of PHP 5. PHP 5 supports __get(), __set() and __call() natively. See the Overloading in PHP 5 page for more information.
Instalacja/Konfiguracja
Spis treści
Wymagania
Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.
Instalacja
Aby używać tych funkcji musimy skompilować PHP z opcją --enable-overload . Począwszy od PHP 4.3.0 to rozszerzenie jest domyślnie włączone. Możemy wyłączyć obsługę przeciążania podczas kompilacji PHP za pomocą opcji --disable--overload .
PHP w wersji dla systemów Windows posiada wbudowaną obsługę dla tego rozszerzenia. Nie trzeba ładować żadnych dodatkowych rozszerzeń, aby używać tych funkcji.
Informacja: Obsługa przeciążania jest dostępna od PHP 4.3.0.
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
To rozszerzenie nie posiada żadnych stałych.
Przykłady
Spis treści
Basic usage
Some simple examples on using the overload() function:
Przykład #1 Overloading a PHP class
<?php
class OO {
var $a = 111;
var $elem = array('b' => 9, 'c' => 42);
// Callback method for getting a property
function __get($prop_name, &$prop_value)
{
if (isset($this->elem[$prop_name])) {
$prop_value = $this->elem[$prop_name];
return true;
} else {
return false;
}
}
// Callback method for setting a property
function __set($prop_name, $prop_value)
{
$this->elem[$prop_name] = $prop_value;
return true;
}
}
// Here we overload the OO object
overload('OO');
$o = new OO;
echo "\$o->a: $o->a\n"; // print: $o->a: 111
echo "\$o->b: $o->b\n"; // print: $o->b: 9
echo "\$o->c: $o->c\n"; // print: $o->c: 42
echo "\$o->d: $o->d\n"; // print: $o->d:
// add a new item to the $elem array in OO
$o->x = 56;
// instantiate stdclass (it is built-in PHP 4)
// $val is not overloaded!
$val = new stdclass;
$val->prop = 555;
// Set "a" to be an array with the $val object in it
// But __set() will put this in the $elem array
$o->a = array($val);
var_dump($o->a[0]->prop);
?>
Object overloading Funkcje
overload
(PHP 4 >= 4.3.0)
overload — Umożliwienie przeciążania właściwości i wołania metod dla klasy
Opis
$nazwa_klasy
)
Funkcja overload() umożliwia przeciążanie właściwości
i wołania metod dla klasy określonej przez nazwa_klasy.
Parametry
-
nazwa_klasy -
Przeciąża nazwę klasy, jako string
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Zobacz przykład w sekcji wprowadzającej tej części podręcznika.
Spis treści
- overload — Umożliwienie przeciążania właściwości i wołania metod dla klasy
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Przykłady
- Object overloading Funkcje
- overload — Umożliwienie przeciążania właściwości i wołania metod dla klasy
PHP Options and Information
Wstęp
This functions enable you to get a lot of information about PHP itself, e.g. runtime configuration, loaded extensions, version and much more. You'll also find functions to set options for your running PHP. The probably best known function of PHP - phpinfo() - can be found here.
Instalacja/Konfiguracja
Spis treści
Wymagania
Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.
Instalacja
By używać tych funkcji, nie trzeba niczego instalować. Są one częścią jądra PHP.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| assert.active | "1" | PHP_INI_ALL | |
| assert.bail | "0" | PHP_INI_ALL | |
| assert.warning | "1" | PHP_INI_ALL | |
| assert.callback | NULL | PHP_INI_ALL | |
| assert.quiet_eval | "0" | PHP_INI_ALL | |
| enable_dl | "1" | PHP_INI_SYSTEM | Ta przestarzała funkcja zostanie na pewno w przyszłości usunięta. |
| max_execution_time | "30" | PHP_INI_ALL | |
| max_input_time | "-1" | PHP_INI_PERDIR | Available since PHP 4.3.0. |
| max_input_nesting_level | "64" | PHP_INI_PERDIR | Available since PHP 4.4.8 and PHP 5.2.3. |
| max_input_vars | 1000 | PHP_INI_PERDIR | Available since PHP 5.3.9. |
| magic_quotes_gpc | "1" | PHP_INI_PERDIR | PHP_INI_ALL in PHP <= 4.2.3. Ta przestarzała funkcja zostanie na pewno w przyszłości usunięta. |
| magic_quotes_runtime | "0" | PHP_INI_ALL | Ta przestarzała funkcja zostanie na pewno w przyszłości usunięta. |
| zend.enable_gc | "1" | PHP_INI_ALL | Available since PHP 5.3.0. |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
assert.activeboolean -
Enable assert() evaluation.
-
assert.bailboolean -
Terminate script execution on failed assertions.
-
assert.warningboolean -
Issue a PHP warning for each failed assertion.
-
assert.callbackstring -
user function to call on failed assertions
-
assert.quiet_evalboolean -
Use the current setting of error_reporting() during assertion expression evaluation. If enabled, no errors are shown (implicit error_reporting(0)) while evaluation. If disabled, errors are shown according to the settings of error_reporting()
-
enable_dlboolean -
This directive is really only useful in the Apache module version of PHP. You can turn dynamic loading of PHP extensions with dl() on and off per virtual server or per directory.
The main reason for turning dynamic loading off is security. With dynamic loading, it's possible to ignore all open_basedir restrictions. The default is to allow dynamic loading, except when using tryb bezpieczny. In tryb bezpieczny, it's always impossible to use dl().
-
max_execution_timeinteger -
This sets the maximum time in seconds a script is allowed to run before it is terminated by the parser. This helps prevent poorly written scripts from tying up the server. The default setting is 30. When running PHP from the command line the default setting is 0.
The maximum execution time is not affected by system calls, stream operations etc. Please see the set_time_limit() function for more details.
You can not change this setting with ini_set() when running in tryb bezpieczny. The only workaround is to turn off safe mode or by changing the time limit in the php.ini.
Your web server can have other timeout configurations that may also interrupt PHP execution. Apache has a Timeout directive and IIS has a CGI timeout function. Both default to 300 seconds. See your web server documentation for specific details.
-
max_input_timeinteger -
This sets the maximum time in seconds a script is allowed to parse input data, like POST and GET. It is measured from the moment of receiving all data on the server to the start of script execution.
-
max_input_nesting_levelinteger -
Sets the max nesting depth of input variables (i.e. $_GET, $_POST..)
-
max_input_varsinteger -
How many input variables may be accepted. Use of this directive mitigates the possibility of denial of service attacks which use hash collisions. If there are more input variables than specified by this directive, an
E_WARNINGis issued, and further input variables are truncated from the request. This limit applies only to each nesting level of a multi-dimensional input array. -
magic_quotes_gpcboolean -
Ostrzeżenie
This feature has been DEPRECATED as of PHP 5.3.0 and REMOVED as of PHP 5.4.0.
Sets the magic_quotes state for GPC (Get/Post/Cookie) operations. When magic_quotes are on, all ' (single-quote), " (double quote), \ (backslash) and NUL's are escaped with a backslash automatically.
Informacja:
In PHP 4, also $_ENV variables are escaped.
Informacja:
If the magic_quotes_sybase directive is also ON it will completely override magic_quotes_gpc. Having both directives enabled means only single quotes are escaped as ''. Double quotes, backslashes and NUL's will remain untouched and unescaped.
See also get_magic_quotes_gpc()
-
magic_quotes_runtimeboolean -
Ostrzeżenie
This feature has been DEPRECATED as of PHP 5.3.0 and REMOVED as of PHP 5.4.0.
If
magic_quotes_runtimeis enabled, most functions that return data from any sort of external source including databases and text files will have quotes escaped with a backslash. If magic_quotes_sybase is also on, a single-quote is escaped with a single-quote instead of a backslash.Functions affected by
magic_quotes_runtime(does not include functions from PECL):- get_meta_tags()
- file_get_contents()
- file()
- fgets()
- fwrite()
- fread()
- fputcsv()
- stream_socket_recvfrom()
- exec()
- system()
- passthru()
- stream_get_contents()
- bzread()
- gzfile()
- gzgets()
- gzwrite()
- gzread()
- exif_read_data()
- dba_insert()
- dba_replace()
- dba_fetch()
- ibase_fetch_row()
- ibase_fetch_assoc()
- ibase_fetch_object()
- mssql_fetch_row()
- mssql_fetch_object()
- mssql_fetch_array()
- mssql_fetch_assoc()
- mysqli_fetch_row()
- mysqli_fetch_array()
- mysqli_fetch_assoc()
- mysqli_fetch_object()
- pg_fetch_row()
- pg_fetch_assoc()
- pg_fetch_array()
- pg_fetch_object()
- pg_fetch_all()
- pg_select()
- sybase_fetch_object()
- sybase_fetch_array()
- sybase_fetch_assoc()
- SplFileObject::fgets()
- SplFileObject::fgetcsv()
- SplFileObject::fwrite()
-
zend.enable_gcboolean -
Enables or disables the circular reference collector.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
Poniższe stałe są częścią jądra PHP a więc są zawsze widoczne.
| Constant | Value | Description |
|---|---|---|
CREDITS_GROUP |
1 | A list of the core developers |
CREDITS_GENERAL |
2 | General credits: Language design and concept, PHP authors and SAPI module. |
CREDITS_SAPI |
4 | A list of the server API modules for PHP, and their authors. |
CREDITS_MODULES |
8 | A list of the extension modules for PHP, and their authors. |
CREDITS_DOCS |
16 | The credits for the documentation team. |
CREDITS_FULLPAGE |
32 | Usually used in combination with the other flags. Indicates that a complete stand-alone HTML page needs to be printed including the information indicated by the other flags. |
CREDITS_QA |
64 | The credits for the quality assurance team. |
CREDITS_ALL |
-1 | All the credits, equivalent to using: CREDITS_DOCS + CREDITS_GENERAL + CREDITS_GROUP + CREDITS_MODULES + CREDITS_QA CREDITS_FULLPAGE. It generates a complete stand-alone HTML page with the appropriate tags. This is the default value. |
| Constant | Value | Description |
|---|---|---|
INFO_GENERAL |
1 | The configuration line, php.ini location, build date, Web Server, System and more. |
INFO_CREDITS |
2 | PHP Credits. See also phpcredits(). |
INFO_CONFIGURATION |
4 | Current Local and Master values for PHP directives. See also ini_get(). |
INFO_MODULES |
8 | Loaded modules and their respective settings. |
INFO_ENVIRONMENT |
16 | Environment Variable information that's also available in $_ENV. |
INFO_VARIABLES |
32 | Shows all predefined variables from EGPCS (Environment, GET, POST, Cookie, Server). |
INFO_LICENSE |
64 | PHP License information. See also the » license faq. |
INFO_ALL |
-1 | Shows all of the above. This is the default value. |
| Constant | Value | Description |
|---|---|---|
| INI_USER | 1 | Unused |
| INI_PERDIR | 2 | Unused |
| INI_SYSTEM | 4 | Unused |
| INI_ALL | 7 | Unused |
Assert constants, these values are used to set the assertion options in assert_options().
| Constant | INI Setting | Description |
|---|---|---|
ASSERT_ACTIVE |
assert.active | Enable assert() evaluation. |
ASSERT_CALLBACK |
assert.callback | Callback to call on failed assertions. |
ASSERT_BAIL |
assert.bail | Terminate execution on failed assertions. |
ASSERT_WARNING |
assert.warning | Issues a PHP warning for each failed assertion |
ASSERT_QUITE_EVAL |
assert.quiet_eval | Disable error_reporting during assertion expression evaluation. |
The following constants are only available if the host operating system is Windows, and can tell different versioning information so its possible to detect various features and make use of them. They are all available as of PHP 5.3.0.
| Constant | Description |
|---|---|
PHP_WINDOWS_VERSION_MAJOR |
The major version of Windows, this can be either 4 (NT4/Me/98/95), 5 (XP/2003 R2/2003/2000) or 6 (Vista/2008). |
PHP_WINDOWS_VERSION_MINOR |
The minor version of Windows, this can be either 0 (Vista/2008/2000/NT4/95), 1 (XP), 2 (2003 R2/2003/XP x64), 10 (98) or 90 (ME). |
PHP_WINDOWS_VERSION_BUILD |
The Windows build number (for example, Windows Vista with SP1 applied is build 6001) |
PHP_WINDOWS_VERSION_PLATFORM |
The platform that PHP currently is running on, this value is 2 on Windows Vista/XP/2000/NT4, Server 2008/2003 and on Windows ME/98/95 this value is 1. |
PHP_WINDOWS_VERSION_SP_MAJOR |
The major version of the service pack installed, this value is 0 if no service pack is installed. For example, Windows XP with service pack 3 installed will make this value 3. |
PHP_WINDOWS_VERSION_SP_MINOR |
The minor version of the service pack installed, this value is 0 if no service pack is installed. |
PHP_WINDOWS_VERSION_SUITEMASK |
The suitemask is a bitmask that can tell if various features of Windows is installed, see the table below for possible bitfield values. |
PHP_WINDOWS_VERSION_PRODUCTTYPE |
This contains the value used to determine the PHP_WINDOWS_NT_* constants. This value may be one of the PHP_WINDOWS_NT_* constants indicating the platform type. |
PHP_WINDOWS_NT_DOMAIN_CONTROLLER |
This is a domain controller |
PHP_WINDOWS_NT_SERVER |
This is a server system (eg. Server 2008/2003/2000), note that if this is a
domain controller its reported as PHP_WINDOWS_NT_DOMAIN_CONTROLLER.
|
PHP_WINDOWS_NT_WORKSTATION |
This is a workstation system (eg. Vista/XP/2000/NT4) |
This table shows a list of features that can be checked for using the
PHP_WINDOWS_VERSION_SUITEMASK bitmask.
| Bits | Description |
|---|---|
| 0x00000004 | Microsoft BackOffice components are installed. |
| 0x00000400 | Windows Server 2003, Web Edition is installed. |
| 0x00004000 | Windows Server 2003, Compute Cluster Edition is installed. |
| 0x00000080 | Windows Server 2008 Datacenter, Windows Server 2003, Datacenter Edition or Windows 2000 Datacenter Server is installed. |
| 0x00000002 | Windows Server 2008 Enterprise, Windows Server 2003, Enterprise Edition, Windows 2000 Advanced Server, or Windows NT Server 4.0 Enterprise Edition is installed. |
| 0x00000040 | Windows XP Embedded is installed. |
| 0x00000200 | Windows Vista Home Premium, Windows Vista Home Basic, or Windows XP Home Edition is installed. |
| 0x00000100 | Remote Desktop is supported, but only one interactive session is supported. This value is set unless the system is running in application server mode. |
| 0x00000001 | Microsoft Small Business Server was once installed on the system, but may have been upgraded to another version of Windows. |
| 0x00000020 | Microsoft Small Business Server is installed with the restrictive client license in force. |
| 0x00002000 | Windows Storage Server 2003 R2 or Windows Storage Server 2003 is installed. |
| 0x00000010 | Terminal Services is installed. This value is always set. If this value is set but 0x00000100 is not set, then the system is running in application server mode. |
| 0x00008000 | Windows Home Server is installed. |
PHP Options/Info Funkcje
assert_options
(PHP 4, PHP 5)
assert_options — Set/get the various assert flags
Opis
Set the various assert() control options or just query their current settings.
Parametry
-
what -
Assert Options Option INI Setting Default value Description ASSERT_ACTIVE assert.active 1 enable assert() evaluation ASSERT_WARNING assert.warning 1 issue a PHP warning for each failed assertion ASSERT_BAIL assert.bail 0 terminate execution on failed assertions ASSERT_QUIET_EVAL assert.quiet_eval 0 disable error_reporting during assertion expression evaluation ASSERT_CALLBACK assert.callback ( NULL)Callback to call on failed assertions -
value -
An optional new value for the option.
Zwracane wartości
Returns the original setting of any option or FALSE on errors.
Przykłady
Przykład #1 assert_options() example
<?php
// This is our function to handle
// assert failures
function assert_failure()
{
echo 'Assert failed';
}
// This is our test function
function test_assert($parameter)
{
assert(is_bool($parameter));
}
// Set our assert options
assert_options(ASSERT_ACTIVE, true);
assert_options(ASSERT_BAIL, true);
assert_options(ASSERT_WARNING, false);
assert_options(ASSERT_CALLBACK, 'assert_failure');
// Make an assert that would fail
test_assert(1);
// This is never reached due to ASSERT_BAIL
// being true
echo 'Never reached';
?>
assert
(PHP 4, PHP 5)
assert — Checks if assertion is FALSE
Opis
assert() will check the given
assertion and take appropriate action if
its result is FALSE.
If the assertion is given as a string it
will be evaluated as PHP code by assert().
The advantages of a string assertion are
less overhead when assertion checking is off and messages
containing the assertion expression when
an assertion fails. This means that if you pass a boolean condition
as assertion this condition will not show up as
parameter to the assertion function which you may have defined with the
assert_options() function, the condition is converted
to a string before calling that handler function, and the boolean FALSE
is converted as the empty string.
Assertions should be used as a debugging feature only. You may
use them for sanity-checks that test for conditions that should
always be TRUE and that indicate some programming errors if not
or to check for the presence of certain features like extension
functions or certain system limits and features.
Assertions should not be used for normal runtime operations like input parameter checks. As a rule of thumb your code should always be able to work correctly if assertion checking is not activated.
The behavior of assert() may be configured by assert_options() or by .ini-settings described in that functions manual page.
The assert_options() function and/or ASSERT_CALLBACK configuration directive allow a callback function to be set to handle failed assertions.
assert() callbacks are particularly useful for building automated test suites because they allow you to easily capture the code passed to the assertion, along with information on where the assertion was made. While this information can be captured via other methods, using assertions makes it much faster and easier!
The callback function should accept three arguments. The first argument will contain the file the assertion failed in. The second argument will contain the line the assertion failed on and the third argument will contain the expression that failed (if any - literal values such as 1 or "two" will not be passed via this argument)
Parametry
-
assertion -
The assertion.
Zwracane wartości
FALSE if the assertion is false, TRUE otherwise.
Przykłady
Przykład #1 Handle a failed assertion with a custom handler
<?php
// Active assert and make it quiet
assert_options(ASSERT_ACTIVE, 1);
assert_options(ASSERT_WARNING, 0);
assert_options(ASSERT_QUIET_EVAL, 1);
// Create a handler function
function my_assert_handler($file, $line, $code)
{
echo "<hr>Assertion Failed:
File '$file'<br />
Line '$line'<br />
Code '$code'<br /><hr />";
}
// Set up the callback
assert_options(ASSERT_CALLBACK, 'my_assert_handler');
// Make an assertion that should fail
assert('mysql_query("")');
?>
dl
(PHP 4, PHP 5)
dl — Loads a PHP extension at runtime
Opis
$library
)
Loads the PHP extension given by the parameter
library.
Use extension_loaded() to test whether a given extension is already available or not. This works on both built-in extensions and dynamically loaded ones (either through php.ini or dl()).
This function has been removed from some SAPIs in PHP 5.3.
Parametry
-
library -
This parameter is only the filename of the extension to load which also depends on your platform. For example, the sockets extension (if compiled as a shared module, not the default!) would be called sockets.so on Unix platforms whereas it is called php_sockets.dll on the Windows platform.
The directory where the extension is loaded from depends on your platform:
Windows - If not explicitly set in the php.ini, the extension is loaded from C:\php4\extensions\ (PHP 4) or C:\php5\ (PHP 5) by default.
Unix - If not explicitly set in the php.ini, the default extension directory depends on
- whether PHP has been built with --enable-debug or not
- whether PHP has been built with (experimental) ZTS (Zend Thread Safety) support or not
- the current internal ZEND_MODULE_API_NO (Zend internal module API number, which is basically the date on which a major module API change happened, e.g. 20010901)
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu. If the functionality of loading modules is not available
or has been disabled (either by setting
enable_dl off or by enabling tryb bezpieczny
in php.ini) an E_ERROR is emitted
and execution is stopped. If dl() fails because the
specified library couldn't be loaded, in addition to FALSE an
E_WARNING message is emitted.
Przykłady
Przykład #1 dl() examples
<?php
// Example loading an extension based on OS
if (!extension_loaded('sqlite')) {
if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
dl('php_sqlite.dll');
} else {
dl('sqlite.so');
}
}
// Or, the PHP_SHLIB_SUFFIX constant is available as of PHP 4.3.0
if (!extension_loaded('sqlite')) {
$prefix = (PHP_SHLIB_SUFFIX === 'dll') ? 'php_' : '';
dl($prefix . 'sqlite.' . PHP_SHLIB_SUFFIX);
}
?>
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.0 | dl() is now disabled in some SAPIs due to stability issues. The only SAPIs that allow dl() are CLI and Embed. Use the Extension Loading Directives instead. |
Notatki
Informacja:
dl() is not supported when PHP is built with ZTS support. Use the Extension Loading Directives instead.
Informacja:
dl() is case sensitive on Unix platforms.
Informacja: Ta funkcja jest niedostępna jeśli PHP działa w trybie bezpiecznym
Zobacz też:
- Extension Loading Directives
- extension_loaded() - Find out whether an extension is loaded
extension_loaded
(PHP 4, PHP 5)
extension_loaded — Find out whether an extension is loaded
Opis
$name
)Finds out whether the extension is loaded.
Parametry
-
name -
The extension name.
You can see the names of various extensions by using phpinfo() or if you're using the CGI or CLI version of PHP you can use the -m switch to list all available extensions:
$ php -m [PHP Modules] xml tokenizer standard sockets session posix pcre overload mysql mbstring ctype [Zend Modules]
Zwracane wartości
Returns TRUE if the extension identified by name
is loaded, FALSE otherwise.
Przykłady
Przykład #1 extension_loaded() example
<?php
if (!extension_loaded('gd')) {
if (!dl('gd.so')) {
exit;
}
}
?>
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.0.0 | extension_loaded() uses the internal extension name to test whether a certain extension is available or not. Most internal extension names are written in lower case but there may be extensions available which also use uppercase letters. Prior to PHP 5, this function compared the names case sensitively. |
Zobacz też:
- get_loaded_extensions() - Returns an array with the names of all modules compiled and loaded
- get_extension_funcs() - Returns an array with the names of the functions of a module
- phpinfo() - Outputs information about PHP's configuration
- dl() - Loads a PHP extension at runtime
- function_exists() - Return TRUE if the given function has been defined
gc_collect_cycles
(PHP 5 >= 5.3.0)
gc_collect_cycles — Forces collection of any existing garbage cycles
Opis
Forces collection of any existing garbage cycles.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns number of collected cycles.
gc_disable
(PHP 5 >= 5.3.0)
gc_disable — Deactivates the circular reference collector
Opis
Deactivates the circular reference collector, setting zend.enable_gc to 0.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Nie jest zwracana żadna wartość.
gc_enable
(PHP 5 >= 5.3.0)
gc_enable — Activates the circular reference collector
Opis
Activates the circular reference collector, setting zend.enable_gc to 1.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Nie jest zwracana żadna wartość.
gc_enabled
(PHP 5 >= 5.3.0)
gc_enabled — Returns status of the circular reference collector
Opis
Returns status of the circular reference collector.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns TRUE if the garbage collector is enabled, FALSE otherwise.
Przykłady
Przykład #1 A gc_enabled() example
<?php
if(gc_enabled()) gc_collect_cycles();
?>
get_cfg_var
(PHP 4, PHP 5)
get_cfg_var — Gets the value of a PHP configuration option
Opis
$option
)
Gets the value of a PHP configuration option.
This function will not return configuration information set when the PHP was compiled, or read from an Apache configuration file.
To check whether the system is using a configuration file, try retrieving the value of the cfg_file_path configuration setting. If this is available, a configuration file is being used.
Parametry
-
option -
The configuration option name.
Zwracane wartości
Returns the current value of the PHP configuration variable specified by
option, or FALSE if an error occurs.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.0 | get_cfg_var() was fixed to be able to return "array" ini options. |
Zobacz też:
- ini_get() - Gets the value of a configuration option
- ini_get_all() - Gets all configuration options
get_current_user
(PHP 4, PHP 5)
get_current_user — Gets the name of the owner of the current PHP script
Opis
Returns the name of the owner of the current PHP script.
Zwracane wartości
Returns the username as a string.
Przykłady
Przykład #1 get_current_user() example
<?php
echo 'Current script owner: ' . get_current_user();
?>
Powyższy przykład wyświetli coś podobnego do:
Current script owner: SYSTEM
Zobacz też:
- getmyuid() - Gets PHP script owner's UID
- getmygid() - Get PHP script owner's GID
- getmypid() - Gets PHP's process ID
- getmyinode() - Gets the inode of the current script
- getlastmod() - Gets time of last page modification
get_defined_constants
(PHP 4 >= 4.1.0, PHP 5)
get_defined_constants — Returns an associative array with the names of all the constants and their values
Opis
$categorize = false
] )Returns the names and values of all the constants currently defined. This includes those created by extensions as well as those created with the define() function.
Parametry
-
categorize -
Causing this function to return a multi-dimensional array with categories in the keys of the first dimension and constants and their values in the second dimension.
<?php
define("MY_CONSTANT", 1);
print_r(get_defined_constants(true));
?>Powyższy przykład wyświetli coś podobnego do:
Array ( [Core] => Array ( [E_ERROR] => 1 [E_WARNING] => 2 [E_PARSE] => 4 [E_NOTICE] => 8 [E_CORE_ERROR] => 16 [E_CORE_WARNING] => 32 [E_COMPILE_ERROR] => 64 [E_COMPILE_WARNING] => 128 [E_USER_ERROR] => 256 [E_USER_WARNING] => 512 [E_USER_NOTICE] => 1024 [E_ALL] => 2047 [TRUE] => 1 ) [pcre] => Array ( [PREG_PATTERN_ORDER] => 1 [PREG_SET_ORDER] => 2 [PREG_OFFSET_CAPTURE] => 256 [PREG_SPLIT_NO_EMPTY] => 1 [PREG_SPLIT_DELIM_CAPTURE] => 2 [PREG_SPLIT_OFFSET_CAPTURE] => 4 [PREG_GREP_INVERT] => 1 ) [user] => Array ( [MY_CONSTANT] => 1 ) )
Zwracane wartości
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.1 | Windows only: Core constants are categorized under Core, previously mhash. |
| 5.3.0 | Core constants are categorized under Core, previously internal. On Windows, the Core Constants are categorized under mhash. |
| 5.2.11 |
The categorize parameter now operates appropriately.
Previously, the categorize parameter was interpreted
as !is_null($categorize), making any value other than NULL
force the constants to be categorized.
|
| 5.0.0 |
The categorize parameter was added.
|
Przykłady
Przykład #1 get_defined_constants() Example
<?php
print_r(get_defined_constants());
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[E_ERROR] => 1
[E_WARNING] => 2
[E_PARSE] => 4
[E_NOTICE] => 8
[E_CORE_ERROR] => 16
[E_CORE_WARNING] => 32
[E_COMPILE_ERROR] => 64
[E_COMPILE_WARNING] => 128
[E_USER_ERROR] => 256
[E_USER_WARNING] => 512
[E_USER_NOTICE] => 1024
[E_ALL] => 2047
[TRUE] => 1
)
Zobacz też:
- defined() - Checks whether a given named constant exists
- get_loaded_extensions() - Returns an array with the names of all modules compiled and loaded
- get_defined_functions() - Returns an array of all defined functions
- get_defined_vars() - Returns an array of all defined variables
get_extension_funcs
(PHP 4, PHP 5)
get_extension_funcs — Returns an array with the names of the functions of a module
Opis
$module_name
)
This function returns the names of all the functions defined in
the module indicated by module_name.
Parametry
-
module_name -
The module name.
Informacja:
This parameter must be in lowercase.
Zwracane wartości
Returns an array with all the functions, or FALSE if
module_name is not a valid extension.
Przykłady
Przykład #1 Prints the XML functions
<?php
print_r(get_extension_funcs("xml"));
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[0] => xml_parser_create
[1] => xml_parser_create_ns
[2] => xml_set_object
[3] => xml_set_element_handler
[4] => xml_set_character_data_handler
[5] => xml_set_processing_instruction_handler
[6] => xml_set_default_handler
[7] => xml_set_unparsed_entity_decl_handler
[8] => xml_set_notation_decl_handler
[9] => xml_set_external_entity_ref_handler
[10] => xml_set_start_namespace_decl_handler
[11] => xml_set_end_namespace_decl_handler
[12] => xml_parse
[13] => xml_parse_into_struct
[14] => xml_get_error_code
[15] => xml_error_string
[16] => xml_get_current_line_number
[17] => xml_get_current_column_number
[18] => xml_get_current_byte_index
[19] => xml_parser_free
[20] => xml_parser_set_option
[21] => xml_parser_get_option
[22] => utf8_encode
[23] => utf8_decode
)
Zobacz też:
- get_loaded_extensions() - Returns an array with the names of all modules compiled and loaded
- ReflectionExtension::getFunctions() - Gets extension functions
get_include_path
(PHP 4 >= 4.3.0, PHP 5)
get_include_path — Gets the current include_path configuration option
Zwracane wartości
Returns the path, as a string.
Przykłady
Przykład #1 get_include_path() example
<?php
// Works as of PHP 4.3.0
echo get_include_path();
// Works in all PHP versions
echo ini_get('include_path');
?>
Zobacz też:
- ini_get() - Gets the value of a configuration option
- restore_include_path() - Restores the value of the include_path configuration option
- set_include_path() - Sets the include_path configuration option
- include()
get_included_files
(PHP 4, PHP 5)
get_included_files — Returns an array with the names of included or required files
Opis
Gets the names of all files that have been included using include(), include_once(), require() or require_once().
Zwracane wartości
Returns an array of the names of all files.
The script originally called is considered an "included file," so it will be listed together with the files referenced by include() and family.
Files that are included or required multiple times only show up once in the returned array.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.0.1 | In PHP 4.0.1 and previous versions this function assumed that the required files ended in the extension .php; other extensions would not be returned. The array returned by get_included_files() was an associative array and only listed files included by include() and include_once(). |
Przykłady
Przykład #1 get_included_files() example
<?php
// This file is abc.php
include 'test1.php';
include_once 'test2.php';
require 'test3.php';
require_once 'test4.php';
$included_files = get_included_files();
foreach ($included_files as $filename) {
echo "$filename\n";
}
?>
Powyższy przykład wyświetli:
abc.php test1.php test2.php test3.php test4.php
Notatki
Informacja:
Files included using the auto_prepend_file configuration directive are not included in the returned array.
Zobacz też:
- include()
- include_once()
- require()
- require_once()
- get_required_files() - Alias dla get_included_files
get_loaded_extensions
(PHP 4, PHP 5)
get_loaded_extensions — Returns an array with the names of all modules compiled and loaded
Opis
$zend_extensions = false
] )This function returns the names of all the modules compiled and loaded in the PHP interpreter.
Parametry
-
zend_extensions -
Only return Zend extensions, if not then regular extensions, like mysqli are listed. Defaults to
FALSE(return regular extensions).
Zwracane wartości
Returns an indexed array of all the modules names.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.2.4 |
The optional zend_extensions parameter was added
|
Przykłady
Przykład #1 get_loaded_extensions() Example
<?php
print_r(get_loaded_extensions());
?>
Powyższy przykład wyświetli coś podobnego do:
Array ( [0] => xml [1] => wddx [2] => standard [3] => session [4] => posix [5] => pgsql [6] => pcre [7] => gd [8] => ftp [9] => db [10] => calendar [11] => bcmath )
Zobacz też:
- get_extension_funcs() - Returns an array with the names of the functions of a module
- extension_loaded() - Find out whether an extension is loaded
- dl() - Loads a PHP extension at runtime
- phpinfo() - Outputs information about PHP's configuration
get_magic_quotes_gpc
(PHP 4, PHP 5)
get_magic_quotes_gpc — Gets the current configuration setting of magic_quotes_gpc
Opis
Returns the current configuration setting of magic_quotes_gpc
Keep in mind that attempting to set magic_quotes_gpc at runtime will not work.
For more information about magic_quotes, see this security section.
Zwracane wartości
Returns 0 if magic_quotes_gpc is off, 1 otherwise.
Przykłady
Przykład #1 get_magic_quotes_gpc() example
<?php
echo get_magic_quotes_gpc(); // 1
echo $_POST['lastname']; // O\'reilly
echo addslashes($_POST['lastname']); // O\\\'reilly
if (get_magic_quotes_gpc()) {
$lastname = stripslashes($_POST['lastname']);
}
else {
$lastname = $_POST['lastname'];
}
// If using MySQL
$lastname = mysql_real_escape_string($lastname);
echo $lastname; // O\'reilly
$sql = "INSERT INTO lastnames (lastname) VALUES ('$lastname')";
?>
Notatki
Informacja:
If the directive magic_quotes_sybase is ON it will completely override magic_quotes_gpc. So even when get_magic_quotes_gpc() returns
TRUEneither double quotes, backslashes or NUL's will be escaped. Only single quotes will be escaped. In this case they'll look like: ''
Zobacz też:
- addslashes() - Quote string with slashes
- stripslashes() - Un-quotes a quoted string
- get_magic_quotes_runtime() - Gets the current active configuration setting of magic_quotes_runtime
- ini_get() - Gets the value of a configuration option
get_magic_quotes_runtime
(PHP 4, PHP 5)
get_magic_quotes_runtime — Gets the current active configuration setting of magic_quotes_runtime
Opis
Returns the current active configuration setting of magic_quotes_runtime.
Zwracane wartości
Returns 0 if magic_quotes_runtime is off, 1 otherwise.
Przykłady
Przykład #1 get_magic_quotes_runtime() example
<?php
// Check if magic_quotes_runtime is active
if(get_magic_quotes_runtime())
{
// Deactivate
set_magic_quotes_runtime(false);
}
?>
Zobacz też:
- get_magic_quotes_gpc() - Gets the current configuration setting of magic_quotes_gpc
- set_magic_quotes_runtime() - Sets the current active configuration setting of magic_quotes_runtime
Opis
Ta funkcja jest aliasem dla: get_included_files().
getenv
(PHP 4, PHP 5)
getenv — Gets the value of an environment variable
Opis
$varname
)Gets the value of an environment variable.
You can see a list of all the environmental variables by using phpinfo(). Many of these variables are listed within » RFC 3875, specifically section 4.1, "Request Meta-Variables".
Parametry
-
varname -
The variable name.
Zwracane wartości
Returns the value of the environment variable
varname, or FALSE if the environment
variable varname does not exist.
Przykłady
Przykład #1 getenv() Example
<?php
// Example use of getenv()
$ip = getenv('REMOTE_ADDR');
// Or simply use a Superglobal ($_SERVER or $_ENV)
$ip = $_SERVER['REMOTE_ADDR'];
?>
Zobacz też:
- putenv() - Sets the value of an environment variable
- apache_getenv() - Get an Apache subprocess_env variable
- Superglobals
getlastmod
(PHP 4, PHP 5)
getlastmod — Gets time of last page modification
Opis
Gets the time of the last modification of the current page.
If you're interested in getting the last modification time of a different file, consider using filemtime().
Zwracane wartości
Returns the time of the last modification of the current
page. The value returned is a Unix timestamp, suitable for
feeding to date(). Returns FALSE on error.
Przykłady
Przykład #1 getlastmod() example
<?php
// outputs e.g. 'Last modified: March 04 1998 20:43:59.'
echo "Last modified: " . date ("F d Y H:i:s.", getlastmod());
?>
Zobacz też:
- date() - Formatuje lokalny czas/datę
- getmyuid() - Gets PHP script owner's UID
- getmygid() - Get PHP script owner's GID
- get_current_user() - Gets the name of the owner of the current PHP script
- getmyinode() - Gets the inode of the current script
- getmypid() - Gets PHP's process ID
- filemtime() - Pobiera czas ostatniej modyfikacji pliku
getmygid
(PHP 4 >= 4.1.0, PHP 5)
getmygid — Get PHP script owner's GID
Opis
Gets the group ID of the current script.
Zwracane wartości
Returns the group ID of the current script, or FALSE on error.
Zobacz też:
- getmyuid() - Gets PHP script owner's UID
- getmypid() - Gets PHP's process ID
- get_current_user() - Gets the name of the owner of the current PHP script
- getmyinode() - Gets the inode of the current script
- getlastmod() - Gets time of last page modification
getmyinode
(PHP 4, PHP 5)
getmyinode — Gets the inode of the current script
Opis
Gets the inode of the current script.
Zwracane wartości
Returns the current script's inode as an integer, or FALSE on error.
Zobacz też:
- getmygid() - Get PHP script owner's GID
- getmyuid() - Gets PHP script owner's UID
- getmypid() - Gets PHP's process ID
- get_current_user() - Gets the name of the owner of the current PHP script
- getlastmod() - Gets time of last page modification
getmypid
(PHP 4, PHP 5)
getmypid — Gets PHP's process ID
Opis
Gets the current PHP process ID.
Zwracane wartości
Returns the current PHP process ID, or FALSE on error.
Notatki
Process IDs are not unique, thus they are a weak entropy source. We recommend against relying on pids in security-dependent contexts.
Zobacz też:
- getmygid() - Get PHP script owner's GID
- getmyuid() - Gets PHP script owner's UID
- get_current_user() - Gets the name of the owner of the current PHP script
- getmyinode() - Gets the inode of the current script
- getlastmod() - Gets time of last page modification
getmyuid
(PHP 4, PHP 5)
getmyuid — Gets PHP script owner's UID
Opis
Gets the user ID of the current script.
Zwracane wartości
Returns the user ID of the current script, or FALSE on error.
Zobacz też:
- getmygid() - Get PHP script owner's GID
- getmypid() - Gets PHP's process ID
- get_current_user() - Gets the name of the owner of the current PHP script
- getmyinode() - Gets the inode of the current script
- getlastmod() - Gets time of last page modification
getopt
(PHP 4 >= 4.3.0, PHP 5)
getopt — Gets options from the command line argument list
Opis
$options
[, array $longopts
] )Parses options passed to the script.
Parametry
-
options - Each character in this string will be used as option characters and matched against options passed to the script starting with a single hyphen (-). For example, an option string "x" recognizes an option -x. Only a-z, A-Z and 0-9 are allowed.
-
longopts - An array of options. Each element in this array will be used as option strings and matched against options passed to the script starting with two hyphens (--). For example, an longopts element "opt" recognizes an option --opt.
The options parameter may contain the following
elements:
- Individual characters (do not accept values)
- Characters followed by a colon (parameter requires value)
- Characters followed by two colons (optional value)
Informacja: Optional values do not accept " " (space) as a separator.
Informacja:
The format for the
optionsandlongoptsis almost the same, the only difference is thatlongoptstakes an array of options (where each element is the option) whereasoptionstakes a string (where each character is the option).
Zwracane wartości
This function will return an array of option / argument pairs or FALSE on
failure.
Informacja:
The parsing of options will end at the first non-option found, anything that follows is discarded.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.0 | Added support for "=" as argument/value separator. |
| 5.3.0 | Added support for optional values (specified with "::"). |
| 5.3.0 |
Parameter longopts is available on all systems.
|
| 5.3.0 | This function is no longer system dependent, and now works on Windows, too. |
Przykłady
Przykład #1 getopt() example
<?php
$options = getopt("f:hp:");
var_dump($options);
?>
Running the above script with php script.php -fvalue -h will output:
array(2) {
["f"]=>
string(5) "value"
["h"]=>
bool(false)
}
Przykład #2 getopt() example#2
<?php
$shortopts = "";
$shortopts .= "f:"; // Required value
$shortopts .= "v::"; // Optional value
$shortopts .= "abc"; // These options do not accept values
$longopts = array(
"required:", // Required value
"optional::", // Optional value
"option", // No value
"opt", // No value
);
$options = getopt($shortopts, $longopts);
var_dump($options);
?>
Running the above script with php script.php -f "value for f" -v -a --required value --optional="optional value" --option will output:
array(6) {
["f"]=>
string(11) "value for f"
["v"]=>
bool(false)
["a"]=>
bool(false)
["required"]=>
string(5) "value"
["optional"]=>
string(14) "optional value"
["option"]=>
bool(false)
}
Przykład #3 getopt() example#3
Passing multiple options as one
<?php
$options = getopt("abc");
var_dump($options);
?>
Running the above script with php script.php -aaac will output:
array(2) {
["a"]=>
array(3) {
[0]=>
bool(false)
[1]=>
bool(false)
[2]=>
bool(false)
}
["c"]=>
bool(false)
}
getrusage
(PHP 4, PHP 5)
getrusage — Gets the current resource usages
Opis
$who = 0
] )This is an interface to getrusage(2). It gets data returned from the system call.
Parametry
-
who -
If
whois 1, getrusage will be called withRUSAGE_CHILDREN.
Zwracane wartości
Returns an associative array containing the data returned from the system call. All entries are accessible by using their documented field names.
Przykłady
Przykład #1 getrusage() example
<?php
$dat = getrusage();
echo $dat["ru_nswap"]; // number of swaps
echo $dat["ru_majflt"]; // number of page faults
echo $dat["ru_utime.tv_sec"]; // user time used (seconds)
echo $dat["ru_utime.tv_usec"]; // user time used (microseconds)
?>
Notatki
Informacja: Ta funkcja nie jest dostępna na platformie Windows.
Zobacz też:
- Your system's man page on getrusage(2)
Opis
Ta funkcja jest aliasem dla: ini_set().
ini_get_all
(PHP 4 >= 4.2.0, PHP 5)
ini_get_all — Gets all configuration options
Opis
$extension
[, bool $details = true
]] )Returns all the registered configuration options.
Parametry
-
extension -
An optional extension name. If set, the function return only options specific for that extension.
-
details -
Retrieve details settings or only the current value for each setting. Default is
TRUE(retrieve details).
Zwracane wartości
Returns an associative array with directive name as the array key.
When details is TRUE (default) the array will
contain global_value (set in
php.ini), local_value (perhaps set with
ini_set() or .htaccess), and
access (the access level).
When details is FALSE the value will be the
current value of the option.
See the manual section for information on what access levels mean.
Informacja:
It's possible for a directive to have multiple access levels, which is why access shows the appropriate bitmask values.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.0 |
Added details.
|
Przykłady
Przykład #1 ini_get_all() examples
<?php
print_r(ini_get_all("pcre"));
print_r(ini_get_all());
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[pcre.backtrack_limit] => Array
(
[global_value] => 100000
[local_value] => 100000
[access] => 7
)
[pcre.recursion_limit] => Array
(
[global_value] => 100000
[local_value] => 100000
[access] => 7
)
)
Array
(
[allow_call_time_pass_reference] => Array
(
[global_value] => 0
[local_value] => 0
[access] => 6
)
[allow_url_fopen] => Array
(
[global_value] => 1
[local_value] => 1
[access] => 4
)
...
)
Przykład #2 Disabling details
<?php
print_r(ini_get_all("pcre", false)); // Added in PHP 5.3.0
print_r(ini_get_all(null, false)); // Added in PHP 5.3.0
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[pcre.backtrack_limit] => 100000
[pcre.recursion_limit] => 100000
)
Array
(
[allow_call_time_pass_reference] => 0
[allow_url_fopen] => 1
...
)
Zobacz też:
- How to change configuration settings
- ini_get() - Gets the value of a configuration option
- ini_restore() - Restores the value of a configuration option
- ini_set() - Sets the value of a configuration option
- get_loaded_extensions() - Returns an array with the names of all modules compiled and loaded
- phpinfo() - Outputs information about PHP's configuration
ini_get
(PHP 4, PHP 5)
ini_get — Gets the value of a configuration option
Opis
$varname
)Returns the value of the configuration option on success.
Parametry
-
varname -
The configuration option name.
Zwracane wartości
Returns the value of the configuration option as a string on success, or an
empty string for null values. Returns FALSE if the
configuration option doesn't exist.
Przykłady
Przykład #1 A few ini_get() examples
<?php
/*
Our php.ini contains the following settings:
display_errors = On
register_globals = Off
post_max_size = 8M
*/
echo 'display_errors = ' . ini_get('display_errors') . "\n";
echo 'register_globals = ' . ini_get('register_globals') . "\n";
echo 'post_max_size = ' . ini_get('post_max_size') . "\n";
echo 'post_max_size+1 = ' . (ini_get('post_max_size')+1) . "\n";
echo 'post_max_size in bytes = ' . return_bytes(ini_get('post_max_size'));
function return_bytes($val) {
$val = trim($val);
$last = strtolower($val[strlen($val)-1]);
switch($last) {
// The 'G' modifier is available since PHP 5.1.0
case 'g':
$val *= 1024;
case 'm':
$val *= 1024;
case 'k':
$val *= 1024;
}
return $val;
}
?>
Powyższy przykład wyświetli coś podobnego do:
display_errors = 1 register_globals = 0 post_max_size = 8M post_max_size+1 = 9 post_max_size in bytes = 8388608
Notatki
Informacja: When querying boolean values
A boolean ini value of off will be returned as an empty string or "0" while a boolean ini value of on will be returned as "1". The function can also return the literal string of INI value.
Informacja: When querying memory size values
Many ini memory size values, such as upload_max_filesize, are stored in the php.ini file in shorthand notation. ini_get() will return the exact string stored in the php.ini file and NOT its integer equivalent. Attempting normal arithmetic functions on these values will not have otherwise expected results. The example above shows one way to convert shorthand notation into bytes, much like how the PHP source does it.
Zobacz też:
- get_cfg_var() - Gets the value of a PHP configuration option
- ini_get_all() - Gets all configuration options
- ini_restore() - Restores the value of a configuration option
- ini_set() - Sets the value of a configuration option
ini_restore
(PHP 4, PHP 5)
ini_restore — Restores the value of a configuration option
Opis
$varname
)Restores a given configuration option to its original value.
Parametry
-
varname -
The configuration option name.
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 ini_restore() example
<?php
$setting = 'y2k_compliance';
echo 'Current value for \'' . $setting . '\': ' . ini_get($setting), PHP_EOL;
ini_set($setting, ini_get($setting) ? 0 : 1);
echo 'New value for \'' . $setting . '\': ' . ini_get($setting), PHP_EOL;
ini_restore($setting);
echo 'Original value for \'' . $setting . '\': ' . ini_get($setting), PHP_EOL;
?>
Powyższy przykład wyświetli:
Current value for 'y2k_compliance': 1 New value for 'y2k_compliance': 0 Original value for 'y2k_compliance': 1
Zobacz też:
- ini_get() - Gets the value of a configuration option
- ini_get_all() - Gets all configuration options
- ini_set() - Sets the value of a configuration option
ini_set
(PHP 4, PHP 5)
ini_set — Sets the value of a configuration option
Opis
$varname
, string $newvalue
)Sets the value of the given configuration option. The configuration option will keep this new value during the script's execution, and will be restored at the script's ending.
Parametry
-
varname -
Not all the available options can be changed using ini_set(). There is a list of all available options in the appendix.
-
newvalue -
The new value for the option.
Zwracane wartości
Returns the old value on success, FALSE on failure.
Przykłady
Przykład #1 Setting an ini option
<?php
echo ini_get('display_errors');
if (!ini_get('display_errors')) {
ini_set('display_errors', 1);
}
echo ini_get('display_errors');
?>
Zobacz też:
- get_cfg_var() - Gets the value of a PHP configuration option
- ini_get() - Gets the value of a configuration option
- ini_get_all() - Gets all configuration options
- ini_restore() - Restores the value of a configuration option
- How to change configuration settings
Opis
Ta funkcja jest aliasem dla: set_magic_quotes_runtime()
main
main — Dummy for main()
Opis
There is no function named main() except in the PHP source. In PHP 4.3.0, a new type of error handling in the PHP source (php_error_docref) was introduced. One feature is to provide links to a manual page in PHP error messages when the PHP directives html_errors (on by default) and docref_root (on by default until PHP 4.3.2) are set.
Sometimes error messages refer to a manual page for the function main() which is why this page exists. If you discover such a reference, please » file a bug report, indicating the PHP function caused the error that linked to main() and it will be fixed and properly documented.
| Function name | No longer points here as of |
|---|---|
| include() | 5.1.0 |
| include_once() | 5.1.0 |
| require() | 5.1.0 |
| require_once() | 5.1.0 |
memory_get_peak_usage
(PHP 5 >= 5.2.0)
memory_get_peak_usage — Returns the peak of memory allocated by PHP
Opis
$real_usage = false
] )Returns the peak of memory, in bytes, that's been allocated to your PHP script.
Parametry
-
real_usage -
Set this to
TRUEto get the real size of memory allocated from system. If not set orFALSEonly the memory used by emalloc() is reported.
Zwracane wartości
Returns the memory peak in bytes.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.2.1 | Compiling with --enable-memory-limit is no longer required for this function to exist. |
| 5.2.0 |
real_usage was added.
|
memory_get_usage
(PHP 4 >= 4.3.2, PHP 5)
memory_get_usage — Returns the amount of memory allocated to PHP
Opis
$real_usage = false
] )Returns the amount of memory, in bytes, that's currently being allocated to your PHP script.
Parametry
-
real_usage -
Set this to
TRUEto get the real size of memory allocated from system. If not set orFALSEonly the memory used by emalloc() is reported.
Zwracane wartości
Returns the memory amount in bytes.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.2.1 | Compiling with --enable-memory-limit is no longer required for this function to exist. |
| 5.2.0 |
real_usage was added.
|
Przykłady
Przykład #1 A memory_get_usage() example
<?php
// This is only an example, the numbers below will
// differ depending on your system
echo memory_get_usage() . "\n"; // 36640
$a = str_repeat("Hello", 4242);
echo memory_get_usage() . "\n"; // 57960
unset($a);
echo memory_get_usage() . "\n"; // 36744
?>
php_ini_loaded_file
(PHP 5 >= 5.2.4)
php_ini_loaded_file — Retrieve a path to the loaded php.ini file
Opis
Check if a php.ini file is loaded, and retrieve its path.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
The loaded php.ini path, or FALSE if one is not loaded.
Przykłady
Przykład #1 php_ini_loaded_file() example
<?php
$inipath = php_ini_loaded_file();
if ($inipath) {
echo 'Loaded php.ini: ' . $inipath;
} else {
echo 'A php.ini file is not loaded';
}
?>
Powyższy przykład wyświetli coś podobnego do:
Loaded php.ini: /usr/local/php/php.ini
Zobacz też:
- php_ini_scanned_files() - Return a list of .ini files parsed from the additional ini dir
- phpinfo() - Outputs information about PHP's configuration
- The configuration file
php_ini_scanned_files
(PHP 4 >= 4.3.0, PHP 5)
php_ini_scanned_files — Return a list of .ini files parsed from the additional ini dir
Opis
php_ini_scanned_files() returns a comma-separated list of configuration files parsed after php.ini. These files are found in a directory defined by the --with-config-file-scan-dir option which is set during compilation.
The returned configuration files also include the path as declared in the --with-config-file-scan-dir option.
Zwracane wartości
Returns a comma-separated string of .ini files on success. Each comma is
followed by a newline. If the directive --with-config-file-scan-dir
wasn't set,
FALSE is returned. If it was set and the directory was empty, an
empty string is returned. If a file is unrecognizable, the file will
still make it into the returned string but a PHP error will also result.
This PHP error will be seen both at compile time and while using
php_ini_scanned_files().
Przykłady
Przykład #1 A simple example to list the returned ini files
<?php
if ($filelist = php_ini_scanned_files()) {
if (strlen($filelist) > 0) {
$files = explode(',', $filelist);
foreach ($files as $file) {
echo "<li>" . trim($file) . "</li>\n";
}
}
}
?>
Zobacz też:
- ini_set() - Sets the value of a configuration option
- phpinfo() - Outputs information about PHP's configuration
- php_ini_loaded_file() - Retrieve a path to the loaded php.ini file
php_logo_guid
(PHP 4, PHP 5)
php_logo_guid — Gets the logo guid
Opis
This function returns the ID which can be used to display the PHP logo using the built-in image. Logo is displayed only if expose_php is On.
Zwracane wartości
Returns PHPE9568F34-D428-11d2-A769-00AA001ACF42.
Przykłady
Przykład #1 php_logo_guid() example
<?php
echo '<img src="' . $_SERVER['PHP_SELF'] .
'?=' . php_logo_guid() . '" alt="PHP Logo !" />';
?>
Zobacz też:
- phpinfo() - Outputs information about PHP's configuration
- phpversion() - Gets the current PHP version
- phpcredits() - Prints out the credits for PHP
- zend_logo_guid() - Gets the Zend guid
php_sapi_name
(PHP 4 >= 4.0.1, PHP 5)
php_sapi_name — Returns the type of interface between web server and PHP
Opis
Returns a lowercase string that describes the type of interface (the Server API, SAPI) that PHP is using. For example, in CLI PHP this string will be "cli" whereas with Apache it may have several different values depending on the exact SAPI used. Possible values are listed below.
Zwracane wartości
Returns the interface type, as a lowercase string.
Although not exhaustive, the possible return values include aolserver, apache, apache2filter, apache2handler, caudium, cgi (until PHP 5.3), cgi-fcgi, cli, continuity, embed, isapi, litespeed, milter, nsapi, phttpd, pi3web, roxen, thttpd, tux, and webjames.
Przykłady
Przykład #1 php_sapi_name() example
This example checks for the substring cgi because it may also be cgi-fcgi.
<?php
$sapi_type = php_sapi_name();
if (substr($sapi_type, 0, 3) == 'cgi') {
echo "You are using CGI PHP\n";
} else {
echo "You are not using CGI PHP\n";
}
?>
Notatki
Informacja: An alternative approach
The PHP constant
PHP_SAPIhas the same value as php_sapi_name().
A potential gotcha
The defined SAPI may not be obvious, because for example instead of apache it may be defined as apache2handler or apache2filter.
php_uname
(PHP 4 >= 4.0.2, PHP 5)
php_uname — Returns information about the operating system PHP is running on
Opis
$mode = "a"
] )
php_uname() returns a description of the operating
system PHP is running on. This is the same string you see at the very
top of the phpinfo() output. For the name of just
the operating system, consider using the PHP_OS
constant, but keep in mind this constant will contain the operating
system PHP was built on.
On some older UNIX platforms, it may not be able to determine the current OS information in which case it will revert to displaying the OS PHP was built on. This will only happen if your uname() library call either doesn't exist or doesn't work.
Parametry
-
mode -
modeis a single character that defines what information is returned:- 'a': This is the default. Contains all modes in the sequence "s n r v m".
- 's': Operating system name. eg. FreeBSD.
- 'n': Host name. eg. localhost.example.com.
- 'r': Release name. eg. 5.1.2-RELEASE.
- 'v': Version information. Varies a lot between operating systems.
- 'm': Machine type. eg. i386.
Zwracane wartości
Returns the description, as a string.
Przykłady
Przykład #1 Some php_uname() examples
<?php
echo php_uname();
echo PHP_OS;
/* Some possible outputs:
Linux localhost 2.4.21-0.13mdk #1 Fri Mar 14 15:08:06 EST 2003 i686
Linux
FreeBSD localhost 3.2-RELEASE #15: Mon Dec 17 08:46:02 GMT 2001
FreeBSD
Windows NT XN1 5.1 build 2600
WINNT
*/
if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
echo 'This is a server using Windows!';
} else {
echo 'This is a server not using Windows!';
}
?>
There are also some related Predefined PHP constants that may come in handy, for example:
Przykład #2 A few OS related constant examples
<?php
// *nix
echo DIRECTORY_SEPARATOR; // /
echo PHP_SHLIB_SUFFIX; // so
echo PATH_SEPARATOR; // :
// Win*
echo DIRECTORY_SEPARATOR; // \
echo PHP_SHLIB_SUFFIX; // dll
echo PATH_SEPARATOR; // ;
?>
Zobacz też:
- phpversion() - Gets the current PHP version
- php_sapi_name() - Returns the type of interface between web server and PHP
- phpinfo() - Outputs information about PHP's configuration
phpcredits
(PHP 4, PHP 5)
phpcredits — Prints out the credits for PHP
Opis
$flag = CREDITS_ALL
] )This function prints out the credits listing the PHP developers, modules, etc. It generates the appropriate HTML codes to insert the information in a page.
Parametry
-
flag -
To generate a custom credits page, you may want to use the
flagparameter.Pre-defined phpcredits() flags name description CREDITS_ALL All the credits, equivalent to using: CREDITS_DOCS+CREDITS_GENERAL+CREDITS_GROUP+CREDITS_MODULES+CREDITS_FULLPAGE. It generates a complete stand-alone HTML page with the appropriate tags.CREDITS_DOCS The credits for the documentation team CREDITS_FULLPAGE Usually used in combination with the other flags. Indicates that a complete stand-alone HTML page needs to be printed including the information indicated by the other flags. CREDITS_GENERAL General credits: Language design and concept, PHP authors and SAPI module. CREDITS_GROUP A list of the core developers CREDITS_MODULES A list of the extension modules for PHP, and their authors CREDITS_SAPI A list of the server API modules for PHP, and their authors
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Prints the general credits
<?php
phpcredits(CREDITS_GENERAL);
?>
Przykład #2 Prints the core developers and the documentation group
<?php
phpcredits(CREDITS_GROUP | CREDITS_DOCS | CREDITS_FULLPAGE);
?>
Przykład #3 Printing all the credits
<html>
<head>
<title>My credits page</title>
</head>
<body>
<?php
// some code of your own
phpcredits(CREDITS_ALL - CREDITS_FULLPAGE);
// some more code
?>
</body>
</html>
Zobacz też:
- phpversion() - Gets the current PHP version
- php_logo_guid() - Gets the logo guid
- phpinfo() - Outputs information about PHP's configuration
phpinfo
(PHP 4, PHP 5)
phpinfo — Outputs information about PHP's configuration
Opis
$what = INFO_ALL
] )Outputs a large amount of information about the current state of PHP. This includes information about PHP compilation options and extensions, the PHP version, server information and environment (if compiled as a module), the PHP environment, OS version information, paths, master and local values of configuration options, HTTP headers, and the PHP License.
Because every system is setup differently, phpinfo() is commonly used to check configuration settings and for available predefined variables on a given system.
phpinfo() is also a valuable debugging tool as it contains all EGPCS (Environment, GET, POST, Cookie, Server) data.
Parametry
-
what -
The output may be customized by passing one or more of the following constants bitwise values summed together in the optional
whatparameter. One can also combine the respective constants or bitwise values together with the or operator.phpinfo() options Name (constant) Value Description INFO_GENERAL 1 The configuration line, php.ini location, build date, Web Server, System and more. INFO_CREDITS 2 PHP Credits. See also phpcredits(). INFO_CONFIGURATION 4 Current Local and Master values for PHP directives. See also ini_get(). INFO_MODULES 8 Loaded modules and their respective settings. See also get_loaded_extensions(). INFO_ENVIRONMENT 16 Environment Variable information that's also available in $_ENV. INFO_VARIABLES 32 Shows all predefined variables from EGPCS (Environment, GET, POST, Cookie, Server). INFO_LICENSE 64 PHP License information. See also the » license FAQ. INFO_ALL -1 Shows all of the above.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.2.2 | The "Loaded Configuration File" information was added, when before only "Configuration File (php.ini) Path" existed. |
Przykłady
Przykład #1 phpinfo() Example
<?php
// Show all information, defaults to INFO_ALL
phpinfo();
// Show just the module information.
// phpinfo(8) yields identical results.
phpinfo(INFO_MODULES);
?>
Notatki
Informacja:
Parts of the information displayed are disabled when the expose_php configuration setting is set to off. This includes the PHP and Zend logos, and the credits.
Informacja:
phpinfo() outputs plain text instead of HTML when using the CLI mode.
Zobacz też:
- phpversion() - Gets the current PHP version
- phpcredits() - Prints out the credits for PHP
- php_logo_guid() - Gets the logo guid
- ini_get() - Gets the value of a configuration option
- ini_set() - Sets the value of a configuration option
- get_loaded_extensions() - Returns an array with the names of all modules compiled and loaded
- Predefined Variables
phpversion
(PHP 4, PHP 5)
phpversion — Gets the current PHP version
Opis
$extension
] )Returns a string containing the version of the currently running PHP parser or extension.
Parametry
-
extension -
An optional extension name.
Zwracane wartości
If the optional extension parameter is
specified, phpversion() returns the version of that
extension, or FALSE if there is no version information associated or
the extension isn't enabled.
Przykłady
Przykład #1 phpversion() example
<?php
// prints e.g. 'Current PHP version: 4.1.1'
echo 'Current PHP version: ' . phpversion();
// prints e.g. '2.0' or nothing if the extension isn't enabled
echo phpversion('tidy');
?>
Przykład #2 PHP_VERSION_ID example and usage
<?php
// PHP_VERSION_ID is available as of PHP 5.2.7, if our
// version is lower than that, then emulate it
if (!defined('PHP_VERSION_ID')) {
$version = explode('.', PHP_VERSION);
define('PHP_VERSION_ID', ($version[0] * 10000 + $version[1] * 100 + $version[2]));
}
// PHP_VERSION_ID is defined as a number, where the higher the number
// is, the newer a PHP version is used. It's defined as used in the above
// expression:
//
// $version_id = $major_version * 10000 + $minor_version * 100 + $release_version;
//
// Now with PHP_VERSION_ID we can check for features this PHP version
// may have, this doesn't require to use version_compare() everytime
// you check if the current PHP version may not support a feature.
//
// For example, we may here define the PHP_VERSION_* constants thats
// not available in versions prior to 5.2.7
if (PHP_VERSION_ID < 50207) {
define('PHP_MAJOR_VERSION', $version[0]);
define('PHP_MINOR_VERSION', $version[1]);
define('PHP_RELEASE_VERSION', $version[2]);
// and so on, ...
}
?>
Notatki
Informacja:
This information is also available in the predefined constant
PHP_VERSION. More versioning information is available using thePHP_VERSION_*constants.
Zobacz też:
- PHP_VERSION constants
- version_compare() - Compares two "PHP-standardized" version number strings
- phpinfo() - Outputs information about PHP's configuration
- phpcredits() - Prints out the credits for PHP
- php_logo_guid() - Gets the logo guid
- zend_version() - Gets the version of the current Zend engine
putenv
(PHP 4, PHP 5)
putenv — Sets the value of an environment variable
Opis
$setting
)
Adds setting to the server environment. The
environment variable will only exist for the duration of the current
request. At the end of the request the environment is restored to its
original state.
Setting certain environment variables may be a potential security breach. The safe_mode_allowed_env_vars directive contains a comma-delimited list of prefixes. In Safe Mode, the user may only alter environment variables whose names begin with the prefixes supplied by this directive. By default, users will only be able to set environment variables that begin with PHP_ (e.g. PHP_FOO=BAR). Note: if this directive is empty, PHP will let the user modify ANY environment variable!
The safe_mode_protected_env_vars directive contains a comma-delimited list of environment variables, that the end user won't be able to change using putenv(). These variables will be protected even if safe_mode_allowed_env_vars is set to allow to change them.
Parametry
-
setting -
The setting, like "FOO=BAR"
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Setting an environment variable
<?php
putenv("UNIQID=$uniqid");
?>
Notatki
The safe_mode_allowed_env_vars and safe_mode_protected_env_vars directives only take effect when safe_mode is enabled.
restore_include_path
(PHP 4 >= 4.3.0, PHP 5)
restore_include_path — Restores the value of the include_path configuration option
Opis
Restores the include_path configuration option back to its original master value as set in php.ini
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 restore_include_path() example
<?php
echo get_include_path(); // .:/usr/local/lib/php
set_include_path('/inc');
echo get_include_path(); // /inc
// Works as of PHP 4.3.0
restore_include_path();
// Works in all PHP versions
ini_restore('include_path');
echo get_include_path(); // .:/usr/local/lib/php
?>
Zobacz też:
- ini_restore() - Restores the value of a configuration option
- get_include_path() - Gets the current include_path configuration option
- set_include_path() - Sets the include_path configuration option
- include()
set_include_path
(PHP 4 >= 4.3.0, PHP 5)
set_include_path — Sets the include_path configuration option
Opis
$new_include_path
)Sets the include_path configuration option for the duration of the script.
Zwracane wartości
Returns the old include_path on
success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 set_include_path() example
<?php
// Works as of PHP 4.3.0
set_include_path('/usr/lib/pear');
// Works in all PHP versions
ini_set('include_path', '/usr/lib/pear');
?>
Przykład #2 Adding to the include path
Making use of the PATH_SEPARATOR constant, it is
possible to extend the include path regardless of the operating system.
In this example we add /usr/lib/pear to the end of the existing include_path.
<?php
$path = '/usr/lib/pear';
set_include_path(get_include_path() . PATH_SEPARATOR . $path);
?>
Zobacz też:
- ini_set() - Sets the value of a configuration option
- get_include_path() - Gets the current include_path configuration option
- restore_include_path() - Restores the value of the include_path configuration option
- include()
set_magic_quotes_runtime
(PHP 4, PHP 5)
set_magic_quotes_runtime — Sets the current active configuration setting of magic_quotes_runtime
Opis
$new_setting
)Set the current active configuration setting of magic_quotes_runtime.
Ta funkcja jest PRZESTARZAŁA od PHP 5.3.0. Używanie tej funkcji nie jest zalecane.
Parametry
-
new_setting -
FALSEfor off,TRUEfor on.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 set_magic_quotes_runtime() example
<?php
// Create a temporary file pointer
$fp = tmpfile();
// Write some data to the pointer
fwrite($fp, '\'PHP\' is a Recursive acronym');
// Without magic_quotes_runtime
rewind($fp);
set_magic_quotes_runtime(false);
echo 'Without magic_quotes_runtime: ' . fread($fp, 64), PHP_EOL;
// With magic_quotes_runtime
rewind($fp);
set_magic_quotes_runtime(true);
echo 'With magic_quotes_runtime: ' . fread($fp, 64), PHP_EOL;
// Clean up
fclose($fp);
?>
Powyższy przykład wyświetli:
Without magic_quotes_runtime: 'PHP' is a Recursive acronym With magic_quotes_runtime: \'PHP\' is a Recursive acronym
Zobacz też:
- get_magic_quotes_gpc() - Gets the current configuration setting of magic_quotes_gpc
- get_magic_quotes_runtime() - Gets the current active configuration setting of magic_quotes_runtime
set_time_limit
(PHP 4, PHP 5)
set_time_limit — Limits the maximum execution time
Opis
$seconds
)Set the number of seconds a script is allowed to run. If this is reached, the script returns a fatal error. The default limit is 30 seconds or, if it exists, the max_execution_time value defined in the php.ini.
When called, set_time_limit() restarts the timeout counter from zero. In other words, if the timeout is the default 30 seconds, and 25 seconds into script execution a call such as set_time_limit(20) is made, the script will run for a total of 45 seconds before timing out.
Parametry
-
seconds -
The maximum execution time, in seconds. If set to zero, no time limit is imposed.
Zwracane wartości
Nie jest zwracana żadna wartość.
Notatki
This function has no effect when PHP is running in tryb bezpieczny. There is no workaround other than turning off safe mode or changing the time limit in the php.ini.
Informacja:
The set_time_limit() function and the configuration directive max_execution_time only affect the execution time of the script itself. Any time spent on activity that happens outside the execution of the script such as system calls using system(), stream operations, database queries, etc. is not included when determining the maximum time that the script has been running. This is not true on Windows where the measured time is real.
sys_get_temp_dir
(PHP 5 >= 5.2.1)
sys_get_temp_dir — Returns directory path used for temporary files
Opis
Returns the path of the directory PHP stores temporary files in by default.
Zwracane wartości
Returns the path of the temporary directory.
Przykłady
Przykład #1 sys_get_temp_dir() example
<?php
// Create a temporary file in the temporary
// files directory using sys_get_temp_dir()
$temp_file = tempnam(sys_get_temp_dir(), 'Tux');
echo $temp_file;
?>
Powyższy przykład wyświetli coś podobnego do:
C:\Windows\Temp\TuxA318.tmp
version_compare
(PHP 4 >= 4.1.0, PHP 5)
version_compare — Compares two "PHP-standardized" version number strings
Opis
version_compare() compares two "PHP-standardized" version number strings. This is useful if you would like to write programs working only on some versions of PHP.
The function first replaces _, - and + with a dot . in the version strings and also inserts dots . before and after any non number so that for example '4.3.2RC1' becomes '4.3.2.RC.1'. Then it splits the results like if you were using explode('.', $ver). Then it compares the parts starting from left to right. If a part contains special version strings these are handled in the following order: any string not found in this list < dev < alpha = a < beta = b < RC = rc < # < pl = p. This way not only versions with different levels like '4.1' and '4.1.2' can be compared but also any PHP specific version containing development state.
Parametry
-
version1 -
First version number.
-
version2 -
Second version number.
-
operator -
If you specify the third optional
operatorargument, you can test for a particular relationship. The possible operators are: <, lt, <=, le, >, gt, >=, ge, ==, =, eq, !=, <>, ne respectively.This parameter is case-sensitive, so values should be lowercase.
Zwracane wartości
By default, version_compare() returns -1 if the first version is lower than the second, 0 if they are equal, and 1 if the second is lower.
When using the optional operator argument, the
function will return TRUE if the relationship is the one specified
by the operator, FALSE otherwise.
Przykłady
The examples below use the PHP_VERSION constant,
because it contains the value of the PHP version that is executing
the code.
Przykład #1 version_compare() examples
<?php
if (version_compare(PHP_VERSION, '6.0.0') >= 0) {
echo 'I am at least PHP version 6.0.0, my version: ' . PHP_VERSION . "\n";
}
if (version_compare(PHP_VERSION, '5.3.0') >= 0) {
echo 'I am at least PHP version 5.3.0, my version: ' . PHP_VERSION . "\n";
}
if (version_compare(PHP_VERSION, '5.0.0', '>=')) {
echo 'I am using PHP 5, my version: ' . PHP_VERSION . "\n";
}
if (version_compare(PHP_VERSION, '5.0.0', '<')) {
echo 'I am using PHP 4, my version: ' . PHP_VERSION . "\n";
}
?>
Notatki
Informacja:
The
PHP_VERSIONconstant holds current PHP version.
Informacja:
Note that pre-release versions, such as 5.3.0-dev, are considered lower than their final release counterparts (like 5.3.0).
Zobacz też:
- phpversion() - Gets the current PHP version
- php_uname() - Returns information about the operating system PHP is running on
- function_exists() - Return TRUE if the given function has been defined
zend_logo_guid
(PHP 4, PHP 5)
zend_logo_guid — Gets the Zend guid
Opis
This function returns the ID which can be used to display the Zend logo using the built-in image.
Zwracane wartości
Returns PHPE9568F35-D428-11d2-A769-00AA001ACF42.
Przykłady
Przykład #1 zend_logo_guid() example
<?php
echo '<img src="' . $_SERVER['PHP_SELF'] .
'?=' . zend_logo_guid() . '" alt="Zend Logo !" />';
?>
zend_thread_id
(PHP 5)
zend_thread_id — Returns a unique identifier for the current thread
Opis
This function returns a unique identifier for the current thread.
Zwracane wartości
Returns the thread id as an integer.
Przykłady
Przykład #1 zend_thread_id() example
<?php
$thread_id = zend_thread_id();
echo 'Current thread id is: ' . $thread_id;
?>
Powyższy przykład wyświetli coś podobnego do:
Current thread id is: 7864
Notatki
Informacja:
This function is only available if PHP has been built with ZTS (Zend Thread Safety) support and debug mode (--enable-debug).
zend_version
(PHP 4, PHP 5)
zend_version — Gets the version of the current Zend engine
Opis
Returns a string containing the version of the currently running Zend Engine.
Zwracane wartości
Returns the Zend Engine version number, as a string.
Przykłady
Przykład #1 zend_version() example
<?php
echo "Zend engine version: " . zend_version();
?>
Powyższy przykład wyświetli coś podobnego do:
Zend engine version: 2.2.0
Zobacz też:
- phpinfo() - Outputs information about PHP's configuration
- phpcredits() - Prints out the credits for PHP
- php_logo_guid() - Gets the logo guid
- phpversion() - Gets the current PHP version
Spis treści
- assert_options — Set/get the various assert flags
- assert — Checks if assertion is FALSE
- dl — Loads a PHP extension at runtime
- extension_loaded — Find out whether an extension is loaded
- gc_collect_cycles — Forces collection of any existing garbage cycles
- gc_disable — Deactivates the circular reference collector
- gc_enable — Activates the circular reference collector
- gc_enabled — Returns status of the circular reference collector
- get_cfg_var — Gets the value of a PHP configuration option
- get_current_user — Gets the name of the owner of the current PHP script
- get_defined_constants — Returns an associative array with the names of all the constants and their values
- get_extension_funcs — Returns an array with the names of the functions of a module
- get_include_path — Gets the current include_path configuration option
- get_included_files — Returns an array with the names of included or required files
- get_loaded_extensions — Returns an array with the names of all modules compiled and loaded
- get_magic_quotes_gpc — Gets the current configuration setting of magic_quotes_gpc
- get_magic_quotes_runtime — Gets the current active configuration setting of magic_quotes_runtime
- get_required_files — Alias dla get_included_files
- getenv — Gets the value of an environment variable
- getlastmod — Gets time of last page modification
- getmygid — Get PHP script owner's GID
- getmyinode — Gets the inode of the current script
- getmypid — Gets PHP's process ID
- getmyuid — Gets PHP script owner's UID
- getopt — Gets options from the command line argument list
- getrusage — Gets the current resource usages
- ini_alter — Alias dla ini_set
- ini_get_all — Gets all configuration options
- ini_get — Gets the value of a configuration option
- ini_restore — Restores the value of a configuration option
- ini_set — Sets the value of a configuration option
- magic_quotes_runtime — Alias dla set_magic_quotes_runtime
- main — Dummy for main
- memory_get_peak_usage — Returns the peak of memory allocated by PHP
- memory_get_usage — Returns the amount of memory allocated to PHP
- php_ini_loaded_file — Retrieve a path to the loaded php.ini file
- php_ini_scanned_files — Return a list of .ini files parsed from the additional ini dir
- php_logo_guid — Gets the logo guid
- php_sapi_name — Returns the type of interface between web server and PHP
- php_uname — Returns information about the operating system PHP is running on
- phpcredits — Prints out the credits for PHP
- phpinfo — Outputs information about PHP's configuration
- phpversion — Gets the current PHP version
- putenv — Sets the value of an environment variable
- restore_include_path — Restores the value of the include_path configuration option
- set_include_path — Sets the include_path configuration option
- set_magic_quotes_runtime — Sets the current active configuration setting of magic_quotes_runtime
- set_time_limit — Limits the maximum execution time
- sys_get_temp_dir — Returns directory path used for temporary files
- version_compare — Compares two "PHP-standardized" version number strings
- zend_logo_guid — Gets the Zend guid
- zend_thread_id — Returns a unique identifier for the current thread
- zend_version — Gets the version of the current Zend engine
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- PHP Options/Info Funkcje
- assert_options — Set/get the various assert flags
- assert — Checks if assertion is FALSE
- dl — Loads a PHP extension at runtime
- extension_loaded — Find out whether an extension is loaded
- gc_collect_cycles — Forces collection of any existing garbage cycles
- gc_disable — Deactivates the circular reference collector
- gc_enable — Activates the circular reference collector
- gc_enabled — Returns status of the circular reference collector
- get_cfg_var — Gets the value of a PHP configuration option
- get_current_user — Gets the name of the owner of the current PHP script
- get_defined_constants — Returns an associative array with the names of all the constants and their values
- get_extension_funcs — Returns an array with the names of the functions of a module
- get_include_path — Gets the current include_path configuration option
- get_included_files — Returns an array with the names of included or required files
- get_loaded_extensions — Returns an array with the names of all modules compiled and loaded
- get_magic_quotes_gpc — Gets the current configuration setting of magic_quotes_gpc
- get_magic_quotes_runtime — Gets the current active configuration setting of magic_quotes_runtime
- get_required_files — Alias dla get_included_files
- getenv — Gets the value of an environment variable
- getlastmod — Gets time of last page modification
- getmygid — Get PHP script owner's GID
- getmyinode — Gets the inode of the current script
- getmypid — Gets PHP's process ID
- getmyuid — Gets PHP script owner's UID
- getopt — Gets options from the command line argument list
- getrusage — Gets the current resource usages
- ini_alter — Alias dla ini_set
- ini_get_all — Gets all configuration options
- ini_get — Gets the value of a configuration option
- ini_restore — Restores the value of a configuration option
- ini_set — Sets the value of a configuration option
- magic_quotes_runtime — Alias dla set_magic_quotes_runtime
- main — Dummy for main
- memory_get_peak_usage — Returns the peak of memory allocated by PHP
- memory_get_usage — Returns the amount of memory allocated to PHP
- php_ini_loaded_file — Retrieve a path to the loaded php.ini file
- php_ini_scanned_files — Return a list of .ini files parsed from the additional ini dir
- php_logo_guid — Gets the logo guid
- php_sapi_name — Returns the type of interface between web server and PHP
- php_uname — Returns information about the operating system PHP is running on
- phpcredits — Prints out the credits for PHP
- phpinfo — Outputs information about PHP's configuration
- phpversion — Gets the current PHP version
- putenv — Sets the value of an environment variable
- restore_include_path — Restores the value of the include_path configuration option
- set_include_path — Sets the include_path configuration option
- set_magic_quotes_runtime — Sets the current active configuration setting of magic_quotes_runtime
- set_time_limit — Limits the maximum execution time
- sys_get_temp_dir — Returns directory path used for temporary files
- version_compare — Compares two "PHP-standardized" version number strings
- zend_logo_guid — Gets the Zend guid
- zend_thread_id — Returns a unique identifier for the current thread
- zend_version — Gets the version of the current Zend engine
runkit
Wstęp
The runkit extension provides means to modify constants, user-defined functions, and user-defined classes. It also provides for custom superglobal variables and embeddable sub-interpreters via sandboxing.
This package is meant as a feature added replacement for the » classkit package. When compiled with the --enable-runkit=classkit option to ./configure, it will export classkit compatible function definitions and constants.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
-
RUNKIT_IMPORT_FUNCTIONS(integer) - runkit_import() flag indicating that normal functions should be imported from the specified file.
-
RUNKIT_IMPORT_CLASS_METHODS(integer) - runkit_import() flag indicating that class methods should be imported from the specified file.
-
RUNKIT_IMPORT_CLASS_CONSTS(integer) - runkit_import() flag indicating that class constants should be imported from the specified file. Note that this flag is only meaningful in PHP versions 5.1.0 and above.
-
RUNKIT_IMPORT_CLASS_PROPS(integer) - runkit_import() flag indicating that class standard properties should be imported from the specified file.
-
RUNKIT_IMPORT_CLASSES(integer) -
runkit_import() flag representing
a bitwise OR of the
RUNKIT_IMPORT_CLASS_*constants. -
RUNKIT_IMPORT_OVERRIDE(integer) - runkit_import() flag indicating that if any of the imported functions, methods, constants, or properties already exist, they should be replaced with the new definitions. If this flag is not set, then any imported definitions which already exist will be discarded.
-
RUNKIT_ACC_PUBLIC(integer) - PHP 5 specific flag to runkit_method_add()
-
RUNKIT_ACC_PROTECTED(integer) - PHP 5 specific flag to runkit_method_add()
-
RUNKIT_ACC_PRIVATE(integer) - PHP 5 specific flag to runkit_method_add()
-
CLASSKIT_ACC_PUBLIC(integer) - PHP 5 specific flag to classkit_method_add() Only defined when classkit compatibility is enabled.
-
CLASSKIT_ACC_PROTECTED(integer) - PHP 5 specific flag to classkit_method_add() Only defined when classkit compatibility is enabled.
-
CLASSKIT_ACC_PRIVATE(integer) - PHP 5 specific flag to classkit_method_add() Only defined when classkit compatibility is enabled.
-
CLASSKIT_AGGREGATE_OVERRIDE(integer) - PHP 5 specific flag to classkit_import() Only defined when classkit compatibility is enabled.
-
RUNKIT_VERSION(string) - Defined to the current version of the runkit package.
-
CLASSKIT_VERSION(string) - Defined to the current version of the runkit package. Only defined when classkit compatibility is enabled.
Instalacja/Konfiguracja
Spis treści
Wymagania
Modifying Constants, Functions, Classes, and Methods works with all releases of PHP 4 and PHP 5. No special requirements are necessary.
Custom Superglobals are only available in PHP 4.2.0 or later.
Sandboxing requires PHP 5.1.0 or later, or PHP 5.0.0 with a special TSRM patch applied. Regardless of which version of PHP is in use it must be compiled with the --enable-maintainer-zts option. See the README file in the runkit package for additional information.
Instalacja
To rozszerzenie » PECL nie jest dołączane do PHP.
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/runkit.
DLL z tym rozszerzeniem PECL można pobrać zarówno ze strony » PHP Downloads lub z » http://pecl4win.php.net/
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| runkit.superglobal | "" | PHP_INI_PERDIR | |
| runkit.internal_override | "0" | PHP_INI_SYSTEM |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
runkit.superglobalstring -
Comma-separated list of variable names to be treated as superglobals.
This value should be set in the systemwide php.ini file, but may work
in perdir configuration contexts depending on your SAPI.
Przykład #1 Custom Superglobals with runkit.superglobal=_FOO,_BAR in php.ini
<?php
function show_values() {
echo "Foo is $_FOO\n";
echo "Bar is $_BAR\n";
echo "Baz is $_BAZ\n";
}
$_FOO = 'foo';
$_BAR = 'bar';
$_BAZ = 'baz';
/* Displays foo and bar, but not baz */
show_values();
?> -
runkit.internal_overrideboolean - Enables ability to modify/rename/remove internal functions.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
runkit Funkcje
Runkit_Sandbox
(PECL runkit >= 0.7.0)
Runkit_Sandbox — Runkit Sandbox Class -- PHP Virtual Machine
Opis
Instantiating the Runkit_Sandbox class creates a new thread with its own scope and program stack. Using a set of options passed to the constructor, this environment may be restricted to a subset of what the primary interpreter can do and provide a safer environment for executing user supplied code.
Informacja: Obsługa rozszerzenia Sandbox (wymagane dla runkit_lint(), runkit_lint_file(), i klasy Runkit_Sandbox) jest dostępna tylko w PHP 5.1.0 lub specjalnie zmodyfikowanych wersjach PHP 5.0, i wymaga włączonego bezpieczeństwa wątków. Więcej informacji można znaleźć w pliku README dołączonym do pakietu runkit.
Constructor
$options
] )
options is an associative array containing
any combination of the special ini options listed below.
-
safe_mode -
If the outer script which is instantiating the Runkit_Sandbox class is configured with safe_mode = off, then safe_mode may be turned on for the sandbox environment. This setting can not be used to disable safe_mode when it's already enabled in the outer script.
-
safe_mode_gid -
If the outer script which is instantiating the Runkit_Sandbox class is configured with safe_mode_gid = on, then safe_mode_gid may be turned off for the sandbox environment. This setting can not be used to enable safe_mode_gid when it's already disabled in the outer script.
-
safe_mode_include_dir -
If the outer script which is instantiating the Runkit_Sandbox class is configured with a safe_mode_include_dir, then a new safe_mode_include_dir may be set for sandbox environments below the currently defined value. safe_mode_include_dir may also be cleared to indicate that the bypass feature is disabled. If safe_mode_include_dir was blank in the outer script, but safe_mode was not enabled, then any arbitrary safe_mode_include_dir may be set while turning safe_mode on.
-
open_basedir -
open_basedirmay be set to any path below the current setting of open_basedir. If open_basedir is not set within the global scope, then it is assumed to be the root directory and may be set to any location. -
allow_url_fopen -
Like
safe_mode, this setting can only be made more restrictive, in this case by setting it toFALSEwhen it is previously set toTRUE -
disable_functions -
Comma separated list of functions to disable within the sandbox sub-interpreter. This list need not contain the names of the currently disabled functions, they will remain disabled whether listed here or not.
-
disable_classes -
Comma separated list of classes to disable within the sandbox sub-interpreter. This list need not contain the names of the currently disabled classes, they will remain disabled whether listed here or not.
-
runkit.superglobal -
Comma separated list of variables to be treated as superglobals within the sandbox sub-interpreter. These variables will be used in addition to any variables defined internally or through the global runkit.superglobal setting.
-
runkit.internal_override -
Ini option runkit.internal_override may be disabled (but not re-enabled) within sandboxes.
Przykład #1 Instantiating a restricted sandbox
<?php
$options = array(
'safe_mode'=>true,
'open_basedir'=>'/var/www/users/jdoe/',
'allow_url_fopen'=>'false',
'disable_functions'=>'exec,shell_exec,passthru,system',
'disable_classes'=>'myAppClass');
$sandbox = new Runkit_Sandbox($options);
/* Non-protected ini settings may set normally */
$sandbox->ini_set('html_errors',true);
?>
Accessing Variables
All variables in the global scope of the sandbox environment are accessible as properties of the sandbox object. The first thing to note is that because of the way memory between these two threads is managed, object and resource variables can not currently be exchanged between interpreters. Additionally, all arrays are deep copied and any references will be lost. This also means that references between interpreters are not possible.
Przykład #2 Working with variables in a sandbox
<?php
$sandbox = new Runkit_Sandbox();
$sandbox->foo = 'bar';
$sandbox->eval('echo "$foo\n"; $bar = $foo . "baz";');
echo "{$sandbox->bar}\n";
if (isset($sandbox->foo)) unset($sandbox->foo);
$sandbox->eval('var_dump(isset($foo));');
?>
Powyższy przykład wyświetli:
bar barbaz bool(false)
Calling PHP Functions
Any function defined within the sandbox may be called as a method on the sandbox object. This also includes a few pseudo-function language constructs: eval(), include(), include_once(), require(), require_once(), echo(), print(), die(), and exit().
Przykład #3 Calling sandbox functions
<?php
$sandbox = new Runkit_Sandbox();
echo $sandbox->str_replace('a','f','abc');
?>
Powyższy przykład wyświetli:
fbc
When passing arguments to a sandbox function, the arguments are taken from the outer instance of PHP. If you wish to pass arguments from the sandbox's scope, be sure to access them as properties of the sandbox object as illustrated above.
Przykład #4 Passing arguments to sandbox functions
<?php
$sandbox = new Runkit_Sandbox();
$foo = 'bar';
$sandbox->foo = 'baz';
echo $sandbox->str_replace('a',$foo,'a');
echo $sandbox->str_replace('a',$sandbox->foo,'a');
?>
Powyższy przykład wyświetli:
bar baz
Changing Sandbox Settings
As of runkit version 0.5, certain Sandbox settings may
be modified on the fly using ArrayAccess syntax.
Some settings, such as active
are read-only and meant to provide status information.
Other settings, such as output_handler
may be set and read much like a normal array offset.
Future settings may be write-only, however no such
settings currently exist.
| Setting | Type | Purpose | Default |
|---|---|---|---|
| active | Boolean (Read Only) |
TRUE if the Sandbox is still in a usable state,
FALSE if the request is in bailout due to a
call to die(), exit(), or because of a fatal
error condition.
|
TRUE (Initial) |
| output_handler | Callback | When set to a valid callback, all output generated by the Sandbox instance will be processed through the named function. Sandbox output handlers follow the same calling conventions as the system-wide output handler. | None |
| parent_access | Boolean | May the sandbox use instances of the Runkit_Sandbox_Parent class? Must be enabled for other Runkit_Sandbox_Parent related settings to work. | FALSE |
| parent_read | Boolean | May the sandbox read variables in its parent's context? | FALSE |
| parent_write | Boolean | May the sandbox modify variables in its parent's context? | FALSE |
| parent_eval | Boolean | May the sandbox evaluate arbitrary code in its parent's context? DANGEROUS | FALSE |
| parent_include | Boolean | May the sandbox include php code files in its parent's context? DANGEROUS | FALSE |
| parent_echo | Boolean | May the sandbox echo data in its parent's context effectively bypassing its own output_handler? | FALSE |
| parent_call | Boolean | May the sandbox call functions in its parent's context? | FALSE |
| parent_die | Boolean | May the sandbox kill its own parent? (And thus itself) | FALSE |
| parent_scope | Integer | What scope will parental property access look at? 0 == Global scope, 1 == Calling scope, 2 == Scope preceeding calling scope, 3 == The scope before that, etc..., etc... | 0 (Global) |
| parent_scope | String | When parent_scope is set to a string value, it refers to a named array variable in the global scope. If the named variable does not exist at the time of access it will be created as an empty array. If the variable exists but it not an array, a dummy array will be created containing a reference to the named global variable. |
Runkit_Sandbox_Parent
(PECL runkit >= 0.7.0)
Runkit_Sandbox_Parent — Runkit Anti-Sandbox Class
Opis
Instantiating the Runkit_Sandbox_Parent class from within a sandbox environment created from the Runkit_Sandbox class provides some (controlled) means for a sandbox child to access its parent.
Informacja: Obsługa rozszerzenia Sandbox (wymagane dla runkit_lint(), runkit_lint_file(), i klasy Runkit_Sandbox) jest dostępna tylko w PHP 5.1.0 lub specjalnie zmodyfikowanych wersjach PHP 5.0, i wymaga włączonego bezpieczeństwa wątków. Więcej informacji można znaleźć w pliku README dołączonym do pakietu runkit.
In order for any of the Runkit_Sandbox_Parent features to function. Support must be enabled on a per-sandbox basis by enabling the parent_access flag from the parent's context.
Przykład #1 Working with variables in a sandbox
<?php
$sandbox = new Runkit_Sandbox();
$sandbox['parent_access'] = true;
?>
Accessing the Parent's Variables
Just as with sandbox variable access, a sandbox parent's variables may be read from and written to as properties of the Runkit_Sandbox_Parent class. Read access to parental variables may be enabled with the parent_read setting (in addition to the base parent_access setting). Write access, in turn, is enabled through the parent_write setting.
Unlike sandbox child variable access, the variable scope is not limited to globals only. By setting the parent_scope setting to an appropriate integer value, other scopes in the active call stack may be inspected instead. A value of 0 (Default) will direct variable access at the global scope. 1 will point variable access at whatever variable scope was active at the time the current block of sandbox code was executed. Higher values progress back through the functions that called the functions that led to the sandbox executing code that tried to access its own parent's variables.
Przykład #2 Accessing parental variables
<?php
$php = new Runkit_Sandbox();
$php['parent_access'] = true;
$php['parent_read'] = true;
$test = "Global";
$php->eval('$PARENT = new Runkit_Sandbox_Parent;');
$php['parent_scope'] = 0;
one();
$php['parent_scope'] = 1;
one();
$php['parent_scope'] = 2;
one();
$php['parent_scope'] = 3;
one();
$php['parent_scope'] = 4;
one();
$php['parent_scope'] = 5;
one();
function one() {
$test = "one()";
two();
}
function two() {
$test = "two()";
three();
}
function three() {
$test = "three()";
$GLOBALS['php']->eval('var_dump($PARENT->test);');
}
?>
Powyższy przykład wyświetli:
string(6) "Global" string(7) "three()" string(5) "two()" string(5) "one()" string(6) "Global" string(6) "Global"
Calling the Parent's Functions
Just as with sandbox access, a sandbox may access its parents functions providing that the proper settings have been enabled. Enabling parent_call will allow the sandbox to call all functions available to the parent scope. Language constructs are each controlled by their own setting: print() and echo() are enabled with parent_echo. die() and exit() are enabled with parent_die. eval() is enabled with parent_eval while include(), include_once(), require(), and require_once() are enabled through parent_include.
runkit_class_adopt
(PECL runkit >= 0.7.0)
runkit_class_adopt — Convert a base class to an inherited class, add ancestral methods when appropriate
Opis
$classname
, string $parentname
)Parametry
-
classname -
Name of class to be adopted
-
parentname -
Parent class which child class is extending
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 A runkit_class_adopt() example
<?php
class myParent {
function parentFunc() {
echo "Parent Function Output\n";
}
}
class myChild {
}
runkit_class_adopt('myChild','myParent');
myChild::parentFunc();
?>
Powyższy przykład wyświetli:
Parent Function Output
Zobacz też:
- runkit_class_emancipate() - Convert an inherited class to a base class, removes any method whose scope is ancestral
runkit_class_emancipate
(PECL runkit >= 0.7.0)
runkit_class_emancipate — Convert an inherited class to a base class, removes any method whose scope is ancestral
Opis
$classname
)Parametry
-
classname -
Name of class to emancipate
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 A runkit_class_emancipate() example
<?php
class myParent {
function parentFunc () {
echo "Parent Function Output\n";
}
}
class myChild extends myParent {
}
myChild::parentFunc();
runkit_class_emancipate('myChild');
myChild::parentFunc();
?>
Powyższy przykład wyświetli:
Parent Function Output Fatal error: Call to undefined function: parentFunc() in example.php on line 12
Zobacz też:
- runkit_class_adopt() - Convert a base class to an inherited class, add ancestral methods when appropriate
runkit_constant_add
(PECL runkit >= 0.7.0)
runkit_constant_add — Similar to define(), but allows defining in class definitions as well
Opis
Parametry
-
constname -
Name of constant to declare. Either a string to indicate a global constant, or classname::constname to indicate a class constant.
-
value -
NULL, Bool, Long, Double, String, or Resource value to store in the new constant.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- define() - Defines a named constant
- runkit_constant_redefine() - Redefine an already defined constant
- runkit_constant_remove() - Remove/Delete an already defined constant
runkit_constant_redefine
(PECL runkit >= 0.7.0)
runkit_constant_redefine — Redefine an already defined constant
Opis
Parametry
-
constname -
Constant to redefine. Either string indicating global constant, or classname::constname indicating class constant.
-
newvalue -
New value to assign to constant.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- runkit_constant_add() - Similar to define(), but allows defining in class definitions as well
- runkit_constant_remove() - Remove/Delete an already defined constant
runkit_constant_remove
(PECL runkit >= 0.7.0)
runkit_constant_remove — Remove/Delete an already defined constant
Opis
$constname
)Parametry
-
constname -
Name of constant to remove. Either a string indicating a global constant, or classname::constname indicating a class constant.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- define() - Defines a named constant
- runkit_constant_add() - Similar to define(), but allows defining in class definitions as well
- runkit_constant_redefine() - Redefine an already defined constant
runkit_function_add
(PECL runkit >= 0.7.0)
runkit_function_add — Add a new function, similar to create_function()
Opis
$funcname
, string $arglist
, string $code
)Parametry
-
funcname -
Name of function to be created
-
arglist -
Comma separated argument list
-
code -
Code making up the function
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 A runkit_function_add() example
<?php
runkit_function_add('testme','$a,$b','echo "The value of a is $a\n"; echo "The value of b is $b\n";');
testme(1,2);
?>
Powyższy przykład wyświetli:
The value of a is 1 The value of b is 2
Zobacz też:
- create_function() - Create an anonymous (lambda-style) function
- runkit_function_redefine() - Replace a function definition with a new implementation
- runkit_function_copy() - Copy a function to a new function name
- runkit_function_rename() - Change a function's name
- runkit_function_remove() - Remove a function definition
- runkit_method_add() - Dynamically adds a new method to a given class
runkit_function_copy
(PECL runkit >= 0.7.0)
runkit_function_copy — Copy a function to a new function name
Opis
$funcname
, string $targetname
)Parametry
-
funcname -
Name of existing function
-
targetname -
Name of new function to copy definition to
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 A runkit_function_copy() example
<?php
function original() {
echo "In a function\n";
}
runkit_function_copy('original','duplicate');
original();
duplicate();
?>
Powyższy przykład wyświetli:
In a function In a function
Zobacz też:
- runkit_function_add() - Add a new function, similar to create_function
- runkit_function_redefine() - Replace a function definition with a new implementation
- runkit_function_rename() - Change a function's name
- runkit_function_remove() - Remove a function definition
runkit_function_redefine
(PECL runkit >= 0.7.0)
runkit_function_redefine — Replace a function definition with a new implementation
Opis
$funcname
, string $arglist
, string $code
)Informacja: Domyślnie, tylko funkcje przestrzeni użytkownika mogą być usunięte, przemianowane lub zmodyfikowane. Aby uzyskać możliwość modyfikacji funkcji wewnętrznych, należy włączyć opcję runkit.internal_override w pliku php.ini.
Parametry
-
funcname -
Name of function to redefine
-
arglist -
New list of arguments to be accepted by function
-
code -
New code implementation
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 A runkit_function_redefine() example
<?php
function testme() {
echo "Original Testme Implementation\n";
}
testme();
runkit_function_redefine('testme','','echo "New Testme Implementation\n";');
testme();
?>
Powyższy przykład wyświetli:
Original Testme Implementation New Testme Implementation
Zobacz też:
- runkit_function_add() - Add a new function, similar to create_function
- runkit_function_copy() - Copy a function to a new function name
- runkit_function_rename() - Change a function's name
- runkit_function_remove() - Remove a function definition
runkit_function_remove
(PECL runkit >= 0.7.0)
runkit_function_remove — Remove a function definition
Opis
$funcname
)Informacja: Domyślnie, tylko funkcje przestrzeni użytkownika mogą być usunięte, przemianowane lub zmodyfikowane. Aby uzyskać możliwość modyfikacji funkcji wewnętrznych, należy włączyć opcję runkit.internal_override w pliku php.ini.
Parametry
-
funcname -
Name of function to be deleted
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- runkit_function_add() - Add a new function, similar to create_function
- runkit_function_copy() - Copy a function to a new function name
- runkit_function_redefine() - Replace a function definition with a new implementation
- runkit_function_rename() - Change a function's name
runkit_function_rename
(PECL runkit >= 0.7.0)
runkit_function_rename — Change a function's name
Opis
$funcname
, string $newname
)Informacja: Domyślnie, tylko funkcje przestrzeni użytkownika mogą być usunięte, przemianowane lub zmodyfikowane. Aby uzyskać możliwość modyfikacji funkcji wewnętrznych, należy włączyć opcję runkit.internal_override w pliku php.ini.
Parametry
-
funcname -
Current function name
-
newname -
New function name
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- runkit_function_add() - Add a new function, similar to create_function
- runkit_function_copy() - Copy a function to a new function name
- runkit_function_redefine() - Replace a function definition with a new implementation
- runkit_function_remove() - Remove a function definition
runkit_import
(PECL runkit >= 0.7.0)
runkit_import — Process a PHP file importing function and class definitions, overwriting where appropriate
Opis
$filename
[, int $flags = RUNKIT_IMPORT_CLASS_METHODS
] )
Similar to include() however any code residing outside
of a function or class is simply ignored.
Additionally, depending on the value of flags,
any functions or classes which already exist in the currently running environment
will be automatically overwritten by their new definitions.
Parametry
-
filename -
Filename to import function and class definitions from
-
flags -
Bitwise OR of the
RUNKIT_IMPORT_*family of constants.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
runkit_lint_file
(PECL runkit >= 0.7.0)
runkit_lint_file — Check the PHP syntax of the specified file
Opis
$filename
)The runkit_lint_file() function performs a syntax (lint) check on the specified filename testing for scripting errors. This is similar to using php -l from the commandline.
Informacja: Obsługa rozszerzenia Sandbox (wymagane dla runkit_lint(), runkit_lint_file(), i klasy Runkit_Sandbox) jest dostępna tylko w PHP 5.1.0 lub specjalnie zmodyfikowanych wersjach PHP 5.0, i wymaga włączonego bezpieczeństwa wątków. Więcej informacji można znaleźć w pliku README dołączonym do pakietu runkit.
Parametry
-
filename -
File containing PHP Code to be lint checked
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
runkit_lint
(PECL runkit >= 0.7.0)
runkit_lint — Check the PHP syntax of the specified php code
Opis
$code
)The runkit_lint() function performs a syntax (lint) check on the specified php code testing for scripting errors. This is similar to using php -l from the command line except runkit_lint() accepts actual code rather than a filename.
Informacja: Obsługa rozszerzenia Sandbox (wymagane dla runkit_lint(), runkit_lint_file(), i klasy Runkit_Sandbox) jest dostępna tylko w PHP 5.1.0 lub specjalnie zmodyfikowanych wersjach PHP 5.0, i wymaga włączonego bezpieczeństwa wątków. Więcej informacji można znaleźć w pliku README dołączonym do pakietu runkit.
Parametry
-
code -
PHP Code to be lint checked
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
runkit_method_add
(PECL runkit >= 0.7.0)
runkit_method_add — Dynamically adds a new method to a given class
Opis
$classname
, string $methodname
, string $args
, string $code
[, int $flags = RUNKIT_ACC_PUBLIC
] )Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Parametry
-
classname -
The class to which this method will be added
-
methodname -
The name of the method to add
-
args -
Comma-delimited list of arguments for the newly-created method
-
code -
The code to be evaluated when
methodnameis called -
flags -
The type of method to create, can be
RUNKIT_ACC_PUBLIC,RUNKIT_ACC_PROTECTEDorRUNKIT_ACC_PRIVATEInformacja:
This parameter is only used as of PHP 5, because, prior to this, all methods were public.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 runkit_method_add() example
<?php
class Example {
function foo() {
echo "foo!\n";
}
}
// create an Example object
$e = new Example();
// Add a new public method
runkit_method_add(
'Example',
'add',
'$num1, $num2',
'return $num1 + $num2;',
RUNKIT_ACC_PUBLIC
);
// add 12 + 4
echo $e->add(12, 4);
?>
Powyższy przykład wyświetli:
16
Zobacz też:
- runkit_method_copy() - Copies a method from class to another
- runkit_method_redefine() - Dynamically changes the code of the given method
- runkit_method_remove() - Dynamically removes the given method
- runkit_method_rename() - Dynamically changes the name of the given method
- runkit_function_add() - Add a new function, similar to create_function
runkit_method_copy
(PECL runkit >= 0.7.0)
runkit_method_copy — Copies a method from class to another
Opis
$dClass
, string $dMethod
, string $sClass
[, string $sMethod
] )Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Parametry
-
dClass -
Destination class for copied method
-
dMethod -
Destination method name
-
sClass -
Source class of the method to copy
-
sMethod -
Name of the method to copy from the source class. If this parameter is omitted, the value of
dMethodis assumed.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 runkit_method_copy() example
<?php
class Foo {
function example() {
return "foo!\n";
}
}
class Bar {
// initially, no methods
}
// copy the example() method from the Foo class to the Bar class, as baz()
runkit_method_copy('Bar', 'baz', 'Foo', 'example');
// output copied function
echo Bar::baz();
?>
Powyższy przykład wyświetli:
foo!
Zobacz też:
- runkit_method_add() - Dynamically adds a new method to a given class
- runkit_method_redefine() - Dynamically changes the code of the given method
- runkit_method_remove() - Dynamically removes the given method
- runkit_method_rename() - Dynamically changes the name of the given method
- runkit_function_copy() - Copy a function to a new function name
runkit_method_redefine
(PECL runkit >= 0.7.0)
runkit_method_redefine — Dynamically changes the code of the given method
Opis
$classname
, string $methodname
, string $args
, string $code
[, int $flags = RUNKIT_ACC_PUBLIC
] )Informacja: Ta funkcja nie może być użyta do manipulacji aktualnie działającej (lub powiązanej) metody. This function cannot
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Parametry
-
classname -
The class in which to redefine the method
-
methodname -
The name of the method to redefine
-
args -
Comma-delimited list of arguments for the redefined method
-
code -
The new code to be evaluated when
methodnameis called -
flags -
The redefined method can be
RUNKIT_ACC_PUBLIC,RUNKIT_ACC_PROTECTEDorRUNKIT_ACC_PRIVATEInformacja:
This parameter is only used as of PHP 5, because, prior to this, all methods were public.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 runkit_method_redefine() example
<?php
class Example {
function foo() {
return "foo!\n";
}
}
// create an Example object
$e = new Example();
// output Example::foo() (before redefine)
echo "Before: " . $e->foo();
// Redefine the 'foo' method
runkit_method_redefine(
'Example',
'foo',
'',
'return "bar!\n";',
RUNKIT_ACC_PUBLIC
);
// output Example::foo() (after redefine)
echo "After: " . $e->foo();
?>
Powyższy przykład wyświetli:
Before: foo! After: bar!
Zobacz też:
- runkit_method_add() - Dynamically adds a new method to a given class
- runkit_method_copy() - Copies a method from class to another
- runkit_method_remove() - Dynamically removes the given method
- runkit_method_rename() - Dynamically changes the name of the given method
- runkit_function_redefine() - Replace a function definition with a new implementation
runkit_method_remove
(PECL runkit >= 0.7.0)
runkit_method_remove — Dynamically removes the given method
Opis
$classname
, string $methodname
)Informacja: Ta funkcja nie może być użyta do manipulacji aktualnie działającej (lub powiązanej) metody. This function cannot
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Parametry
-
classname -
The class in which to remove the method
-
methodname -
The name of the method to remove
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 runkit_method_remove() example
<?php
class Example {
function foo() {
return "foo!\n";
}
function bar() {
return "bar!\n";
}
}
// Remove the 'foo' method
runkit_method_remove(
'Example',
'foo'
);
echo implode(' ', get_class_methods('Example'));
?>
Powyższy przykład wyświetli:
bar
Zobacz też:
- runkit_method_add() - Dynamically adds a new method to a given class
- runkit_method_copy() - Copies a method from class to another
- runkit_method_redefine() - Dynamically changes the code of the given method
- runkit_method_rename() - Dynamically changes the name of the given method
- runkit_function_remove() - Remove a function definition
runkit_method_rename
(PECL runkit >= 0.7.0)
runkit_method_rename — Dynamically changes the name of the given method
Opis
$classname
, string $methodname
, string $newname
)Informacja: Ta funkcja nie może być użyta do manipulacji aktualnie działającej (lub powiązanej) metody. This function cannot
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Parametry
-
classname -
The class in which to rename the method
-
methodname -
The name of the method to rename
-
newname -
The new name to give to the renamed method
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 runkit_method_rename() example
<?php
class Example {
function foo() {
return "foo!\n";
}
}
// Rename the 'foo' method to 'bar'
runkit_method_rename(
'Example',
'foo',
'bar'
);
// output renamed function
echo Example::bar();
?>
Powyższy przykład wyświetli:
foo!
Zobacz też:
- runkit_method_add() - Dynamically adds a new method to a given class
- runkit_method_copy() - Copies a method from class to another
- runkit_method_redefine() - Dynamically changes the code of the given method
- runkit_method_remove() - Dynamically removes the given method
- runkit_function_rename() - Change a function's name
runkit_return_value_used
(PECL runkit >= 0.8.0)
runkit_return_value_used — Determines if the current functions return value will be used
Opis
Zwracane wartości
Returns TRUE if the function's return value is used by the calling scope,
otherwise FALSE
Przykłady
Przykład #1 runkit_return_value_used() example
<?php
function foo() {
var_dump(runkit_return_value_used());
}
foo();
$f = foo();
?>
Powyższy przykład wyświetli:
bool(false) bool(true)
runkit_sandbox_output_handler
(PECL runkit >= 0.7.0)
runkit_sandbox_output_handler — Specify a function to capture and/or process output from a runkit sandbox
Opis
Ordinarily, anything output (such as with echo() or print()) will be output as though it were printed from the parent's scope. Using runkit_sandbox_output_handler() however, output generated by the sandbox (including errors), can be captured by a function outside of the sandbox.
Informacja: Obsługa rozszerzenia Sandbox (wymagane dla runkit_lint(), runkit_lint_file(), i klasy Runkit_Sandbox) jest dostępna tylko w PHP 5.1.0 lub specjalnie zmodyfikowanych wersjach PHP 5.0, i wymaga włączonego bezpieczeństwa wątków. Więcej informacji można znaleźć w pliku README dołączonym do pakietu runkit.
Informacja: Deprecated
As of runkit version 0.5, this function is deprecated and is scheduled to be removed from the package prior to a 1.0 release. The output handler for a given Runkit_Sandbox instance may be read/set using the array offset syntax shown on the Runkit_Sandbox class definition page.
Parametry
-
sandbox -
Object instance of Runkit_Sandbox class on which to set output handling.
-
callback -
Name of a function which expects one parameter. Output generated by
sandboxwill be passed to this callback. Anything returned by the callback will be displayed normally. If this parameter is not passed then output handling will not be changed. If a non-truth value is passed, output handling will be disabled and will revert to direct display.
Zwracane wartości
Returns the name of the previously defined output handler callback, or
FALSE if no handler was previously defined.
Przykłady
Przykład #1 Feeding output to a variable
<?php
function capture_output($str) {
$GLOBALS['sandbox_output'] .= $str;
return '';
}
$sandbox_output = '';
$php = new Runkit_Sandbox();
runkit_sandbox_output_handler($php, 'capture_output');
$php->echo("Hello\n");
$php->eval('var_dump("Excuse me");');
$php->die("I lost myself.");
unset($php);
echo "Sandbox Complete\n\n";
echo $sandbox_output;
?>
Powyższy przykład wyświetli:
Sandbox Complete Hello string(9) "Excuse me" I lost myself.
runkit_superglobals
(PECL runkit >= 0.7.0)
runkit_superglobals — Return numerically indexed array of registered superglobals
Opis
Zwracane wartości
Returns a numerically indexed array of the currently registered superglobals. i.e. _GET, _POST, _REQUEST, _COOKIE, _SESSION, _SERVER, _ENV, _FILES
Spis treści
- Runkit_Sandbox — Runkit Sandbox Class -- PHP Virtual Machine
- Runkit_Sandbox_Parent — Runkit Anti-Sandbox Class
- runkit_class_adopt — Convert a base class to an inherited class, add ancestral methods when appropriate
- runkit_class_emancipate — Convert an inherited class to a base class, removes any method whose scope is ancestral
- runkit_constant_add — Similar to define(), but allows defining in class definitions as well
- runkit_constant_redefine — Redefine an already defined constant
- runkit_constant_remove — Remove/Delete an already defined constant
- runkit_function_add — Add a new function, similar to create_function
- runkit_function_copy — Copy a function to a new function name
- runkit_function_redefine — Replace a function definition with a new implementation
- runkit_function_remove — Remove a function definition
- runkit_function_rename — Change a function's name
- runkit_import — Process a PHP file importing function and class definitions, overwriting where appropriate
- runkit_lint_file — Check the PHP syntax of the specified file
- runkit_lint — Check the PHP syntax of the specified php code
- runkit_method_add — Dynamically adds a new method to a given class
- runkit_method_copy — Copies a method from class to another
- runkit_method_redefine — Dynamically changes the code of the given method
- runkit_method_remove — Dynamically removes the given method
- runkit_method_rename — Dynamically changes the name of the given method
- runkit_return_value_used — Determines if the current functions return value will be used
- runkit_sandbox_output_handler — Specify a function to capture and/or process output from a runkit sandbox
- runkit_superglobals — Return numerically indexed array of registered superglobals
- Wstęp
- Stałe predefiniowane
- Instalacja/Konfiguracja
- runkit Funkcje
- Runkit_Sandbox — Runkit Sandbox Class -- PHP Virtual Machine
- Runkit_Sandbox_Parent — Runkit Anti-Sandbox Class
- runkit_class_adopt — Convert a base class to an inherited class, add ancestral methods when appropriate
- runkit_class_emancipate — Convert an inherited class to a base class, removes any method whose scope is ancestral
- runkit_constant_add — Similar to define(), but allows defining in class definitions as well
- runkit_constant_redefine — Redefine an already defined constant
- runkit_constant_remove — Remove/Delete an already defined constant
- runkit_function_add — Add a new function, similar to create_function
- runkit_function_copy — Copy a function to a new function name
- runkit_function_redefine — Replace a function definition with a new implementation
- runkit_function_remove — Remove a function definition
- runkit_function_rename — Change a function's name
- runkit_import — Process a PHP file importing function and class definitions, overwriting where appropriate
- runkit_lint_file — Check the PHP syntax of the specified file
- runkit_lint — Check the PHP syntax of the specified php code
- runkit_method_add — Dynamically adds a new method to a given class
- runkit_method_copy — Copies a method from class to another
- runkit_method_redefine — Dynamically changes the code of the given method
- runkit_method_remove — Dynamically removes the given method
- runkit_method_rename — Dynamically changes the name of the given method
- runkit_return_value_used — Determines if the current functions return value will be used
- runkit_sandbox_output_handler — Specify a function to capture and/or process output from a runkit sandbox
- runkit_superglobals — Return numerically indexed array of registered superglobals
Break the silence operator
Wstęp
The scream extension gives the possibility to disable the silencing error control operator so all errors are being reported. This feature is controlled by an ini setting.
Instalacja/Konfiguracja
Spis treści
Wymagania
PHP version 5.2.0 or greater.
Instalacja
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/scream
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Changelog |
|---|---|---|---|
| scream.enabled | Off | PHP_INI_ALL |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
scream.enabledint -
Whether or not to enable scream.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Przykłady
Spis treści
Example that shows the effect of scream
This example demonstrates how scream affects the behaviour of PHP's error handler.
Przykład #1 Enabling and disabling scream at runtime
<?php
// Make sure errors will be shown
ini_set('display_errors', true);
error_reporting(E_ALL);
// Disable scream - this is the default and produce an error
ini_set('scream.enabled', false);
echo "Opening http://example.com/not-existing-file\n";
@fopen('http://example.com/not-existing-file', 'r');
// Now enable scream and try again
ini_set('scream.enabled', true);
echo "Opening http://example.com/not-existing-file\n";
@fopen('http://example.com/another-not-existing-file', 'r');
?>
Powyższy przykład wyświetli coś podobnego do:
Opening http://example.com/not-existing-file Opening http://example.com/not-existing-file Warning: fopen(http://example.com/another-not-existing-file): failed to open stream: HTTP request failed! HTTP/1.1 404 Not Found in example.php on line 14
Informacja: Usually one would set this in the php.ini configuration file instead of changing the code.
Weak References
Wstęp
Weak references provide a non-intrusive gateway to ephemeral objects. Unlike normal (strong) references, weak references do not prevent the garbage collector from freeing that object. For this reason, an object may be destroyed even though a weak reference to that object still exists. In such conditions, the weak reference seamlessly becomes invalid.
Przykład #1 Weakref usage example
<?php
class MyClass {
public function __destruct() {
echo "Destroying object!\n";
}
}
$o1 = new MyClass;
$r1 = new Weakref($o1);
if ($r1->valid()) {
echo "Object still exists!\n";
var_dump($r1->get());
} else {
echo "Object is dead!\n";
}
unset($o1);
if ($r1->valid()) {
echo "Object still exists!\n";
var_dump($r1->get());
} else {
echo "Object is dead!\n";
}
?>
Powyższy przykład wyświetli:
Object still exists!
object(MyClass)#1 (0) {
}
Destroying object!
Object is dead!
Instalacja/Konfiguracja
Spis treści
Wymagania
Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.
Instalacja
To rozszerzenie » PECL nie jest dołączane do PHP.
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/weakref.
DLL z tym rozszerzeniem PECL można pobrać zarówno ze strony » PHP Downloads lub z » http://pecl4win.php.net/
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
The Weakref class
(No version information available, might only be in SVN)
Wstęp
The Weakref class provides a gateway to objects without preventing the garbage collector from freeing those objects. It also provides a way to turn a weak reference into a strong one.
Krótki opis klasy
Przykłady
Przykład #1 Weakref usage example
<?php
class MyClass {
public function __destruct() {
echo "Destroying object!\n";
}
}
$o1 = new MyClass;
$r1 = new Weakref($o1);
if ($r1->valid()) {
echo "Object still exists!\n";
var_dump($r1->get());
} else {
echo "Object is dead!\n";
}
unset($o1);
if ($r1->valid()) {
echo "Object still exists!\n";
var_dump($r1->get());
} else {
echo "Object is dead!\n";
}
?>
Powyższy przykład wyświetli:
Object still exists!
object(MyClass)#1 (0) {
}
Destroying object!
Object is dead!
Weakref::acquire
(No version information available, might only be in SVN)
Weakref::acquire — Acquires a strong reference on that object
Opis
Acquires a strong reference on that object, virtually turning the weak reference into a strong one.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns TRUE if the reference was valid and could be turned into a strong
reference, FALSE otherwise.
Przykłady
Przykład #1 Weakref::acquire() example
<?php
class MyClass {
public function __destruct() {
echo "Destroying object!\n";
}
}
$o1 = new MyClass;
$r1 = new Weakref($o1);
$r1->acquire();
echo "Unsetting o1...\n";
unset($o1);
$o2 = $r1->get();
$r1->release();
echo "Unsetting o2...\n";
unset($o2);
?>
Powyższy przykład wyświetli:
Unsetting o1... Unsetting o2... Destroying object!
Przykład #2 Nested acquire/release example
<?php
class MyClass {
public function __destruct() {
echo "Destroying object!\n";
}
}
$o1 = new MyClass;
$r1 = new Weakref($o1);
echo "Acquiring...\n";
$r1->acquire();
echo " Unsetting...\n";
unset($o1);
echo " Acquiring...\n";
$r1->acquire();
echo " Acquiring...\n";
$r1->acquire();
echo " Releasing...\n";
$r1->release();
echo " Releasing...\n";
$r1->release();
echo "Releasing...\n";
$r1->release();
?>
Powyższy przykład wyświetli:
Acquiring...
Unsetting...
Acquiring...
Acquiring...
Releasing...
Releasing...
Releasing...
Destroying object!
Weakref::__construct
(No version information available, might only be in SVN)
Weakref::__construct — Constructs a new weak reference
Opis
$object
] )Constructs a new weak reference.
Parametry
-
object -
The object to reference.
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 Weakref::__construct() example
<?php
class MyClass {
public function __destruct() {
echo "Destroying object!\n";
}
}
$o1 = new MyClass;
$r1 = new Weakref($o1);
if ($r1->valid()) {
echo "Object still exists!\n";
var_dump($r1->get());
} else {
echo "Object is dead!\n";
}
unset($o1);
if ($r1->valid()) {
echo "Object still exists!\n";
var_dump($r1->get());
} else {
echo "Object is dead!\n";
}
?>
Powyższy przykład wyświetli:
Object still exists!
object(MyClass)#1 (0) {
}
Destroying object!
Object is dead!
Weakref::get
(No version information available, might only be in SVN)
Weakref::get — Returns the object pointed to by the weak reference
Opis
Returns the object pointed to by the weak reference.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the object if the reference is still valid, NULL otherwise.
Weakref::release
(No version information available, might only be in SVN)
Weakref::release — Releases a previously acquired reference
Opis
Releases a previously acquired reference. Potentially turning a strong reference back into a weak reference.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns TRUE if the reference was previously acquired and thus could be
released, FALSE otherwise.
Przykłady
Przykład #1 Weakref::release() example
<?php
class MyClass {
public function __destruct() {
echo "Destroying object!\n";
}
}
$o1 = new MyClass;
$r1 = new Weakref($o1);
$r1->acquire();
echo "Unsetting o1...\n";
unset($o1);
$o2 = $r1->get();
$r1->release();
echo "Unsetting o2...\n";
unset($o2);
?>
Powyższy przykład wyświetli:
Unsetting o1... Unsetting o2... Destroying object!
Weakref::valid
(No version information available, might only be in SVN)
Weakref::valid — Checks whether the object referenced still exists
Opis
Checks whether the object referenced still exists.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns TRUE if the object still exists and is thus still accessible via
Weakref::get(), FALSE otherwise.
Spis treści
- Weakref::acquire — Acquires a strong reference on that object
- Weakref::__construct — Constructs a new weak reference
- Weakref::get — Returns the object pointed to by the weak reference
- Weakref::release — Releases a previously acquired reference
- Weakref::valid — Checks whether the object referenced still exists
- Wstęp
- Instalacja/Konfiguracja
- Weakref — The Weakref class
- Weakref::acquire — Acquires a strong reference on that object
- Weakref::__construct — Constructs a new weak reference
- Weakref::get — Returns the object pointed to by the weak reference
- Weakref::release — Releases a previously acquired reference
- Weakref::valid — Checks whether the object referenced still exists
Windows Cache for PHP
Wstęp
Windows Cache Extension for PHP is a PHP accelerator that is used to increase the speed of PHP applications running on Windows and Windows Server. Once the Windows Cache Extension for PHP is enabled and loaded by the PHP engine, PHP applications can take advantage of the functionality without any code modifications.
The Windows Cache Extension includes 5 different types of caches. The following describes the purpose of each cache type and the benefits it provides.
-
PHP Opcode Cache - PHP is a script processing engine, which reads an input stream of data that contains text and/or PHP instructions and produces another stream of data, most commonly in the HTML format. This means that on a web server the PHP engine reads, parses, compiles and executes a PHP script each time that it is requested by a Web client. The reading, parsing and compilation operations put additional load on the web server's CPU and file system and thus affect the overall performance of a PHP web application. The PHP bytecode (opcode) cache is used to store the compiled script bytecode in shared memory so that it can be re-used by PHP engine for subsequent executions of the same script.
-
File Cache - Even with the PHP opcode cache enabled, the PHP engine has to accesses the script files on a file system. When PHP scripts are stored on a remote UNC file share, the file operations introduce a significant performance overhead. The Windows Cache Extension for PHP includes a file cache that is used to store the content of the PHP script files in shared memory, which reduces the amount of file system operations performed by PHP engine.
-
Resolve File Path Cache - PHP scripts very often include or operate with files by using relative file paths. Every file path has to be normalized to an absolute file path by the PHP engine. When a PHP application uses many PHP files and accesses them by relative paths, the operation of resolving the paths may negatively impact the application's performance. The Windows Cache Extension for PHP provides a Resolve File Path cache, which is used to store the mappings between relative and absolute file paths, thereby reducing the number of path resolutions that the PHP engine has to perform.
-
User Cache (available since version 1.1.0) - PHP scripts can take advantage of the shared memory cache by using the user cache API's. PHP objects and variables can be stored in the user cache and then re-used on subsequent requests. This can be used to improve performance of PHP scripts and to share the data across multiple PHP processes.
-
Session Handler (available since version 1.1.0) - The WinCache session handler can be used to store the PHP session data in the shared memory cache. This avoids file system operations for reading and writing session data, which improves performance when large amount of data is stored in PHP session.
Instalacja/Konfiguracja
Spis treści
- Wymagania
- Instalacja
- Konfiguracja wykonawcza
- WinCache Statistics Script
- WinCache Session Handler
- WinCache Functions Reroutes
- Typy zasobów
Wymagania
The extension is currently supported only on the following configurations:
Windows OS:
- Windows XP SP3 with IIS 5.1 and » FastCGI Extension
- Windows Server 2003 with IIS 6.0 and » FastCGI Extension
- Windows Vista SP1 with IIS 7.0 and FastCGI Module
- Windows Server 2008 with IIS 7.0 and FastCGI Module
- Windows 7 with IIS 7.5 and FastCGI Module
- Windows Server 2008 R2 with IIS 7.5 and FastCGI Module
PHP:
- PHP 5.2.X, Non-thread-safe build
- PHP 5.3 X86, Non-thread-safe VC9 build
Informacja: The WinCache Extension can only be used when IIS is configured to run PHP via FastCGI.
Instalacja
To rozszerzenie » PECL nie jest dołączane do PHP.
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/wincache.
There are two packages for this extension: one package is for PHP versions 5.2.X, and the other package is for PHP 5.3.X. Select the package that is appropriate for the PHP version being used.
To install and enable the extension, follow these steps:
-
Unpack the package into some temporary location.
-
Copy the php_wincache.dll file into the PHP extensions folder. Typically this folder is called "ext" and it is located in the same folder with all PHP binary files. For example: C:\Program Files\PHP\ext.
-
Using a text editor, open the php.ini file, which is usually located in the same folder where all PHP binary files are. For example: C:\Program Files\PHP\php.ini.
-
Add the following line at the end of the php.ini file: extension = php_wincache.dll.
-
Save and close the php.ini file.
-
Recycle the IIS Application Pools for PHP to pick up the configuration changes. To check that the extension has been enabled, create a file called phpinfo.php with a PHP code that calls phpinfo function.
-
Save the phpinfo.php file in the root folder of a IIS web site that uses PHP, then open a browser and make a request to http://localhost/phpinfo.php. Search within the returned web page for a section called wincache. If the extension is enabled, then the phpinfo output will list the configuration settings provided by the WinCache.
Informacja: Do not forget to remove phpinfo.php file from the web site's root folder after verifying that extension has been enabled.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
The following table lists and explains the configuration settings provided by the WinCache extension:
| Nazwa | Domyślnie | Minimum | Maximum | Możliwość zmian | Rejestr zmian |
|---|---|---|---|---|---|
| wincache.fcenabled | "1" | "0" | "1" | PHP_INI_ALL | Available since WinCache 1.0.0 |
| wincache.fcenabledfilter | "NULL" | "NULL" | "NULL" | PHP_INI_SYSTEM | Available since WinCache 1.0.0 |
| wincache.fcachesize | "24" | "5" | "255" | PHP_INI_SYSTEM | Available since WinCache 1.0.0 |
| wincache.fcndetect | "1" | "0" | "1" | PHP_INI_SYSTEM | Available since WinCache 1.1.0 |
| wincache.maxfilesize | "256" | "10" | "2048" | PHP_INI_SYSTEM | Available since WinCache 1.0.0 |
| wincache.ocenabled | "1" | "0" | "1" | PHP_INI_ALL | Available since WinCache 1.0.0 |
| wincache.ocenabledfilter | "NULL" | "NULL" | "NULL" | PHP_INI_SYSTEM | Available since WinCache 1.0.0 |
| wincache.ocachesize | "96" | "15" | "255" | PHP_INI_SYSTEM | Available since WinCache 1.0.0 |
| wincache.filecount | "4096" | "1024" | "16384" | PHP_INI_SYSTEM | Available since WinCache 1.0.0 |
| wincache.chkinterval | "30" | "0" | "300" | PHP_INI_SYSTEM | Available since WinCache 1.0.0 |
| wincache.ttlmax | "1200" | "0" | "7200" | PHP_INI_SYSTEM | Available since WinCache 1.0.0 |
| wincache.enablecli | 0 | 0 | 1 | PHP_INI_SYSTEM | Available since WinCache 1.0.0 |
| wincache.ignorelist | NULL | NULL | NULL | PHP_INI_ALL | Available since WinCache 1.0.0 |
| wincache.namesalt | NULL | NULL | NULL | PHP_INI_SYSTEM | Available since WinCache 1.0.0 |
| wincache.ucenabled | 1 | 0 | 1 | PHP_INI_SYSTEM | Available since WinCache 1.1.0 |
| wincache.ucachesize | 8 | 5 | 85 | PHP_INI_SYSTEM | Available since WinCache 1.1.0 |
| wincache.scachesize | 8 | 5 | 85 | PHP_INI_SYSTEM | Available since WinCache 1.1.0 |
| wincache.rerouteini | NULL | NULL | NULL | PHP_INI_SYSTEM | Available since WinCache 1.2.0 |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
wincache.fcenabledboolean - Enables or disables the file cache functionality.
-
wincache.fcenabledfilterstring - Defines a comma-separated list of IIS web site identifiers where file cache should be enabled or disabled. This setting works in conjunction with wincache.fcenabled: if wincache.fcenabled is set to 1, then the sites listed in the wincache.fcenabledfilter will have the file cache turned off; if wincache.fcenabled is set to 0, then the sites listed in the wincache.fcenabledfilter will have the file cache turned on.
-
wincache.fcachesizeinteger - Defines the maximum memory size (in megabytes) that is allocated for the file cache. If the total size of all the cached files exceeds the value specified in this setting, then most stale files will be removed from the file cache.
-
wincache.fcndetectboolean - Enables or disables the file change notification detection functionality. If file change notification is supported then it will be used to refresh the opcode and file cache entries as soon as the corresponding files are modified on a file system. If file change notification is not supported, for example when using network file shares, then wincache will poll for file changes at regular time intervals specified by wincache.chkinterval.
-
wincache.maxfilesizeinteger - Defines the maximum allowed size (in kilobytes) for a single file to be cached. If a file size exceeds the specified value, the file will not be cached. This setting applies to the file cache only.
-
wincache.ocenabledboolean - Enables or disables the opcode cache functionality
-
wincache.ocenabledfilterstring - Defines a comma-separated list of IIS web site identifiers where opcode cache should be enabled or disabled. This setting works in conjunction with wincache.ocenabled: if wincache.ocenabled is set to 1, then the sites listed in the wincache.ocenabledfilter will have the opcode cache turned off; if wincache.ocenabled is set to 0, then the sites listed in the wincache.ocenabledfilter will have the opcode cache turned on.
-
wincache.ocachesizeinteger - Defines the maximum memory size (in megabytes) that is allocated for the opcode cache. If the cached opcode size exceeds the specified value, then most stale opcode will be removed from the cache. Note that the opcode cache size must be at least 3 times bigger than file cache size. If that is not the case the opcode cache size will be automatically increased.
-
wincache.filecountinteger - Defines how many files are expected to be cached by the extension, so that appropriate memory size is allocated at the startup time. If the number of files exceeds the specified value, the WinCache will re-allocate more memory as needed.
-
wincache.chkintervalinteger - Defines how often (in seconds) the extension checks for file changes in order to refresh the cache. Setting it to 0 will disable the refreshing of the cache. The file changes will not be reflected in the cache unless the cache entry for that file is removed by scavenger or IIS application pool is recycled or wincache_refresh_if_changed function is called.
-
wincache.ttlmaxinteger - Defines the maximum time to live (in seconds) for a cached entry without being used. Setting it to 0 will disable the cache scavenger, so the cached entries will never be removed from the cache during the lifetime of the IIS worker process.
-
wincache.enablecliboolean - Defines if caching is enabled when PHP is running in command line (CLI) mode.
-
wincache.ignoreliststring -
Defines a list of files that should not be cached by the extension. The files list is specified by using file names only, separated by the pipe symbol - "|".
Przykład #1 wincache.ignorelist example
wincache.ignorelist = "index.php|misc.php|admin.php"
-
wincache.namesaltstring - Defines a string that will be used when naming the extension specific objects that are stored in shared memory. This is used to avoid conflicts that may be caused if other applications within an IIS worker process tries to access shared memory. The length of the namesalt string cannot exceed 8 characters.
-
wincache.ucenabledboolean - Enables or disables the user cache functionality.
-
wincache.ucachesizeinteger - Defines the maximum memory size in megabytes that is allocated for the user cache. If the total size of variables stored in the user cache exceeds the specified value, then the most stale variables will be removed from the cache.
-
wincache.scachesizeinteger - Defines the maximum memory size in megabytes that is allocated for the session cache. If the total size of data stored in the session cache exceeds the specified value, then the most stale data will be removed from the cache.
-
wincache.rerouteinistring - Specifies an absolute or a relateve path to the reroute.ini file that contains the list of PHP functions whose implementation should be replaced with the WinCache function equivalents. If a relative path is specified then it is assumed to be relative to the location of php-cgi.exe file.
WinCache Statistics Script
The installation package for WinCache includes a PHP script, wincache.php, that can be used to obtain cache information and statistics.
If the WinCache extension was installed via the Microsoft Web Platform Installer, then this script is located in %SystemDrive%\Program Files\IIS\Windows Cache for PHP\. On a 64-bit version of the Windows Server operating system, the script is located in %SystemDrive%\Program Files (x86)\IIS\Windows Cache for PHP. If the extension was installed manually, then the wincache.php will be located in the same folder from which the content of the installation package was extracted.
To use wincache.php, copy it into a root folder of a Web site or into any subfolder. To protect the script, open it in any text editor and replace the values for USERNAME and PASSWORD constants. If any other IIS authentication is enabled on the server, then follow the instructions in the comments:
Przykład #1 Authentication configuration for wincache.php
<?php
/**
* ======================== CONFIGURATION SETTINGS ==============================
* If you do not want to use authentication for this page, set USE_AUTHENTICATION to 0.
* If you use authentication then replace the default password.
*/
define('USE_AUTHENTICATION', 1);
define('USERNAME', 'wincache');
define('PASSWORD', 'wincache');
/**
* The Basic PHP authentication will work only when IIS is configured to support
* Anonymous Authentication' and nothing else. If IIS is configured to support/use
* any other kind of authentication like Basic/Negotiate/Digest etc, this will not work.
* In that case use the array below to define the names of users in your
* domain/network/workgroup which you want to grant access to.
*/
$user_allowed = array('DOMAIN\user1', 'DOMAIN\user2', 'DOMAIN\user3');
/**
* If the array contains string 'all', then all the users authenticated by IIS
* will have access to the page. Uncomment the below line and comment above line
* to grant access to all users who gets authenticated by IIS.
*/
/* $user_allowed = array('all'); */
/** ===================== END OF CONFIGURATION SETTINGS ========================== */
?>
Informacja: Always protect the wincache.php script by using either the built-in authentication or the server's authentication mechanism. Leaving this script unprotected may compromise the security of your web application and web server.
WinCache Session Handler
The WinCache session handler (available since WinCache 1.1.0) can be used to configure PHP to store the session data in shared memory session cache. Using shared memory instead of the default file session storage helps improve performance of PHP applications that store large amount of data in session objects. Wincache session cache uses file-backed shared memory, which ensures that the session data is not lost during recycling of IIS application pools.
To configure PHP to use WinCache session handler set the php.ini setting session.save_handler to wincache. By default the Windows temporary file location is used for storing the session data. To change the location of the session file use session.save_path directive.
Przykład #1 Enabling WinCache session handler
session.save_handler = wincache session.save_path = C:\inetpub\temp\session\
WinCache Functions Reroutes
The WinCache functions reroutes (available since WinCache 1.2.0) can be used to replace built-in PHP functions with their equivalents that are optimized for a particular purpose. WinCache extension includes Windows-optimized implementation of PHP file functions that may improve performance of PHP applications in cases when PHP has to access files on network shares. The optimized implementation is provided for the following functions:
To configure WinCache to use the functions reroutes use the file reroute.ini that is included in WinCache installation package. Copy this file into the same directory where php.ini file is located. After that add the wincache.rerouteini setting in php.ini and specify an absolute or relative path to the reroute.ini file.
Przykład #1 Enabling WinCache functions reroutes
wincache.rerouteini = C:\PHP\reroute.ini
Informacja: If WinCache functions reroutes are enabled it is recommended to increase the WinCache file cache size. This can be done by using wincache.fcachesize setting.
The reroute.ini file contains the mappings between the native PHP functions and their equivalents in WinCache. Each line in the file defines a mapping by using the following syntax:
<PHP function name>:[<number of function parameters>]=<wincache function name>
The example of the file is shown below. In this example the calls to PHP function file_get_contents() will be replaced with calls to wincache_file_get_contents() only if the number of parameters passed to the function is less than or equals to 2. Specifying the number of parameters is useful when replacement function does not handle all the function's parameters.
Przykład #2 Reroute.ini file content
[FunctionRerouteList] file_exists=wincache_file_exists file_get_contents:2=wincache_file_get_contents readfile:2=wincache_readfile is_readable=wincache_is_readable is_writable=wincache_is_writable is_writeable=wincache_is_writable is_file=wincache_is_file is_dir=wincache_is_dir realpath=wincache_realpath filesize=wincache_filesize
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
To rozszerzenie nie posiada żadnych stałych.
WinCache Funkcje
wincache_fcache_fileinfo
(PECL wincache >= 1.0.0)
wincache_fcache_fileinfo — Retrieves information about files cached in the file cache
Opis
$summaryonly = false
] )Retrieves information about file cache content and its usage.
Parametry
-
summaryonly -
Controls whether the returned array will contain information about individual cache entries along with the file cache summary.
Zwracane wartości
Array of meta data about file cache lub FALSE w przypadku niepowodzenia
The array returned by this function contains the following elements:
- total_cache_uptime - total time in seconds that the file cache has been active
- total_file_count - total number of files that are currently in the file cache
- total_hit_count - number of times the files have been served from the file cache
- total_miss_count - number of times the files have not been found in the file cache
-
file_entries - an array that contains the information about all the cached files:
- file_name - absolute file name of the cached file
- add_time - time in seconds since the file has been added to the file cache
- use_time - time in seconds since the file has been accessed in the file cache
- last_check - time in seconds since the file has been checked for modifications
- hit_count - number of times the file has been served from the cache
- file_size - size of the cached file in bytes
Przykłady
Przykład #1 A wincache_fcache_fileinfo() example
<pre>
<?php
print_r(wincache_fcache_fileinfo());
?>
</pre>
Powyższy przykład wyświetli:
Array
( [total_cache_uptime] => 3234
[total_file_count] => 5
[total_hit_count] => 0
[total_miss_count] => 1
[file_entries] => Array
(
[1] => Array
(
[file_name] => c:\inetpub\wwwroot\checkcache.php
[add_time] => 1
[use_time] => 0
[last_check] => 1
[hit_count] => 1
[file_size] => 2435
)
[2] => Array (...iterates for each cached file)
)
)
Zobacz też:
- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_ocache_fileinfo() - Retrieves information about files cached in the opcode cache
- wincache_ocache_meminfo() - Retrieves information about opcode cache memory usage
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache
- wincache_scache_meminfo() - Retrieves information about session cache memory usage
wincache_fcache_meminfo
(PECL wincache >= 1.0.0)
wincache_fcache_meminfo — Retrieves information about file cache memory usage
Opis
Retrieves information about memory usage by file cache.
Zwracane wartości
Array of meta data about file cache memory usage lub FALSE w przypadku niepowodzenia
The array returned by this function contains the following elements:
- memory_total - amount of memory in bytes allocated for the file cache
- memory_free - amount of free memory in bytes available for the file cache
- num_used_blks - number of memory blocks used by the file cache
- num_free_blks - number of free memory blocks available for the file cache
- memory_overhead - amount of memory in bytes used for the file cache internal structures
Przykłady
Przykład #1 A wincache_fcache_meminfo() example
<pre>
<?php
print_r(wincache_fcache_meminfo());
?>
</pre>
Powyższy przykład wyświetli:
Array
(
[memory_total] => 134217728
[memory_free] => 131339120
[num_used_blks] => 361
[num_free_blks] => 3
[memory_overhead] => 5856
)
Zobacz też:
- wincache_fcache_fileinfo() - Retrieves information about files cached in the file cache
- wincache_ocache_fileinfo() - Retrieves information about files cached in the opcode cache
- wincache_ocache_meminfo() - Retrieves information about opcode cache memory usage
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache
- wincache_scache_meminfo() - Retrieves information about session cache memory usage
wincache_lock
(PECL wincache >= 1.1.0)
wincache_lock — Acquires an exclusive lock on a given key
Opis
$key
[, bool $isglobal = false
] )Obtains an exclusive lock on a given key. The execution of the current script will be blocked until the lock can be obtained. Once the lock is obtained, the other scripts that try to request the lock by using the same key will be blocked, until the current script releases the lock by using wincache_unlock().
Using of the wincache_lock() and wincache_unlock() can cause deadlocks when executing PHP scripts in a multi-process environment like FastCGI. Do not use these functions unless you are absolutely sure you need to use them. For the majority of the operations on the user cache it is not necessary to use these functions.
Parametry
-
key -
Name of the key in the cache to get the lock on.
-
isglobal -
Controls whether the scope of the lock is system-wide or local. Local locks are scoped to the application pool in IIS FastCGI case or to all php processes that have the same parent process identifier.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Using wincache_lock()
<?php
$fp = fopen("/tmp/lock.txt", "r+");
if (wincache_lock(“lock_txt_lock”)) { // do an exclusive lock
ftruncate($fp, 0); // truncate file
fwrite($fp, "Write something here\n");
wincache_unlock(“lock_txt_lock”); // release the lock
} else {
echo "Couldn't get the lock!";
}
fclose($fp);
?>
Zobacz też:
- wincache_unlock() - Releases an exclusive lock on a given key
- wincache_ucache_set() - Adds a variable in user cache and overwrites a variable if it already exists in the cache
- wincache_ucache_get() - Gets a variable stored in the user cache
- wincache_ucache_delete() - Deletes variables from the user cache
- wincache_ucache_clear() - Deletes entire content of the user cache
- wincache_ucache_exists() - Checks if a variable exists in the user cache
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache
wincache_ocache_fileinfo
(PECL wincache >= 1.0.0)
wincache_ocache_fileinfo — Retrieves information about files cached in the opcode cache
Opis
$summaryonly = false
] )Retrieves information about opcode cache content and its usage.
Parametry
-
summaryonly -
Controls whether the returned array will contain information about individual cache entries along with the opcode cache summary.
Zwracane wartości
Array of meta data about opcode cache lub FALSE w przypadku niepowodzenia
The array returned by this function contains the following elements:
- total_cache_uptime - total time in seconds that the opcode cache has been active
- total_file_count - total number of files that are currently in the opcode cache
- total_hit_count - number of times the compiled opcode have been served from the cache
- total_miss_count - number of times the compiled opcode have not been found in the cache
- is_local_cache - true is the cache metadata is for a local cache instance, false if the metadata is for the global cache
-
file_entries - an array that contains the information about all the cached files:
- file_name - absolute file name of the cached file
- add_time - time in seconds since the file has been added to the opcode cache
- use_time - time in seconds since the file has been accessed in the opcode cache
- last_check - time in seconds since the file has been checked for modifications
- hit_count - number of times the file has been served from the cache
- function_count - number of functions in the cached file
- class_count - number of classes in the cached file
Przykłady
Przykład #1 A wincache_ocache_fileinfo() example
<pre>
<?php
print_r(wincache_ocache_fileinfo());
?>
</pre>
Powyższy przykład wyświetli:
Array
(
[total_cache_uptime] => 17357
[total_file_count] => 121
[total_hit_count] => 36562
[total_miss_count] => 201
[file_entries] => Array
(
[1] => Array
(
[file_name] => c:\inetpub\wwwroot\checkcache.php
[add_time] => 17356
[use_time] => 7
[last_check] => 10
[hit_count] => 454
[function_count] => 0
[class_count] => 1
)
[2] => Array (...iterates for each cached file)
)
)
Zobacz też:
- wincache_fcache_fileinfo() - Retrieves information about files cached in the file cache
- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_ocache_meminfo() - Retrieves information about opcode cache memory usage
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache
- wincache_scache_meminfo() - Retrieves information about session cache memory usage
wincache_ocache_meminfo
(PECL wincache >= 1.0.0)
wincache_ocache_meminfo — Retrieves information about opcode cache memory usage
Opis
Retrieves information about memory usage by opcode cache.
Zwracane wartości
Array of meta data about opcode cache memory usage lub FALSE w przypadku niepowodzenia
The array returned by this function contains the following elements:
- memory_total - amount of memory in bytes allocated for the opcode cache
- memory_free - amount of free memory in bytes available for the opcode cache
- num_used_blks - number of memory blocks used by the opcode cache
- num_free_blks - number of free memory blocks available for the opcode cache
- memory_overhead - amount of memory in bytes used for the opcode cache internal structures
Przykłady
Przykład #1 A wincache_ocache_meminfo() example
<pre>
<?php
print_r(wincache_ocache_meminfo());
?>
</pre>
Powyższy przykład wyświetli:
Array
(
[memory_total] => 134217728
[memory_free] => 112106972
[num_used_blks] => 15469
[num_free_blks] => 4
[memory_overhead] => 247600
)
Zobacz też:
- wincache_fcache_fileinfo() - Retrieves information about files cached in the file cache
- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_ocache_fileinfo() - Retrieves information about files cached in the opcode cache
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache
- wincache_scache_meminfo() - Retrieves information about session cache memory usage
wincache_refresh_if_changed
(PECL wincache >= 1.0.0)
wincache_refresh_if_changed — Refreshes the cache entries for the cached files
Opis
$files
] )Refreshes the cache entries for the files, whose names were passed in the input argument. If no argument is specified then refreshes all the entries in the cache.
Parametry
-
files -
An array of file names for files that need to be refreshed. An absolute or relative file paths can be used.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
WinCache performs regular checks on the cached files to ensure that if any file has changed then the corresponding entry in the cache is updated. By default this check is performed every 30 seconds. If, for example, a PHP script updates another PHP script where the application's configuration settings are stored, then it may happen that after the configuration settings have been saved to a file, the application is still using old settings for some time until the cache is refreshed. In those cases it may be preferrable to refresh the cache right after the file has been changed. The following example shows how this can be done.
Przykład #1 A wincache_refresh_if_changed() example
<?php
$filename = 'C:\inetpub\wwwroot\config.php';
$handle = fopen($filename, 'w+');
if ($handle === FALSE) die('Failed to open file '.$filename.' for writing');
fwrite($handle, '<?php $setting=something; ?>');
fclose($handle);
wincache_refresh_if_changed(array($filename));
?>
Zobacz też:
- wincache_fcache_fileinfo() - Retrieves information about files cached in the file cache
- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_ocache_fileinfo() - Retrieves information about files cached in the opcode cache
- wincache_ocache_meminfo() - Retrieves information about opcode cache memory usage
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
wincache_rplist_fileinfo
(PECL wincache >= 1.0.0)
wincache_rplist_fileinfo — Retrieves information about resolve file path cache
Opis
$summaryonly = false
] )Retrieves information about cached mappings between relative file paths and corresponding absolute file paths.
Zwracane wartości
Array of meta data about the resolve file path cache lub FALSE w przypadku niepowodzenia
The array returned by this function contains the following elements:
- total_file_count - total number of file path mappings stored in the cache
-
rplist_entries - an array that contains the information about all the cached file paths:
- resolve_path - path to a file
- subkey_data - corresponding absolute path to a file
Przykłady
Przykład #1 A wincache_rplist_fileinfo() example
<pre>
<?php
print_r(wincache_rplist_fileinfo());
?>
</pre>
Powyższy przykład wyświetli:
Array
(
[total_file_count] => 5
[rplist_entries] => Array
(
[1] => Array
(
[resolve_path] => checkcache.php
[subkey_data] => c:\inetpub\wwwroot|c:\inetpub\wwwroot\checkcache.php
)
[2] => Array (...iterates for each cached file)
)
)
Zobacz też:
- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_fcache_fileinfo() - Retrieves information about files cached in the file cache
- wincache_ocache_fileinfo() - Retrieves information about files cached in the opcode cache
- wincache_ocache_meminfo() - Retrieves information about opcode cache memory usage
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache
- wincache_scache_meminfo() - Retrieves information about session cache memory usage
wincache_rplist_meminfo
(PECL wincache >= 1.0.0)
wincache_rplist_meminfo — Retrieves information about memory usage by the resolve file path cache
Opis
Retrieves information about memory usage by resolve file path cache.
Zwracane wartości
Array of meta data that describes memory usage by resolve file path cache. lub FALSE w przypadku niepowodzenia
The array returned by this function contains the following elements:
- memory_total - amount of memory in bytes allocated for the resolve file path cache
- memory_free - amount of free memory in bytes available for the resolve file path cache
- num_used_blks - number of memory blocks used by the resolve file path cache
- num_free_blks - number of free memory blocks available for the resolve file path cache
- memory_overhead - amount of memory in bytes used for the internal structures of resolve file path cache
Przykłady
Przykład #1 A wincache_rplist_meminfo() example
<pre>
<?php
print_r(wincache_rplist_meminfo());
?>
</pre>
Powyższy przykład wyświetli:
Array
(
[memory_total] => 9437184
[memory_free] => 9416744
[num_used_blks] => 23
[num_free_blks] => 1
[memory_overhead] => 416
)
Zobacz też:
- wincache_fcache_fileinfo() - Retrieves information about files cached in the file cache
- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_ocache_fileinfo() - Retrieves information about files cached in the opcode cache
- wincache_ocache_meminfo() - Retrieves information about opcode cache memory usage
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache
- wincache_scache_meminfo() - Retrieves information about session cache memory usage
wincache_scache_info
(PECL wincache >= 1.1.0)
wincache_scache_info — Retrieves information about files cached in the session cache
Opis
$summaryonly = false
] )Retrieves information about session cache content and its usage.
Parametry
-
summaryonly -
Controls whether the returned array will contain information about individual cache entries along with the session cache summary.
Zwracane wartości
Array of meta data about session cache lub FALSE w przypadku niepowodzenia
The array returned by this function contains the following elements:
- total_cache_uptime - total time in seconds that the session cache has been active
- total_item_count - total number of elements that are currently in the session cache
- is_local_cache - true is the cache metadata is for a local cache instance, false if the metadata is for the global cache
- total_hit_count - number of times the data has been served from the cache
- total_miss_count - number of times the data has not been found in the cache
-
scache_entries - an array that contains the information about all the cached items:
- key_name - name of the key which is used to store the data
- value_type - type of value stored by the key
- use_time - time in seconds since the file has been accessed in the opcode cache
- last_check - time in seconds since the file has been checked for modifications
- ttl_seconds - time remaining for the data to live in the cache, 0 meaning infinite
- age_seconds - time elapsed from the time data has been added in the cache
- hitcount - number of times data has been served from the cache
Przykłady
Przykład #1 A wincache_scache_info() example
<pre>
<?php
print_r(wincache_scache_info());
?>
</pre>
Powyższy przykład wyświetli:
Array
(
[total_cache_uptime] => 17357
[total_file_count] => 121
[total_hit_count] => 36562
[total_miss_count] => 201
[scache_entries] => Array
(
[1] => Array
(
[file_name] => c:\inetpub\wwwroot\checkcache.php
[add_time] => 17356
[use_time] => 7
[last_check] => 10
[hit_count] => 454
[function_count] => 0
[class_count] => 1
)
[2] => Array (...iterates for each cached file)
)
)
Zobacz też:
- wincache_fcache_fileinfo() - Retrieves information about files cached in the file cache
- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_ocache_meminfo() - Retrieves information about opcode cache memory usage
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_meminfo() - Retrieves information about session cache memory usage
wincache_scache_meminfo
(PECL wincache >= 1.1.0)
wincache_scache_meminfo — Retrieves information about session cache memory usage
Opis
Retrieves information about memory usage by session cache.
Zwracane wartości
Array of meta data about session cache memory usage lub FALSE w przypadku niepowodzenia
The array returned by this function contains the following elements:
- memory_total - amount of memory in bytes allocated for the session cache
- memory_free - amount of free memory in bytes available for the session cache
- num_used_blks - number of memory blocks used by the session cache
- num_free_blks - number of free memory blocks available for the session cache
- memory_overhead - amount of memory in bytes used for the session cache internal structures
Przykłady
Przykład #1 A wincache_scache_meminfo() example
<pre>
<?php
print_r(wincache_scache_meminfo());
?>
</pre>
Powyższy przykład wyświetli:
Array
(
[memory_total] => 5242880
[memory_free] => 5215056
[num_used_blks] => 6
[num_free_blks] => 3
[memory_overhead] => 176
)
Zobacz też:
- wincache_fcache_fileinfo() - Retrieves information about files cached in the file cache
- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_ocache_fileinfo() - Retrieves information about files cached in the opcode cache
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache
wincache_ucache_add
(PECL wincache >= 1.1.0)
wincache_ucache_add — Adds a variable in user cache only if variable does not already exist in the cache
Opis
Adds a variable in user cache, only if this variable doesn't already exist in the cache. The added variable remains in the user cache unless its time to live expires or it is deleted by using wincache_ucache_delete() or wincache_ucache_clear() functions.
Parametry
-
key -
Store the variable using this
keyname. If a variable with same key is already present the function will fail and returnFALSE.keyis case sensitive. To override the value even ifkeyis present use wincache_ucache_set() function instad.keycan also take array of name => value pairs where names will be used as keys. This can be used to add multiple values in the cache in one operation, thus avoiding race condition. -
value -
Value of a variable to store.
Valuesupports all data types except resources, such as file handles. This paramter is ignored if first argument is an array. A general guidance is to passNULLasvaluewhile using array askey. Ifvalueis an object, or an array containing objects, then the objects will be serialized. See __sleep() for details on serializing objects. -
values -
Associative array of keys and values.
-
ttl -
Time for the variable to live in the cache in seconds. After the value specified in
ttlhas passed the stored variable will be deleted from the cache. This parameter takes a default value of 0 which means the variable will stay in the cache unless explicitly deleted by using wincache_ucache_delete() or wincache_ucache_clear() functions.
Zwracane wartości
If key is string, the function returns TRUE on success and FALSE on failure.
If key is an array, the function returns:
- If all the name => value pairs in the array can be set, function returns an empty array;
-
If all the name => value pairs in the array cannot be set, function returns
FALSE; - If some can be set while others cannot, function returns an array with name=>value pair for which the addition failed in the user cache.
Przykłady
Przykład #1 wincache_ucache_add() with key as a string
<?php
$bar = 'BAR';
var_dump(wincache_ucache_add('foo', $bar));
var_dump(wincache_ucache_add('foo', $bar));
var_dump(wincache_ucache_get('foo'));
?>
Powyższy przykład wyświetli:
bool(true) bool(false) string(3) "BAR"
Przykład #2 wincache_ucache_add() with key as an array
<?php
$colors_array = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
var_dump(wincache_ucache_add($colors_array));
var_dump(wincache_ucache_add($colors_array));
var_dump(wincache_ucache_get('Blue'));
?>
Powyższy przykład wyświetli:
array(0) { }
array(4) {
["green"]=> int(-1)
["Blue"]=> int(-1)
["yellow"]=> int(-1)
["cyan"]=> int(-1)
}
string(1) "6"
Zobacz też:
- wincache_ucache_set() - Adds a variable in user cache and overwrites a variable if it already exists in the cache
- wincache_ucache_get() - Gets a variable stored in the user cache
- wincache_ucache_delete() - Deletes variables from the user cache
- wincache_ucache_clear() - Deletes entire content of the user cache
- wincache_ucache_exists() - Checks if a variable exists in the user cache
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- __sleep()
wincache_ucache_cas
(PECL wincache >= 1.1.0)
wincache_ucache_cas — Compares the variable with old value and assigns new value to it
Opis
$key
, int $old_value
, int $new_value
)
Compares the variable associated with the key with old_value
and if it matches then assigns the new_value to it.
Parametry
-
key -
The
keythat is used to store the variable in the cache.keyis case sensitive. -
old_value -
Old value of the variable pointed by
keyin the user cache. The value should be of type long, otherwise the function returnsFALSE. -
new_value -
New value which will get assigned to variable pointer by
keyif a match is found. The value should be of type long, otherwise the function returnsFALSE.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Using wincache_ucache_cas()
<?php
wincache_ucache_set('counter', 2922);
var_dump(wincache_ucache_cas('counter', 2922, 1));
var_dump(wincache_ucache_get('counter'));
?>
Powyższy przykład wyświetli:
bool(true) int(1)
Zobacz też:
- wincache_ucache_inc() - Increments the value associated with the key
- wincache_ucache_dec() - Decrements the value associated with the key
wincache_ucache_clear
(PECL wincache >= 1.1.0)
wincache_ucache_clear — Deletes entire content of the user cache
Opis
Clears/deletes all the values stored in the user cache.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 using wincache_ucache_clear()
<?php
wincache_ucache_set('green', 1);
wincache_ucache_set('red', 2);
wincache_ucache_set('orange', 4);
wincache_ucache_set('blue', 8);
wincache_ucache_set('cyan', 16);
$array1 = array('green', 'red', 'orange', 'blue', 'cyan');
var_dump(wincache_ucache_get($array1));
var_dump(wincache_ucache_clear());
var_dump(wincache_ucache_get($array1));
?>
Powyższy przykład wyświetli:
array(5) { ["green"]=> int(1)
["red"]=> int(2)
["orange"]=> int(4)
["blue"]=> int(8)
["cyan"]=> int(16) }
bool(true)
bool(false)
Zobacz też:
- wincache_ucache_set() - Adds a variable in user cache and overwrites a variable if it already exists in the cache
- wincache_ucache_add() - Adds a variable in user cache only if variable does not already exist in the cache
- wincache_ucache_delete() - Deletes variables from the user cache
- wincache_ucache_get() - Gets a variable stored in the user cache
- wincache_ucache_exists() - Checks if a variable exists in the user cache
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
wincache_ucache_dec
(PECL wincache >= 1.1.0)
wincache_ucache_dec — Decrements the value associated with the key
Opis
Decrements the value associated with the key by 1 or as specified
by dec_by.
Parametry
-
key -
The
keythat was used to store the variable in the cache.keyis case sensitive. -
dec_by -
The value by which the variable associated with the
keywill get decremented. If the argument is a floating point number it will be truncated to nearest integer. The variable associated with thekeyshould be of type long, otherwise the function fails and returnsFALSE. -
success -
Will be set to
TRUEon success andFALSEon failure.
Zwracane wartości
Returns the decremented value on success and FALSE on failure.
Przykłady
Przykład #1 Using wincache_ucache_dec()
<?php
wincache_ucache_set('counter', 1);
var_dump(wincache_ucache_dec('counter', 2923, $success));
var_dump($success);
?>
Powyższy przykład wyświetli:
int(2922) bool(true)
Zobacz też:
- wincache_ucache_inc() - Increments the value associated with the key
- wincache_ucache_cas() - Compares the variable with old value and assigns new value to it
wincache_ucache_delete
(PECL wincache >= 1.1.0)
wincache_ucache_delete — Deletes variables from the user cache
Opis
Deletes the elements in the user cache pointed by key.
Parametry
-
key -
The
keythat was used to store the variable in the cache.keyis case sensitive.keycan be an array of keys.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
If key is an array then the function returns FALSE
if every element of the array fails to get deleted from the user cache, otherwise returns an
array which consists of all the keys that are deleted.
Przykłady
Przykład #1 Using wincache_ucache_delete() with key as a string
<?php
wincache_ucache_set('foo', 'bar');
var_dump(wincache_ucache_delete('foo'));
var_dump(wincache_ucache_exists('foo'));
?>
Powyższy przykład wyświetli:
bool(true) bool(false)
Przykład #2 Usingwincache_ucache_delete() with key as an array
<?php
$array1 = array('green' => '5', 'blue' => '6', 'yellow' => '7', 'cyan' => '8');
wincache_ucache_set($array1);
$array2 = array('green', 'blue', 'yellow', 'cyan');
var_dump(wincache_ucache_delete($array2));
?>
Powyższy przykład wyświetli:
array(4) { [0]=> string(5) "green"
[1]=> string(4) "Blue"
[2]=> string(6) "yellow"
[3]=> string(4) "cyan" }
Przykład #3 Using wincache_ucache_delete() with key as an array where some elements cannot be deleted
<?php
$array1 = array('green' => '5', 'blue' => '6', 'yellow' => '7', 'cyan' => '8');
wincache_ucache_set($array1);
$array2 = array('orange', 'red', 'yellow', 'cyan');
var_dump(wincache_ucache_delete($array2));
?>
Powyższy przykład wyświetli:
array(2) { [0]=> string(6) "yellow"
[1]=> string(4) "cyan" }
Zobacz też:
- wincache_ucache_set() - Adds a variable in user cache and overwrites a variable if it already exists in the cache
- wincache_ucache_add() - Adds a variable in user cache only if variable does not already exist in the cache
- wincache_ucache_get() - Gets a variable stored in the user cache
- wincache_ucache_clear() - Deletes entire content of the user cache
- wincache_ucache_exists() - Checks if a variable exists in the user cache
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
wincache_ucache_exists
(PECL wincache >= 1.1.0)
wincache_ucache_exists — Checks if a variable exists in the user cache
Opis
$key
)
Checks if a variable with the key exists in the user cache or not.
Parametry
-
key -
The
keythat was used to store the variable in the cache.keyis case sensitive.
Zwracane wartości
Returns TRUE if variable with the key exitsts,
otherwise returns FALSE.
Przykłady
Przykład #1 Using wincache_ucache_exists()
<?php
if (!wincache_ucache_exists('green'))
wincache_ucache_set('green', 1);
var_dump(wincache_ucache_exists('green'));
?>
Powyższy przykład wyświetli:
bool(true)
Zobacz też:
- wincache_ucache_set() - Adds a variable in user cache and overwrites a variable if it already exists in the cache
- wincache_ucache_add() - Adds a variable in user cache only if variable does not already exist in the cache
- wincache_ucache_get() - Gets a variable stored in the user cache
- wincache_ucache_clear() - Deletes entire content of the user cache
- wincache_ucache_delete() - Deletes variables from the user cache
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
wincache_ucache_get
(PECL wincache >= 1.1.0)
wincache_ucache_get — Gets a variable stored in the user cache
Opis
Gets a variable stored in the user cache.
Parametry
-
key -
The
keythat was used to store the variable in the cache.keyis case sensitive.keycan be an array of keys. In this case the return value will be an array of values of each element in thekeyarray. If an object, or an array containing objects, is returned, then the objects will be unserialized. See __wakeup() for details on unserializing objects. -
success -
Will be set to
TRUEon success andFALSEon failure.
Zwracane wartości
If key is a string, the function returns the value of the variable stored with that key.
The success is set to TRUE on success and
to FALSE on failure.
The key is an array, the parameter success
is always set to TRUE. The returned array (name => value pairs) will
contain only those name => value pairs for which the get operation in user cache was
successful. If none of the keys in the key array finds a match in the user cache
an empty array will be returned.
Przykłady
Przykład #1 wincache_ucache_get() with key as a string
<?php
wincache_ucache_add('color', 'blue');
var_dump(wincache_ucache_get('color', $success));
var_dump($success);
?>
Powyższy przykład wyświetli:
string(4) "blue" bool(true)
Przykład #2 wincache_ucache_get() with key as an array
<?php
$array1 = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
wincache_ucache_set($array1);
$array2 = array('green', 'Blue', 'yellow', 'cyan');
var_dump(wincache_ucache_get($array2, $success));
var_dump($success);
?>
Powyższy przykład wyświetli:
array(4) { ["green"]=> string(1) "5"
["Blue"]=> string(1) "6"
["yellow"]=> string(1) "7"
["cyan"]=> string(1) "8" }
bool(true)
Zobacz też:
- wincache_ucache_add() - Adds a variable in user cache only if variable does not already exist in the cache
- wincache_ucache_set() - Adds a variable in user cache and overwrites a variable if it already exists in the cache
- wincache_ucache_delete() - Deletes variables from the user cache
- wincache_ucache_clear() - Deletes entire content of the user cache
- wincache_ucache_exists() - Checks if a variable exists in the user cache
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- __wakeup()
wincache_ucache_inc
(PECL wincache >= 1.1.0)
wincache_ucache_inc — Increments the value associated with the key
Opis
Increments the value associated with the key by 1 or as specified
by inc_by.
Parametry
-
key -
The
keythat was used to store the variable in the cache.keyis case sensitive. -
inc_by -
The value by which the variable associated with the
keywill get incremented. If the argument is a floating point number it will be truncated to nearest integer. The variable associated with thekeyshould be of type long, otherwise the function fails and returnsFALSE. -
success -
Will be set to
TRUEon success andFALSEon failure.
Zwracane wartości
Returns the incremented value on success and FALSE on failure.
Przykłady
Przykład #1 Using wincache_ucache_inc()
<?php
wincache_ucache_set('counter', 1);
var_dump(wincache_ucache_inc('counter', 2921, $success));
var_dump($success);
?>
Powyższy przykład wyświetli:
int(2922) bool(true)
Zobacz też:
- wincache_ucache_dec() - Decrements the value associated with the key
- wincache_ucache_cas() - Compares the variable with old value and assigns new value to it
wincache_ucache_info
(PECL wincache >= 1.1.0)
wincache_ucache_info — Retrieves information about data stored in the user cache
Opis
$summaryonly = false
[, string $key
]] )Retrieves information about data stored in the user cache.
Parametry
-
summaryonly -
Controls whether the returned array will contain information about individual cache entries along with the user cache summary.
-
key -
The key of an entry in the user cache. If specified then the returned array will contain information only about that cache entry. If not specified and
summaryonlyis set toFALSEthen the returned array will contain information about all entries in the cache.
Zwracane wartości
Array of meta data about user cache lub FALSE w przypadku niepowodzenia
The array returned by this function contains the following elements:
- total_cache_uptime - total time in seconds that the user cache has been active
- total_item_count - total number of elements that are currently in the user cache
- is_local_cache - true is the cache metadata is for a local cache instance, false if the metadata is for the global cache
- total_hit_count - number of times the data has been served from the cache
- total_miss_count - number of times the data has not been found in the cache
-
ucache_entries - an array that contains the information about all the cached items:
- key_name - name of the key which is used to store the data
- value_type - type of value stored by the key
- use_time - time in seconds since the file has been accessed in the opcode cache
- last_check - time in seconds since the file has been checked for modifications
- is_session - indicates if the data is a session variable
- ttl_seconds - time remaining for the data to live in the cache, 0 meaning infinite
- age_seconds - time elapsed from the time data has been added in the cache
- hitcount - number of times data has been served from the cache
Przykłady
Przykład #1 Using wincache_ucache_info()
<?php
wincache_ucache_get('green');
wincache_ucache_set('green', 2922);
wincache_ucache_get('green');
wincache_ucache_get('green');
wincache_ucache_get('green');
print_r(wincache_ucache_info());
?>
Powyższy przykład wyświetli:
Array
( ["total_cache_uptime"] => int(0)
["is_local_cache"] => bool(false)
["total_item_count"] => int(1)
["total_hit_count"] => int(3)
["total_miss_count"] => int(1)
["ucache_entries"] => Array(1)
( [1] => Array(6)
(
["key_name"] => string(5) "green"
["value_type"] => string(4) "long"
["is_session"] => int(0)
["ttl_seconds"] => int(0)
["age_seconds"] => int(0)
["hitcount"] => int(3)
)
)
)
Zobacz też:
- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_ocache_fileinfo() - Retrieves information about files cached in the opcode cache
- wincache_ocache_meminfo() - Retrieves information about opcode cache memory usage
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_scache_info() - Retrieves information about files cached in the session cache
- wincache_scache_meminfo() - Retrieves information about session cache memory usage
wincache_ucache_meminfo
(PECL wincache >= 1.1.0)
wincache_ucache_meminfo — Retrieves information about user cache memory usage
Opis
Retrieves information about memory usage by user cache.
Zwracane wartości
Array of meta data about user cache memory usage lub FALSE w przypadku niepowodzenia
The array returned by this function contains the following elements:
- memory_total - amount of memory in bytes allocated for the user cache
- memory_free - amount of free memory in bytes available for the user cache
- num_used_blks - number of memory blocks used by the user cache
- num_free_blks - number of free memory blocks available for the user cache
- memory_overhead - amount of memory in bytes used for the user cache internal structures
Przykłady
Przykład #1 A wincache_ucache_meminfo() example
<pre>
<?php
print_r(wincache_ucache_meminfo());
?>
</pre>
Powyższy przykład wyświetli:
Array
(
[memory_total] => 5242880
[memory_free] => 5215056
[num_used_blks] => 6
[num_free_blks] => 3
[memory_overhead] => 176
)
Zobacz też:
- wincache_fcache_fileinfo() - Retrieves information about files cached in the file cache
- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_ocache_fileinfo() - Retrieves information about files cached in the opcode cache
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache
- wincache_scache_meminfo() - Retrieves information about session cache memory usage
wincache_ucache_set
(PECL wincache >= 1.1.0)
wincache_ucache_set — Adds a variable in user cache and overwrites a variable if it already exists in the cache
Opis
Adds a variable in user cache. Overwrites a variable if it already exists in the cache. The added or updated variable remains in the user cache unless its time to live expires or it is deleted by using wincache_ucache_delete() or wincache_ucache_clear() functions.
Parametry
-
key -
Store the variable using this
keyname. If a variable with samekeyis already present the function will overwrite the previous value with the new one.keyis case sensitive.keycan also take array of name => value pairs where names will be used as keys. This can be used to add multiple values in the cache in one operation, thus avoiding race condition. -
value -
Value of a variable to store.
Valuesupports all data types except resources, such as file handles. This paramter is ignored if first argument is an array. A general guidance is to passNULLasvaluewhile using array askey. Ifvalueis an object, or an array containing objects, then the objects will be serialized. See __sleep() for details on serializing objects. -
values -
Associative array of keys and values.
-
ttl -
Time for the variable to live in the cache in seconds. After the value specified in
ttlhas passed the stored variable will be deleted from the cache. This parameter takes a default value of 0 which means the variable will stay in the cache unless explicitly deleted by using wincache_ucache_delete() or wincache_ucache_clear() functions.
Zwracane wartości
If key is string, the function returns TRUE on success and FALSE on failure.
If key is an array, the function returns:
- If all the name => value pairs in the array can be set, function returns an empty array;
-
If all the name => value pairs in the array cannot be set, function returns
FALSE; - If some can be set while others cannot, function returns an array with name=>value pair for which the addition failed in the user cache.
Przykłady
Przykład #1 wincache_ucache_set() with key as a string
<?php
$bar = 'BAR';
var_dump(wincache_ucache_set('foo', $bar));
var_dump(wincache_ucache_get('foo'));
$bar1 = 'BAR1';
var_dump(wincache_ucache_set('foo', $bar1));
var_dump(wincache_ucache_get('foo'));
?>
Powyższy przykład wyświetli:
bool(true) string(3) "BAR" bool(true) string(3) "BAR1"
Przykład #2 wincache_ucache_set() with key as an array
<?php
$colors_array = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
var_dump(wincache_ucache_set($colors_array));
var_dump(wincache_ucache_set($colors_array));
var_dump(wincache_ucache_get('Blue'));
?>
Powyższy przykład wyświetli:
array(0) {}
array(0) {}
string(1) "6"
Zobacz też:
- wincache_ucache_add() - Adds a variable in user cache only if variable does not already exist in the cache
- wincache_ucache_get() - Gets a variable stored in the user cache
- wincache_ucache_delete() - Deletes variables from the user cache
- wincache_ucache_clear() - Deletes entire content of the user cache
- wincache_ucache_exists() - Checks if a variable exists in the user cache
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- __sleep()
wincache_unlock
(PECL wincache >= 1.1.0)
wincache_unlock — Releases an exclusive lock on a given key
Opis
$key
)Releases an exclusive lock that was obtained on a given key by using wincache_lock(). If any other process was blocked waiting for the lock on this key, that process will be able to obtain the lock.
Using of the wincache_lock() and wincache_unlock() can cause deadlocks when executing PHP scripts in a multi-process environment like FastCGI. Do not use these functions unless you are absolutely sure you need to use them. For the majority of the operations on the user cache it is not necessary to use these functions.
Parametry
-
key -
Name of the key in the cache to release the lock on.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Using wincache_unlock()
<?php
$fp = fopen("/tmp/lock.txt", "r+");
if (wincache_lock(“lock_txt_lock”)) { // do an exclusive lock
ftruncate($fp, 0); // truncate file
fwrite($fp, "Write something here\n");
wincache_unlock(“lock_txt_lock”); // release the lock
} else {
echo "Couldn't get the lock!";
}
fclose($fp);
?>
Zobacz też:
- wincache_lock() - Acquires an exclusive lock on a given key
- wincache_ucache_set() - Adds a variable in user cache and overwrites a variable if it already exists in the cache
- wincache_ucache_get() - Gets a variable stored in the user cache
- wincache_ucache_delete() - Deletes variables from the user cache
- wincache_ucache_clear() - Deletes entire content of the user cache
- wincache_ucache_exists() - Checks if a variable exists in the user cache
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache
Spis treści
- wincache_fcache_fileinfo — Retrieves information about files cached in the file cache
- wincache_fcache_meminfo — Retrieves information about file cache memory usage
- wincache_lock — Acquires an exclusive lock on a given key
- wincache_ocache_fileinfo — Retrieves information about files cached in the opcode cache
- wincache_ocache_meminfo — Retrieves information about opcode cache memory usage
- wincache_refresh_if_changed — Refreshes the cache entries for the cached files
- wincache_rplist_fileinfo — Retrieves information about resolve file path cache
- wincache_rplist_meminfo — Retrieves information about memory usage by the resolve file path cache
- wincache_scache_info — Retrieves information about files cached in the session cache
- wincache_scache_meminfo — Retrieves information about session cache memory usage
- wincache_ucache_add — Adds a variable in user cache only if variable does not already exist in the cache
- wincache_ucache_cas — Compares the variable with old value and assigns new value to it
- wincache_ucache_clear — Deletes entire content of the user cache
- wincache_ucache_dec — Decrements the value associated with the key
- wincache_ucache_delete — Deletes variables from the user cache
- wincache_ucache_exists — Checks if a variable exists in the user cache
- wincache_ucache_get — Gets a variable stored in the user cache
- wincache_ucache_inc — Increments the value associated with the key
- wincache_ucache_info — Retrieves information about data stored in the user cache
- wincache_ucache_meminfo — Retrieves information about user cache memory usage
- wincache_ucache_set — Adds a variable in user cache and overwrites a variable if it already exists in the cache
- wincache_unlock — Releases an exclusive lock on a given key
Building for Windows
Spis treści
Prerequisites
Building WinCache extension will require:
- PHP source code
- PHP build environment
- WinCache source code
For completing first two steps, follow the step-by-step guide for how to » build PHP on Windows.
For getting the WinCache source code follow the instructions described in Downloading PECL extensions.
Compiling and building
The following steps describe how to compile and build WinCache on Windows OS:
-
Open a command prompt which is used to build PHP
-
Go to the root folder where PHP sources are present
-
Run the command:
cscript.exe win32\build\buildconf.js
-
Run the command:
The output will contain a new flag --enable-wincache.configure.bat --help
-
Run the command:
--enable-wincache is the only extra option which is required to ensure that WinCache extension gets built properly. This option will build WinCache and will statically link it with PHP dll. To build WinCache extension as a stand-alone DLL use the option --enable-wincache=shared.configure.js [all options used to build PHP] --enable-wincache
-
Run the command:
nmake
Verifying the build
The following steps describe how to verify that WinCache has been built correctly:
-
Go to the folder where the PHP binaries are built
-
Run the command:
If WinCache has been built properly, the output of this command will list the INI directives and functions supported by WinCache.php.exe -n -d extension=php_wincache.dll -re wincache
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- WinCache Funkcje
- wincache_fcache_fileinfo — Retrieves information about files cached in the file cache
- wincache_fcache_meminfo — Retrieves information about file cache memory usage
- wincache_lock — Acquires an exclusive lock on a given key
- wincache_ocache_fileinfo — Retrieves information about files cached in the opcode cache
- wincache_ocache_meminfo — Retrieves information about opcode cache memory usage
- wincache_refresh_if_changed — Refreshes the cache entries for the cached files
- wincache_rplist_fileinfo — Retrieves information about resolve file path cache
- wincache_rplist_meminfo — Retrieves information about memory usage by the resolve file path cache
- wincache_scache_info — Retrieves information about files cached in the session cache
- wincache_scache_meminfo — Retrieves information about session cache memory usage
- wincache_ucache_add — Adds a variable in user cache only if variable does not already exist in the cache
- wincache_ucache_cas — Compares the variable with old value and assigns new value to it
- wincache_ucache_clear — Deletes entire content of the user cache
- wincache_ucache_dec — Decrements the value associated with the key
- wincache_ucache_delete — Deletes variables from the user cache
- wincache_ucache_exists — Checks if a variable exists in the user cache
- wincache_ucache_get — Gets a variable stored in the user cache
- wincache_ucache_inc — Increments the value associated with the key
- wincache_ucache_info — Retrieves information about data stored in the user cache
- wincache_ucache_meminfo — Retrieves information about user cache memory usage
- wincache_ucache_set — Adds a variable in user cache and overwrites a variable if it already exists in the cache
- wincache_unlock — Releases an exclusive lock on a given key
- Building for Windows
Hierarchical Profiler
Wstęp
XHProf is a light-weight hierarchical and instrumentation based profiler. During the data collection phase, it keeps track of call counts and inclusive metrics for arcs in the dynamic callgraph of a program. It computes exclusive metrics in the reporting/post processing phase, such as wall (elapsed) time, CPU time and memory usage. A functions profile can be broken down by callers or callees. XHProf handles recursive functions by detecting cycles in the callgraph at data collection time itself and avoiding the cycles by giving unique depth qualified names for the recursive invocations.
XHProf includes a simple HTML based user interface (written in PHP). The browser based UI for viewing profiler results makes it easy to view results or to share results with peers. A callgraph image view is also supported.
XHProf reports can often be helpful in understanding the structure of the code being executed. The hierarchical nature of the reports can be used to determine, for example, what chain of calls led to a particular function getting called.
XHProf supports ability to compare two runs (a.k.a. "diff" reports) or aggregate data from multiple runs. Diff and aggregate reports, much like single run reports, offer "flat" as well as "hierarchical" views of the profile.
Additional documentation can be found via the » facebook xhprof website.
Instalacja/Konfiguracja
Spis treści
Wymagania
Although not required, xhprof includes an interface that's written in PHP. It's used to save and display the profiled data in a usable way, where viewing is done via a web browser. So, a PHP enabled web server will likely make the xhprof experience more useful.
There's also a fork of the GUI interface at » http://github.com/preinheimer/xhprof
Instalacja
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/xhprof
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| xhprof.output_dir | "" | PHP_INI_ALL |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
xhprof.output_dirstring -
Directory used by the default implementation of the iXHProfRuns interface (namely, the XHProfRuns_Default class) for storing XHProf runs.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
Przykłady
Przykład #1 Xhprof example with the optional GUI
This example starts and stops the profiler, then uses the bundled GUI interface to save and parse the results. In other words, the code from the extension itself ends at the call to xhprof_disable().
<?php
xhprof_enable(XHPROF_FLAGS_CPU + XHPROF_FLAGS_MEMORY);
for ($i = 0; $i <= 1000; $i++) {
$a = $i * $i;
}
$xhprof_data = xhprof_disable();
$XHPROF_ROOT = "/tools/xhprof/";
include_once $XHPROF_ROOT . "/xhprof_lib/utils/xhprof_lib.php";
include_once $XHPROF_ROOT . "/xhprof_lib/utils/xhprof_runs.php";
$xhprof_runs = new XHProfRuns_Default();
$run_id = $xhprof_runs->save_run($xhprof_data, "xhprof_testing");
echo "http://localhost/xhprof/xhprof_html/index.php?run={$run_id}&source=xhprof_testing\n";
?>
Powyższy przykład wyświetli coś podobnego do:
http://localhost/xhprof/xhprof_html/index.php?run=t11_4bdf44d21121f&source=xhprof_testing
Xhprof Funkcje
xhprof_disable
(PECL xhprof >= 0.9.0)
xhprof_disable — Stops xhprof profiler
Opis
Stops the profiler, and returns xhprof data from the run.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
An array of xhprof data, from the run.
Przykłady
Przykład #1 xhprof_disable() example
<?php
xhprof_enable();
$foo = strlen("foo bar");
$xhprof_data = xhprof_disable();
print_r($xhprof_data);
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[main()==>strlen] => Array
(
[ct] => 1
[wt] => 279
)
[main()==>xhprof_disable] => Array
(
[ct] => 1
[wt] => 9
)
[main()] => Array
(
[ct] => 1
[wt] => 610
)
)
xhprof_enable
(PECL xhprof >= 0.9.0)
xhprof_enable — Start xhprof profiler
Opis
$flags = 0
[, array $options
]] )Start xhprof profiling.
Parametry
-
flags -
Optional flags to add additional information to the profiling. See the XHprof constants for further information about these flags, e.g.,
XHPROF_FLAGS_MEMORYto enable memory profiling. -
options -
An array of optional options, namely, the 'ignored_functions' option to pass in functions to be ignored during profiling.
Zwracane wartości
NULL
Rejestr zmian
| Wersja | Opis |
|---|---|
| 0.9.2 |
The optional options parameter was added.
|
Przykłady
Przykład #1 xhprof_enable() examples
<?php
// 1. elapsed time + memory + CPU profiling; and ignore built-in (internal) functions
xhprof_enable(XHPROF_FLAGS_NO_BUILTINS | XHPROF_FLAGS_CPU | XHPROF_FLAGS_MEMORY);
// 2. elapsed time profiling; ignore call_user_func* during profiling
xhprof_enable(
0,
array('ignored_functions' => array('call_user_func',
'call_user_func_array')));
// 3. elapsed time + memory profiling; ignore call_user_func* during profiling
xhprof_enable(
XHPROF_FLAGS_MEMORY,
array('ignored_functions' => array('call_user_func',
'call_user_func_array')));
?>
Zobacz też:
- xhprof_disable() - Stops xhprof profiler
- xhprof_sample_enable() - Description
- memory_get_usage() - Returns the amount of memory allocated to PHP
- getrusage() - Gets the current resource usages
xhprof_sample_disable
(PECL xhprof >= 0.9.0)
xhprof_sample_disable — Stops xhprof sample profiler
Opis
Stops the sample mode xhprof profiler, and
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
An array of xhprof sample data, from the run.
Przykłady
Przykład #1 xhprof_sample_disable() example
<?php
xhprof_sample_enable();
for ($i = 0; $i <= 10000; $i++) {
$a = strlen($i);
$b = $i * $a;
$c = rand();
}
$xhprof_data = xhprof_sample_disable();
print_r($xhprof_data);
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[1272935300.800000] => main()
[1272935300.900000] => main()
)
xhprof_sample_enable
(PECL xhprof >= 0.9.0)
xhprof_sample_enable — Description
Opis
Starts profiling in sample mode, which is a lighter weight version of xhprof_enable(). The sampling interval is 0.1 seconds, and samples record the full function call stack. The main use case is when lower overhead is required when doing performance monitoring and diagnostics.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
NULL
Zobacz też:
- xhprof_sample_disable() - Stops xhprof sample profiler
- xhprof_enable() - Start xhprof profiler
- memory_get_usage() - Returns the amount of memory allocated to PHP
- getrusage() - Gets the current resource usages
Spis treści
- xhprof_disable — Stops xhprof profiler
- xhprof_enable — Start xhprof profiler
- xhprof_sample_disable — Stops xhprof sample profiler
- xhprof_sample_enable — Description
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Przykłady
- Xhprof Funkcje
- xhprof_disable — Stops xhprof profiler
- xhprof_enable — Start xhprof profiler
- xhprof_sample_disable — Stops xhprof sample profiler
- xhprof_sample_enable — Description
- APC — Alternative PHP Cache
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- APC Funkcje
- APCIterator — The APCIterator class
- APD — Advanced PHP debugger
- bcompiler — PHP bytecode Compiler
- Error Handling — Error Handling and Logging
- htscanner — htaccess-like support for all SAPIs
- inclued — Inclusion hierarchy viewer
- Memtrack
- Output Control — Output Buffering Control
- Object overloading — Object property and method call overloading
- PHP Options/Info — PHP Options and Information
- runkit
- scream — Break the silence operator
- Weakref — Weak References
- Wstęp
- Instalacja/Konfiguracja
- Weakref — The Weakref class
- WinCache — Windows Cache for PHP
- Xhprof — Hierarchical Profiler
Przetwarzanie formatów audio
Tagi ID3
Wstęp
Te funkcje umożliwiają odczyt i modyfikację znaczników ID3. Znaczniki ID3 są używane w plikach MP3 do przechowywania metadanych, takich jak: tytułu piosenki, informacji o artyście, albumie, gatunku, roku wydania, oraz numerze utworu.
Od wersji 0.2 możliwe jest wydobywanie informacji tekstowych ze znaczników ID3 v2.2+ .
Instalacja/Konfiguracja
Spis treści
Wymagania
Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.
Instalacja
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/id3.
DLL z tym rozszerzeniem PECL można pobrać zarówno ze strony » PHP Downloads lub z » http://pecl4win.php.net/
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Predefined Constants
Most of the id3 functions either let you specify or return a tag version. In order to specify the version please use on of these constants.
-
ID3_V1_0(integer) -
ID3_V1_0is used if you are working with ID3 V1.0 tags. These tags may contain the fields title, artist, album, genre, year and comment. -
ID3_V1_1(integer) -
ID3_V1_1is used if you are working with ID3 V1.1 tags. These tags may all information contained in v1.0 tags plus the track number. -
ID3_V2_1(integer) -
ID3_V2_1is used if you are working with ID3 V2.1 tags. -
ID3_V2_2(integer) -
ID3_V2_2is used if you are working with ID3 V2.2 tags. -
ID3_V2_3(integer) -
ID3_V2_3is used if you are working with ID3 V2.3 tags. -
ID3_V2_4(integer) -
ID3_V2_4is used if you are working with ID3 V2.4 tags. -
ID3_BEST(integer) -
ID3_BESTis used if would like to let the id3 functions determine which tag version should be used.
Funkcje ID3
id3_get_frame_long_name
(PECL id3 >= 0.2)
id3_get_frame_long_name — Get the long name of an ID3v2 frame
Opis
$frameId
)id3_get_frame_long_name() returns the long name for an ID3v2 frame.
Parametry
-
frameId -
An ID3v2 frame
Zwracane wartości
Returns the frame long name or FALSE on errors.
Przykłady
Przykład #1 id3_get_frame_long_name() example
<?php
$longName = id3_get_frame_long_name("TOLY");
echo $longName;
?>
Powyższy przykład wyświetli:
Original lyricist(s)/text writer(s)
id3_get_frame_short_name
(PECL id3 >= 0.2)
id3_get_frame_short_name — Get the short name of an ID3v2 frame
Opis
$frameId
)id3_get_frame_short_name() returns the short name for an ID3v2 frame.
Parametry
-
frameId -
An ID3v2 frame
Zwracane wartości
Returns the frame short name or FALSE on errors.
The values returned by id3_get_frame_short_name() are used in the array returned by id3_get_tag().
Przykłady
Przykład #1 id3_get_frame_short_name() example
<?php
$shortName = id3_get_frame_short_name("TOLY");
echo $shortName;
?>
Powyższy przykład wyświetli:
originalLyricist
id3_get_genre_id
(PECL id3 >= 0.1)
id3_get_genre_id — Get the id for a genre
Opis
$genre
)id3_get_genre_id() returns the id for a genre.
Parametry
-
genre -
Genre name as string.
Zwracane wartości
The genre id or FALSE on errors.
Przykłady
Przykład #1 id3_get_genre_id() example
<?php
$id = id3_get_genre_id("Alternative");
echo $id;
?>
Powyższy przykład wyświetli:
20
Zobacz też:
- id3_get_genre_name() - Get the name for a genre id
- id3_get_genre_list() - Get all possible genre values
id3_get_genre_list
(PECL id3 >= 0.1)
id3_get_genre_list — Get all possible genre values
Opis
id3_get_genre_list() returns an array containing all possible genres that may be stored in an ID3 tag. This list has been created by Eric Kemp and later extended by WinAmp.
This function is useful to provide you users a list of genres from which they may choose one. When updating the ID3 tag you will always have to specify the genre as an integer ranging from 0 to 147.
Zwracane wartości
Returns an array containing all possible genres that may be stored in an ID3 tag.
Przykłady
Przykład #1 id3_get_genre_list() example
<?php
$genres = id3_get_genre_list();
print_r($genres);
?>
Powyższy przykład wyświetli:
Array
(
[0] => Blues
[1] => Classic Rock
[2] => Country
[3] => Dance
[4] => Disco
[5] => Funk
[6] => Grunge
[7] => Hip-Hop
[8] => Jazz
[9] => Metal
[10] => New Age
[11] => Oldies
[12] => Other
[13] => Pop
[14] => R&B
[15] => Rap
[16] => Reggae
[17] => Rock
[18] => Techno
[19] => Industrial
[20] => Alternative
[21] => Ska
[22] => Death Metal
[23] => Pranks
[24] => Soundtrack
[25] => Euro-Techno
[26] => Ambient
[27] => Trip-Hop
[28] => Vocal
[29] => Jazz+Funk
[30] => Fusion
[31] => Trance
[32] => Classical
[33] => Instrumental
[34] => Acid
[35] => House
[36] => Game
[37] => Sound Clip
[38] => Gospel
[39] => Noise
[40] => Alternative Rock
[41] => Bass
[42] => Soul
[43] => Punk
[44] => Space
[45] => Meditative
[46] => Instrumental Pop
[47] => Instrumental Rock
[48] => Ethnic
[49] => Gothic
[50] => Darkwave
[51] => Techno-Industrial
[52] => Electronic
[53] => Pop-Folk
[54] => Eurodance
[55] => Dream
[56] => Southern Rock
[57] => Comedy
[58] => Cult
[59] => Gangsta
[60] => Top 40
[61] => Christian Rap
[62] => Pop/Funk
[63] => Jungle
[64] => Native US
[65] => Cabaret
[66] => New Wave
[67] => Psychadelic
[68] => Rave
[69] => Showtunes
[70] => Trailer
[71] => Lo-Fi
[72] => Tribal
[73] => Acid Punk
[74] => Acid Jazz
[75] => Polka
[76] => Retro
[77] => Musical
[78] => Rock & Roll
[79] => Hard Rock
[80] => Folk
[81] => Folk-Rock
[82] => National Folk
[83] => Swing
[84] => Fast Fusion
[85] => Bebob
[86] => Latin
[87] => Revival
[88] => Celtic
[89] => Bluegrass
[90] => Avantgarde
[91] => Gothic Rock
[92] => Progressive Rock
[93] => Psychedelic Rock
[94] => Symphonic Rock
[95] => Slow Rock
[96] => Big Band
[97] => Chorus
[98] => Easy Listening
[99] => Acoustic
[100] => Humour
[101] => Speech
[102] => Chanson
[103] => Opera
[104] => Chamber Music
[105] => Sonata
[106] => Symphony
[107] => Booty Bass
[108] => Primus
[109] => Porn Groove
[110] => Satire
[111] => Slow Jam
[112] => Club
[113] => Tango
[114] => Samba
[115] => Folklore
[116] => Ballad
[117] => Power Ballad
[118] => Rhytmic Soul
[119] => Freestyle
[120] => Duet
[121] => Punk Rock
[122] => Drum Solo
[123] => Acapella
[124] => Euro-House
[125] => Dance Hall
[126] => Goa
[127] => Drum & Bass
[128] => Club-House
[129] => Hardcore
[130] => Terror
[131] => Indie
[132] => BritPop
[133] => Negerpunk
[134] => Polsk Punk
[135] => Beat
[136] => Christian Gangsta
[137] => Heavy Metal
[138] => Black Metal
[139] => Crossover
[140] => Contemporary C
[141] => Christian Rock
[142] => Merengue
[143] => Salsa
[144] => Thrash Metal
[145] => Anime
[146] => JPop
[147] => SynthPop
)
Zobacz też:
- id3_get_genre_name() - Get the name for a genre id
- id3_get_genre_id() - Get the id for a genre
id3_get_genre_name
(PECL id3 >= 0.1)
id3_get_genre_name — Get the name for a genre id
Opis
$genre_id
)id3_get_genre_name() returns the name for a genre id.
Parametry
-
genre_id -
An integer ranging from 0 to 147
Zwracane wartości
Returns the name as a string.
Przykłady
Przykład #1 id3_get_genre_name() example
<?php
$genre = id3_get_genre_name(20);
echo $genre;
?>
Powyższy przykład wyświetli:
Alternative
Zobacz też:
- id3_get_genre_list() - Get all possible genre values
- id3_get_genre_id() - Get the id for a genre
id3_get_tag
(PECL id3 >= 0.1)
id3_get_tag — Get all information stored in an ID3 tag
Opis
$filename
[, int $version = ID3_BEST
] )id3_get_tag() is used to get all information stored in the id3 tag of the specified file.
Parametry
-
filename -
The path to the MP3 file
Instead of a filename you may also pass a valid stream resource
-
version -
Allows you to specify the version of the tag as MP3 files may contain both, version 1.x and version 2.x tags
Since version 0.2 id3_get_tag() also supports ID3 tags of version 2.2, 2.3 and 2.4. To extract information from these tags, pass one of the constants ID3_V2_2, ID3_V2_3 or ID3_V2_4 as the second parameter. ID3 v2.x tags can contain a lot more information about the MP3 file than ID3 v1.x tags.
Zwracane wartości
Returns an associative array with various keys like: title, artist, ..
The key genre will contain an integer between 0 and 147. You may use id3_get_genre_name() to convert it to a human readable string.
Przykłady
Przykład #1 id3_get_tag() example
<?php
$tag = id3_get_tag( "path/to/example.mp3" );
print_r($tag);
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[title] => DN-38416
[artist] => Re:\Legion
[album] => Reflections
[year] => 2004
[genre] => 19
)
Przykład #2 id3_get_tag() example
<?php
$tag = id3_get_tag( "path/to/example2.mp3", ID3_V2_3 );
print_r($tag);
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[copyright] => Dirty Mac
[originalArtist] => Dirty Mac
[composer] => Marcus Götze
[artist] => Dirty Mac
[title] => Little Big Man
[album] => Demo-Tape
[track] => 5/12
[genre] => (17)Rock
[year] => 2001
)
Zobacz też:
- id3_set_tag() - Update information stored in an ID3 tag
- id3_remove_tag() - Remove an existing ID3 tag
- id3_get_version() - Get version of an ID3 tag
id3_get_version
(PECL id3 >= 0.1)
id3_get_version — Get version of an ID3 tag
Opis
$filename
)id3_get_version() retrieves the version(s) of the ID3 tag(s) in the MP3 file.
If a file contains an ID3 v1.1 tag, it always contains a 1.0 tag, as version 1.1 is just an extension of 1.0.
Parametry
-
filename -
The path to the MP3 file
Instead of a filename you may also pass a valid stream resource
Zwracane wartości
Returns the version number of the ID3 tag of the file.
As a tag can contain ID3 v1.x and v2.x tags, the return value of this
function should be bitwise compared with the predefined constants
ID3_V1_0, ID3_V1_1 and
ID3_V2.
Przykłady
Przykład #1 id3_get_version() example
<?php
$version = id3_get_version( "path/to/example.mp3" );
if ($version & ID3_V1_0) {
echo "Contains a 1.x tag\n";
}
if ($version & ID3_V1_1) {
echo "Contains a 1.1 tag\n";
}
if ($version & ID3_V2) {
echo "Contains a 2.x tag\n";
}
?>
Powyższy przykład wyświetli coś podobnego do:
Contains a 1.x tag Contains a 1.1 tag
Zobacz też:
- id3_set_tag() - Update information stored in an ID3 tag
- id3_get_tag() - Get all information stored in an ID3 tag
- id3_remove_tag() - Remove an existing ID3 tag
id3_remove_tag
(PECL id3 >= 0.1)
id3_remove_tag — Remove an existing ID3 tag
Opis
$filename
[, int $version = ID3_V1_0
] )id3_remove_tag() is used to remove the information stored of an ID3 tag.
Parametry
-
filename -
The path to the MP3 file
Instead of a filename you may also pass a valid stream resource
-
version -
Allows you to specify the version of the tag as MP3 files may contain both, version 1.x and version 2.x tags.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 id3_remove_tag() example
<?php
$result = id3_remove_tag( "path/to/example.mp3", ID3_V1_0 );
if ($result === true) {
echo "Tag succesfully removed\n";
}
?>
If the file is writable and contained a 1.0 tag, this will output:
Tag succesfully removed
Notatki
Informacja: Currently id3_remove_tag() only supports version 1.0 and 1.1. If you choose to remove a 1.0 tag and the file contains a 1.1 tag, this tag will be removed, as v1.1 is only an extension of 1.0.
Zobacz też:
- id3_set_tag() - Update information stored in an ID3 tag
- id3_get_tag() - Get all information stored in an ID3 tag
- id3_get_version() - Get version of an ID3 tag
id3_set_tag
(PECL id3 >= 0.1)
id3_set_tag — Update information stored in an ID3 tag
Opis
$filename
, array $tag
[, int $version = ID3_V1_0
] )id3_set_tag() is used to change the information stored of an ID3 tag. If no tag has been present, it will be added to the file.
Parametry
-
filename -
The path to the MP3 file
Instead of a filename you may also pass a valid stream resource
-
tag -
An associative array of tag keys and values
The following keys may be used in the associative array:
Keys in the associative array key possible value available in version title string with maximum of 30 characters v1.0, v1.1 artist string with maximum of 30 characters v1.0, v1.1 album string with maximum of 30 characters v1.0, v1.1 year 4 digits v1.0, v1.1 genre integer value between 0 and 147 v1.0, v1.1 comment string with maximum of 30 characters (28 in v1.1) v1.0, v1.1 track integer between 0 and 255 v1.1 -
version -
Allows you to specify the version of the tag as MP3 files may contain both, version 1.x and version 2.x tags
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 id3_set_tag() example
<?php
$data = array(
"title" => "Re:Start",
"artist" => "Re:\Legion",
"comment" => "A nice track"
);
$result = id3_set_tag( "path/to/example.mp3", $data, ID3_V1_0 );
if ($result === true) {
echo "Tag succesfully updated\n";
}
?>
If the file is writable, this will output:
Tag succesfully updated
Notatki
Informacja: Currently id3_set_tag() only supports version 1.0 and 1.1.
Zobacz też:
- id3_remove_tag() - Remove an existing ID3 tag
- id3_get_tag() - Get all information stored in an ID3 tag
- id3_get_version() - Get version of an ID3 tag
Spis treści
- id3_get_frame_long_name — Get the long name of an ID3v2 frame
- id3_get_frame_short_name — Get the short name of an ID3v2 frame
- id3_get_genre_id — Get the id for a genre
- id3_get_genre_list — Get all possible genre values
- id3_get_genre_name — Get the name for a genre id
- id3_get_tag — Get all information stored in an ID3 tag
- id3_get_version — Get version of an ID3 tag
- id3_remove_tag — Remove an existing ID3 tag
- id3_set_tag — Update information stored in an ID3 tag
- Wstęp
- Instalacja/Konfiguracja
- Predefined Constants
- Funkcje ID3
- id3_get_frame_long_name — Get the long name of an ID3v2 frame
- id3_get_frame_short_name — Get the short name of an ID3v2 frame
- id3_get_genre_id — Get the id for a genre
- id3_get_genre_list — Get all possible genre values
- id3_get_genre_name — Get the name for a genre id
- id3_get_tag — Get all information stored in an ID3 tag
- id3_get_version — Get version of an ID3 tag
- id3_remove_tag — Remove an existing ID3 tag
- id3_set_tag — Update information stored in an ID3 tag
KTaglib
Wstęp
KTaglib is an object oriented binding to the taglib library from the KDE project used in projects like Amarok to read and write ID3 and Ogg tags. The library also provides access to audio information. The bindings are designed usually follow the underlying C++ API, but were changed whenever there is a more PHP-like way.
Informacja:
At the moment ktaglib is able to read and write ID3v1 and ID3v2 tags.
Instalacja/Konfiguracja
Spis treści
Wymagania
If you want to build ktaglib you need at least taglib 1.5 installed. To obtain the taglib see the » taglib project page. Windows DLL's are build static against taglib, therefore there is no need to have taglib installed.
Instalacja
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/ktaglib.
DLL z tym rozszerzeniem PECL można pobrać zarówno ze strony » PHP Downloads lub z » http://pecl4win.php.net/
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
KTaglib uses class constants. Most of the constants are mappings to the according Taglib enums and constants.
-
KTaglib_MPEG_Header::Version1(integer) - ID3 version is 1.0
-
KTaglib_MPEG_Header::Version2(integer) - ID3 version is 2.0
-
KTaglib_MPEG_Header::Version2_5(integer) - ID3 version is 2.5
-
KTaglib_ID3v2_AttachedPictureFrame::Other(integer) - Picture type Other
-
KTaglib_ID3v2_AttachedPictureFrame::FileIcon(integer) - Picture type FileIcon
-
KTaglib_ID3v2_AttachedPictureFrame::OtherFileIcon(integer) - Picture type OtherFileIcon
-
KTaglib_ID3v2_AttachedPictureFrame::FrontCover(integer) - Picture type FrontCover
-
KTaglib_ID3v2_AttachedPictureFrame::BackCover(integer) - Picture type BackCover
-
KTaglib_ID3v2_AttachedPictureFrame::LeafletPage(integer) - Picture type LeafletPage
-
KTaglib_ID3v2_AttachedPictureFrame::Media(integer) - Picture type Media
-
KTaglib_ID3v2_AttachedPictureFrame::LeadArtist(integer) - Picture type LeadArtist
-
KTaglib_ID3v2_AttachedPictureFrame::Artist(integer) - Picture type Artist
-
KTaglib_ID3v2_AttachedPictureFrame::Conductor(integer) - Picture type Condutor
-
KTaglib_ID3v2_AttachedPictureFrame::Band(integer) - Picture type Band
-
KTaglib_ID3v2_AttachedPictureFrame::Composer(integer) - Picture type Composer
-
KTaglib_ID3v2_AttachedPictureFrame::Lyricist(integer) - Picture type Lyricist
-
KTaglib_ID3v2_AttachedPictureFrame::RecordingLocation(integer) - Picture type RecordingLocation
-
KTaglib_ID3v2_AttachedPictureFrame::DuringRecording(integer) - Picture type DuringRecording
-
KTaglib_ID3v2_AttachedPictureFrame::DuringPerformance(integer) - Picture type DuringPerformance
-
KTaglib_ID3v2_AttachedPictureFrame::MovieScreenCapture(integer) - Picture type MovieScreenCapture
-
KTaglib_ID3v2_AttachedPictureFrame::ColouredFish(integer) - Picture type ColouredFish
-
KTaglib_ID3v2_AttachedPictureFrame::Illustration(integer) - Picture type Illustration
-
KTaglib_ID3v2_AttachedPictureFrame::BandLogo(integer) - Picture type BandLogo
The KTaglib_MPEG_File class
(No version information available, might only be in SVN)
Wstęp
Represents an MPEG file. MPEG files can have ID3v1, ID3v2 tags and audio properties.
Class synopsis
KTaglib_MPEG_File::__construct
(0.0.1)
KTaglib_MPEG_File::__construct — Opens a new file
Opis
$filename
)Opens a new MPEG file.
Parametry
-
filename -
The file to read
Przykłady
Przykład #1 Opens a new MP3 file and read the title
<?php
$mpeg = new KTaglib_MPEG_File('example.mp3');
echo $mpeg->getID3v1Tag()->getTitle();
?>
KTaglib_MPEG_File::getAudioProperties
(0.0.1)
KTaglib_MPEG_File::getAudioProperties — Returns an object that provides access to the audio properties
Opis
Returns an object that provides access to the audio properties of the mpeg file.
Zwracane wartości
Returns an KTaglib_MPEG_AudioProperties object or false.
KTaglib_MPEG_File::getID3v1Tag
(0.0.1)
KTaglib_MPEG_File::getID3v1Tag — Returns an object representing an ID3v1 tag
Opis
$create = false
] )Returns an object that represents an ID3v1 tag, which can be used to get information about the ID3v1 tag.
Zwracane wartości
Returns an KTaglib_MPEG_ID3v1Tag object or false if there is no ID3v1 tag.
KTaglib_MPEG_File::getID3v2Tag
(0.0.1)
KTaglib_MPEG_File::getID3v2Tag — Returns a ID3v2 object
Opis
Returns a ID3v2 object for the mpeg file. If no ID3v2 Tag is present, an KTaglib_TagNotFoundException is thrown.
Zwracane wartości
Returns the KTaglib_ID3v2_Tag object of the MPEG file or false if there is no ID3v2 tag
Spis treści
- KTaglib_MPEG_File::__construct — Opens a new file
- KTaglib_MPEG_File::getAudioProperties — Returns an object that provides access to the audio properties
- KTaglib_MPEG_File::getID3v1Tag — Returns an object representing an ID3v1 tag
- KTaglib_MPEG_File::getID3v2Tag — Returns a ID3v2 object
The KTaglib_MPEG_AudioProperties class
(No version information available, might only be in SVN)
Wstęp
Represents the audio properties of a MPEG file, like length, bitrate or samplerate.
Class synopsis
KTaglib_MPEG_AudioProperties::getBitrate
(0.0.1)
KTaglib_MPEG_AudioProperties::getBitrate — Returns the bitrate of the MPEG file
Opis
Returns the bitrate of the MPEG file
Zwracane wartości
Returns the bitrate as an integer
KTaglib_MPEG_AudioProperties::getChannels
(0.0.1)
KTaglib_MPEG_AudioProperties::getChannels — Returns the amount of channels of a MPEG file
Opis
Returns the amount of channels of the MPEG file
Zwracane wartości
Returns the channel count as an integer
KTaglib_MPEG_AudioProperties::getLayer
(0.0.1)
KTaglib_MPEG_AudioProperties::getLayer — Returns the layer of a MPEG file
Opis
Returns the layer of the MPEG file (usually 3 for MP3).
Zwracane wartości
Returns the layer as an integer
KTaglib_MPEG_AudioProperties::getLength
(0.0.1)
KTaglib_MPEG_AudioProperties::getLength — Returns the length of a MPEG file
Opis
Returns the length of the MPEG file
Zwracane wartości
Returns the length as an integer
KTaglib_MPEG_AudioProperties::getSampleBitrate
(0.0.1)
KTaglib_MPEG_AudioProperties::getSampleBitrate — Returns the sample bitrate of a MPEG file
Opis
Returns the sample bitrate of the MPEG file
Zwracane wartości
Returns the sample bitrate as an integer
KTaglib_MPEG_AudioProperties::getVersion
(0.0.1)
KTaglib_MPEG_AudioProperties::getVersion — Returns the version of a MPEG file
Opis
Returns the version of the MPEG file header. The possible versions are defined in Tag_MPEG_Header (Version1, Version2, Version2.5).
Zwracane wartości
Returns the version
KTaglib_MPEG_AudioProperties::isCopyrighted
(0.0.1)
KTaglib_MPEG_AudioProperties::isCopyrighted — Returns the length of a MPEG file
Opis
Returns true if the MPEG file is copyrighted
Zwracane wartości
Returns true if the MPEG file is copyrighted
KTaglib_MPEG_AudioProperties::isOriginal
(0.0.1)
KTaglib_MPEG_AudioProperties::isOriginal — Returns if the file is marked as the original file
Opis
Returns true if the file is marked as the original file
Zwracane wartości
Returns true if the file is marked as the original file
KTaglib_MPEG_AudioProperties::isProtectionEnabled
(0.0.1)
KTaglib_MPEG_AudioProperties::isProtectionEnabled — Returns the length of a MPEG file
Opis
Returns true if protection mechanism (like DRM) are enabled for this file
Zwracane wartości
Returns true if protection mechanism (like DRM) are enabled for this file
Spis treści
- KTaglib_MPEG_AudioProperties::getBitrate — Returns the bitrate of the MPEG file
- KTaglib_MPEG_AudioProperties::getChannels — Returns the amount of channels of a MPEG file
- KTaglib_MPEG_AudioProperties::getLayer — Returns the layer of a MPEG file
- KTaglib_MPEG_AudioProperties::getLength — Returns the length of a MPEG file
- KTaglib_MPEG_AudioProperties::getSampleBitrate — Returns the sample bitrate of a MPEG file
- KTaglib_MPEG_AudioProperties::getVersion — Returns the version of a MPEG file
- KTaglib_MPEG_AudioProperties::isCopyrighted — Returns the length of a MPEG file
- KTaglib_MPEG_AudioProperties::isOriginal — Returns if the file is marked as the original file
- KTaglib_MPEG_AudioProperties::isProtectionEnabled — Returns the length of a MPEG file
The KTaglib_Tag class
(No version information available, might only be in SVN)
Wstęp
Base class for ID3v1 or ID3v2 tags
KTaglib_Tag::getAlbum
(0.0.1)
KTaglib_Tag::getAlbum — Returns the title string from a ID3 tag
Opis
Returns the album string of an ID3 tag. This method is implemented in ID3v1 and ID3v2 tags.
Zwracane wartości
Returns the album string
KTaglib_Tag::getArtist
(0.0.1)
KTaglib_Tag::getArtist — Returns the artist string from a ID3 tag
Opis
Returns the artist string of an ID3 tag. This method is implemented in ID3v1 and ID3v2 tags.
Zwracane wartości
Returns the artist string
KTaglib_Tag::getComment
(0.0.1)
KTaglib_Tag::getComment — Returns the comment from a ID3 tag
Opis
Returns the comment of an ID3 tag. This method is implemented in ID3v1 and ID3v2 tags.
Zwracane wartości
Returns the comment string
KTaglib_Tag::getGenre
(0.0.1)
KTaglib_Tag::getGenre — Returns the genre from a ID3 tag
Opis
Returns the genre of an ID3 tag. This method is implemented in ID3v1 and ID3v2 tags.
Zwracane wartości
Returns the genre string
KTaglib_Tag::getTitle
(0.0.1)
KTaglib_Tag::getTitle — Returns the title string from a ID3 tag
Opis
Returns the title string of an ID3 tag. This method is implemented in ID3v1 and ID3v2 tags.
Zwracane wartości
Returns the title string
KTaglib_Tag::getTrack
(0.0.1)
KTaglib_Tag::getTrack — Returns the track number from a ID3 tag
Opis
Returns the track number of an ID3 tag. This method is implemented in ID3v1 and ID3v2 tags.
Zwracane wartości
Returns the track number as an integer
KTaglib_Tag::getYear
(0.0.1)
KTaglib_Tag::getYear — Returns the year from a ID3 tag
Opis
Returns the year of an ID3 tag. This method is implemented in ID3v1 and ID3v2 tags.
Zwracane wartości
Returns the year as an integer
KTaglib_Tag::isEmpty
(0.0.1)
KTaglib_Tag::isEmpty — Returns true if the tag is empty
Opis
Returns true if the tag exists, but is empty. This method is implemented in ID3v1 and ID3v2 tags.
Zwracane wartości
Returns true if the tag is empty, otherwise false.
Spis treści
- KTaglib_Tag::getAlbum — Returns the title string from a ID3 tag
- KTaglib_Tag::getArtist — Returns the artist string from a ID3 tag
- KTaglib_Tag::getComment — Returns the comment from a ID3 tag
- KTaglib_Tag::getGenre — Returns the genre from a ID3 tag
- KTaglib_Tag::getTitle — Returns the title string from a ID3 tag
- KTaglib_Tag::getTrack — Returns the track number from a ID3 tag
- KTaglib_Tag::getYear — Returns the year from a ID3 tag
- KTaglib_Tag::isEmpty — Returns true if the tag is empty
The KTaglib_ID3v2_Tag class
(No version information available, might only be in SVN)
Wstęp
Represents and ID3v2 tag. It provides a list of ID3v2 frames and can be used to add and remove additional frames.
Class synopsis
KTaglib_ID3v2_Tag::addFrame
(0.0.1)
KTaglib_ID3v2_Tag::addFrame — Add a frame to the ID3v2 tag
Opis
Adds a frame to the ID3v2 tag. The frame must be a valid KTaglib_ID3v2_Frame object. To save the tag, the save function needs to be invoked.
Zwracane wartości
Returns true on success, otherwise false.
KTaglib_ID3v2_Tag::getFrameList
(0.0.1)
KTaglib_ID3v2_Tag::getFrameList — Returns an array of ID3v2 frames, associated with the ID3v2 tag
Opis
Returns an array of ID3v2 frames, associated with the ID3v2 tag.
Zwracane wartości
Return an array of KTaglib_ID3v2_Frame objects
Spis treści
- KTaglib_ID3v2_Tag::addFrame — Add a frame to the ID3v2 tag
- KTaglib_ID3v2_Tag::getFrameList — Returns an array of ID3v2 frames, associated with the ID3v2 tag
The KTaglib_ID3v2_Frame class
(No version information available, might only be in SVN)
Wstęp
The base class for ID3v2 frames. ID3v2 tags are separated in various specialized frames. Some frames can exists multiple times.
Class synopsis
KTaglib_ID3v2_Frame::getSize
(0.0.1)
KTaglib_ID3v2_Frame::getSize — Returns the size of the frame in bytes
Opis
Returns the size of the frame in bytes. Please refer to id3.org to see what ID3v2 frames are and how they are defined.
Zwracane wartości
Returns the size of the frame in bytes
KTaglib_ID3v2_Frame::__toString
(0.0.1)
KTaglib_ID3v2_Frame::__toString — Returns a string representation of the frame
Opis
Returns a string representation of the frame. This might be just the frame id, but might contain more information. Please see the ktaglib documentation for more information
Zwracane wartości
Returns a string representation of the frame.
Spis treści
- KTaglib_ID3v2_Frame::getSize — Returns the size of the frame in bytes
- KTaglib_ID3v2_Frame::__toString — Returns a string representation of the frame
The KTaglib_ID3v2_AttachedPictureFrame class
(No version information available, might only be in SVN)
Wstęp
Represents an ID3v2 frame that can hold a picture.
Class synopsis
KTaglib_ID3v2_AttachedPictureFrame::getDescription
(0.0.1)
KTaglib_ID3v2_AttachedPictureFrame::getDescription — Returns a description for the picture in a picture frame
Opis
Returns the attached description for a picture frame in an ID3v2.x frame.
Zwracane wartości
Returns a description for the picture in a picture frame
KTaglib_ID3v2_AttachedPictureFrame::getMimeType
(0.2.0)
KTaglib_ID3v2_AttachedPictureFrame::getMimeType — Returns the mime type of the picture
Opis
Returns the mime type of the image represented by the attached picture frame.
Please notice that this method might return different types. While ID3v2.2 have a mime type that doesn't start with "image/", ID3v2.3 and v2.4 usually start with "image/". Therefore the method might return "image/png" for IDv2.3 frames and just "PNG" for ID3v2.2 frames.
Notice that even the frame is an attached picture, the mime type might not be set and therefore an empty string might be returned.
Zwracane wartości
Returns the mime type of the image represented by the attached picture frame.
KTaglib_ID3v2_AttachedPictureFrame::getType
(0.2.0)
KTaglib_ID3v2_AttachedPictureFrame::getType — Returns the type of the image
Opis
Returns the type of the image.
The ID3v2 specification allows an AttachedPictureFrame to set the type of an image. This can be e.g. FrontCover or FileIcon. Please refer to the KTaglib_ID3v2_AttachedPictureFrame class description for a list of available types.
Zwracane wartości
Returns the integer representation of the type.
KTaglib_ID3v2_AttachedPictureFrame::savePicture
(0.0.1)
KTaglib_ID3v2_AttachedPictureFrame::savePicture — Saves the picture to a file
Opis
$filename
)Saves the attached picture to the given filename.
Zwracane wartości
Returns true on success, otherwise false
KTaglib_ID3v2_AttachedPictureFrame::setMimeType
(0.2.0)
KTaglib_ID3v2_AttachedPictureFrame::setMimeType — Set's the mime type of the picture
Opis
Sets the mime type of the image. This should in most cases be "image/png" or "image/jpeg".
KTaglib_ID3v2_AttachedPictureFrame::setPicture
(0.0.1)
KTaglib_ID3v2_AttachedPictureFrame::setPicture — Sets the frame picture to the given image
Opis
$filename
)Sets the picture to the give image. The image is loaded from the given filename. Please note that the picture is not saved unless you call the save method of the corresponding file object.
Zwracane wartości
Returns true on success, otherwise false
KTaglib_ID3v2_AttachedPictureFrame::setType
(0.2.0)
KTaglib_ID3v2_AttachedPictureFrame::setType — Set the type of the image
Opis
$type
)Sets the type of the image. This can be e.g. FrontCover or FileIcon. Please refer to the KTaglib_ID3v2_AttachedPictureFrame class description for a list of available types and their constant mappings.
Spis treści
- KTaglib_ID3v2_AttachedPictureFrame::getDescription — Returns a description for the picture in a picture frame
- KTaglib_ID3v2_AttachedPictureFrame::getMimeType — Returns the mime type of the picture
- KTaglib_ID3v2_AttachedPictureFrame::getType — Returns the type of the image
- KTaglib_ID3v2_AttachedPictureFrame::savePicture — Saves the picture to a file
- KTaglib_ID3v2_AttachedPictureFrame::setMimeType — Set's the mime type of the picture
- KTaglib_ID3v2_AttachedPictureFrame::setPicture — Sets the frame picture to the given image
- KTaglib_ID3v2_AttachedPictureFrame::setType — Set the type of the image
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- KTaglib_MPEG_File — The KTaglib_MPEG_File class
- KTaglib_MPEG_File::__construct — Opens a new file
- KTaglib_MPEG_File::getAudioProperties — Returns an object that provides access to the audio properties
- KTaglib_MPEG_File::getID3v1Tag — Returns an object representing an ID3v1 tag
- KTaglib_MPEG_File::getID3v2Tag — Returns a ID3v2 object
- KTaglib_MPEG_AudioProperties — The KTaglib_MPEG_AudioProperties class
- KTaglib_MPEG_AudioProperties::getBitrate — Returns the bitrate of the MPEG file
- KTaglib_MPEG_AudioProperties::getChannels — Returns the amount of channels of a MPEG file
- KTaglib_MPEG_AudioProperties::getLayer — Returns the layer of a MPEG file
- KTaglib_MPEG_AudioProperties::getLength — Returns the length of a MPEG file
- KTaglib_MPEG_AudioProperties::getSampleBitrate — Returns the sample bitrate of a MPEG file
- KTaglib_MPEG_AudioProperties::getVersion — Returns the version of a MPEG file
- KTaglib_MPEG_AudioProperties::isCopyrighted — Returns the length of a MPEG file
- KTaglib_MPEG_AudioProperties::isOriginal — Returns if the file is marked as the original file
- KTaglib_MPEG_AudioProperties::isProtectionEnabled — Returns the length of a MPEG file
- KTaglib_Tag — The KTaglib_Tag class
- KTaglib_Tag::getAlbum — Returns the title string from a ID3 tag
- KTaglib_Tag::getArtist — Returns the artist string from a ID3 tag
- KTaglib_Tag::getComment — Returns the comment from a ID3 tag
- KTaglib_Tag::getGenre — Returns the genre from a ID3 tag
- KTaglib_Tag::getTitle — Returns the title string from a ID3 tag
- KTaglib_Tag::getTrack — Returns the track number from a ID3 tag
- KTaglib_Tag::getYear — Returns the year from a ID3 tag
- KTaglib_Tag::isEmpty — Returns true if the tag is empty
- KTaglib_ID3v2_Tag — The KTaglib_ID3v2_Tag class
- KTaglib_ID3v2_Tag::addFrame — Add a frame to the ID3v2 tag
- KTaglib_ID3v2_Tag::getFrameList — Returns an array of ID3v2 frames, associated with the ID3v2 tag
- KTaglib_ID3v2_Frame — The KTaglib_ID3v2_Frame class
- KTaglib_ID3v2_Frame::getSize — Returns the size of the frame in bytes
- KTaglib_ID3v2_Frame::__toString — Returns a string representation of the frame
- KTaglib_ID3v2_AttachedPictureFrame — The KTaglib_ID3v2_AttachedPictureFrame class
- KTaglib_ID3v2_AttachedPictureFrame::getDescription — Returns a description for the picture in a picture frame
- KTaglib_ID3v2_AttachedPictureFrame::getMimeType — Returns the mime type of the picture
- KTaglib_ID3v2_AttachedPictureFrame::getType — Returns the type of the image
- KTaglib_ID3v2_AttachedPictureFrame::savePicture — Saves the picture to a file
- KTaglib_ID3v2_AttachedPictureFrame::setMimeType — Set's the mime type of the picture
- KTaglib_ID3v2_AttachedPictureFrame::setPicture — Sets the frame picture to the given image
- KTaglib_ID3v2_AttachedPictureFrame::setType — Set the type of the image
OGG/Vorbis
Wstęp
The OGG/Vorbis file format, as defined by » http://www.vorbis.com/, is a scheme for compressing audio streams by multiple factors with a minimum of quality loss. This extension adds Ogg Vorbis support to PHP's URL Wrappers. When used in read mode, compressed OGG/Vorbis data is expanded to raw PCM audio in one of six PCM encoding formats listed below.
Instalacja/Konfiguracja
Spis treści
Instalacja
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/oggvorbis
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
| Constant | Definition |
|---|---|
OGGVORBIS_PCM_U8 |
Unsigned 8-bit PCM. |
OGGVORBIS_PCM_S8 |
Signed 8-bit PCM. |
OGGVORBIS_PCM_U16_LE |
Unsigned 16-bit PCM. Little Endian byte order. |
OGGVORBIS_PCM_U16_BE |
Unsigned 16-bit PCM. Big Endian byte order. |
OGGVORBIS_PCM_S16_LE |
Signed 16-bit PCM. Little Endian byte order. |
OGGVORBIS_PCM_S16_BE |
Signed 16-bit PCM. Big Endian byte order. |
Context options
| Option | Definition | Relevance | Default |
|---|---|---|---|
| pcm_mode | PCM byte encoding used. See constants below. | Read / Write | OGGVORBIS_PCM_S16_LE |
| rate | PCM Sampling rate. Measured in Hz. | Write only | 44100 |
| bitrate | Vorbis Average Bitrate Encoding / Variable Bitrate Encoding. Measured in bps (ABR) or Quality level (VBR: 0.0 to 1.0). 128000 ABR is rough equal to 0.4 VBR. | Write only | 128000 |
| channels | Number of PCM channels. 1 == Mono, 2 == Stereo. | Write only | 2 |
| serialno | Serial Number of stream within file. Must be unique within file. Because of the potential to select a duplicate serial number within a chained file, make efforts to manually assign unique numbers when encoding. | Write only | Random |
| comments | Associative array of file comments. Will be translated to strtoupper($name) . "=$value". Note: This context option is not available in oggvorbis-0.1 | Write only | array('ENCODER' => 'PHP/OggVorbis, http://pear.php.net/oggvorbis') |
Przykłady
Spis treści
Examples on using the ogg:// wrapper.
Przykład #1 Reading an OGG/Vorbis file
<?php
dl("oggvorbis.so");
/* By default, ogg:// will decode to Signed 16-bit Little Endian */
$fp = fopen('ogg://myaudio.ogg', 'r');
/* Collect some information about the file. */
$metadata = stream_get_meta_data($fp);
/* Inspect the first song (usually the only song,
but OGG/Vorbis files may be chained) */
$songdata = $metadata['wrapper_data'][0];
echo "OGG/Vorbis file encoded by: {$songdata['vendor']}\n.";
echo " {$songdata['channels']} channels of {$songdata['rate']}Hz sampling encoded at {$songdata['bitrate_nominal']}bps.\n";
foreach($songdata['comments'] as $comment) {
echo " $comment\n";
}
while ($audio_data = fread($fp, 8192)) {
/* Do something with the PCM audio we're extracting from the OGG.
Copying to /dev/dsp is a good target on linux systems,
just remember to setup the device for your sampling mode first. */
}
fclose($fp);
?>
Przykład #2 Encode an audio file to OGG/Vorbis
<?php
dl('oggvorbis.so');
$context = stream_context_create(array('ogg'=>array(
'pcm_mode' => OGGVORBIS_PCM_S8, /* Signed 8bit audio */
'rate' => 44100, /* 44kHz CD quality */
'bitrate' => 0.5, /* Midquality VBR */
'channels' => 1, /* Mono */
'serialno' => 12345))); /* Unique within our stream */
/* Open file for appending. This will "chain" a second OGG stream at the end of the first. */
$ogg = fopen('ogg://mysong.ogg', 'a', false, $context);
$pcm = fopen('mysample.pcm', 'r');
/* Compress the raw PCM audio from mysample.pcm into mysong.ogg */
stream_copy_to_stream($pcm, $ogg);
fclose($pcm);
fclose($ogg);
?>
OpenAL Audio Bindings
Instalacja/Konfiguracja
Spis treści
Wymagania
Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.
Instalacja
To rozszerzenie » PECL nie jest dołączane do PHP.
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/openal.
DLL z tym rozszerzeniem PECL można pobrać zarówno ze strony » PHP Downloads lub z » http://pecl4win.php.net/
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
This extension defines four resource types: Open AL(Device) - Returned by openal_device_open(), Open AL(Context) - Returned by openal_context_create(), Open AL(Buffer) - Returned by openal_buffer_create(), and Open AL(Source) - Returned by openal_source_create().
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
-
ALC_FREQUENCY(integer) - Context Attribute
-
ALC_REFRESH(integer) - Context Attribute
-
ALC_SYNC(integer) - Context Attribute
-
AL_FREQUENCY(integer) - Buffer Setting
-
AL_BITS(integer) - Buffer Setting
-
AL_CHANNELS(integer) - Buffer Setting
-
AL_SIZE(integer) - Buffer Setting
-
AL_BUFFER(integer) - Source/Listener Setting (Integer)
-
AL_SOURCE_RELATIVE(integer) - Source/Listener Setting (Integer)
-
AL_SOURCE_STATE(integer) - Source/Listener Setting (Integer)
-
AL_PITCH(integer) - Source/Listener Setting (Float)
-
AL_GAIN(integer) - Source/Listener Setting (Float)
-
AL_MIN_GAIN(integer) - Source/Listener Setting (Float)
-
AL_MAX_GAIN(integer) - Source/Listener Setting (Float)
-
AL_MAX_DISTANCE(integer) - Source/Listener Setting (Float)
-
AL_ROLLOFF_FACTOR(integer) - Source/Listener Setting (Float)
-
AL_CONE_OUTER_GAIN(integer) - Source/Listener Setting (Float)
-
AL_CONE_INNER_ANGLE(integer) - Source/Listener Setting (Float)
-
AL_CONE_OUTER_ANGLE(integer) - Source/Listener Setting (Float)
-
AL_REFERENCE_DISTANCE(integer) - Source/Listener Setting (Float)
-
AL_POSITION(integer) - Source/Listener Setting (Float Vector)
-
AL_VELOCITY(integer) - Source/Listener Setting (Float Vector)
-
AL_DIRECTION(integer) - Source/Listener Setting (Float Vector)
-
AL_ORIENTATION(integer) - Source/Listener Setting (Float Vector)
-
AL_FORMAT_MONO8(integer) - PCM Format
-
AL_FORMAT_MONO16(integer) - PCM Format
-
AL_FORMAT_STEREO8(integer) - PCM Format
-
AL_FORMAT_STEREO16(integer) - PCM Format
-
AL_INITIAL(integer) - Source State
-
AL_PLAYING(integer) - Source State
-
AL_PAUSED(integer) - Source State
-
AL_STOPPED(integer) - Source State
-
AL_LOOPING(integer) - Source State
-
AL_TRUE(integer) - Boolean value recognized by OpenAL
-
AL_FALSE(integer) - Boolean value recognized by OpenAL
OpenAL Funkcje
openal_buffer_create
(PECL openal >= 0.1.0)
openal_buffer_create — Generate OpenAL buffer
Opis
Zwracane wartości
Returns an Open AL(Buffer) resource on success or
FALSE on failure.
Zobacz też:
- openal_buffer_loadwav() - Load a .wav file into a buffer
- openal_buffer_data() - Load a buffer with data
openal_buffer_data
(PECL openal >= 0.1.0)
openal_buffer_data — Load a buffer with data
Opis
$buffer
, int $format
, string $data
, int $freq
)Parametry
-
buffer -
An Open AL(Buffer) resource (previously created by openal_buffer_create()).
-
format -
Format of
data, one of:AL_FORMAT_MONO8,AL_FORMAT_MONO16,AL_FORMAT_STEREO8iAL_FORMAT_STEREO16 -
data -
Block of binary audio data in the
formatandfreqspecified. -
freq -
Frequency of
datagiven in Hz.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- openal_buffer_loadwav() - Load a .wav file into a buffer
- openal_stream() - Begin streaming on a source
openal_buffer_destroy
(PECL openal >= 0.1.0)
openal_buffer_destroy — Destroys an OpenAL buffer
Opis
$buffer
)Parametry
-
buffer -
An Open AL(Buffer) resource (previously created by openal_buffer_create()).
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
openal_buffer_get
(PECL openal >= 0.1.0)
openal_buffer_get — Retrieve an OpenAL buffer property
Opis
$buffer
, int $property
)Parametry
-
buffer -
An Open AL(Buffer) resource (previously created by openal_buffer_create()).
-
property -
Specific property, one of:
AL_FREQUENCY,AL_BITS,AL_CHANNELSiAL_SIZE.
Zwracane wartości
Returns an integer value appropriate to the property
requested lub FALSE w przypadku niepowodzenia.
openal_buffer_loadwav
(PECL openal >= 0.1.0)
openal_buffer_loadwav — Load a .wav file into a buffer
Opis
$buffer
, string $wavfile
)Parametry
-
buffer -
An Open AL(Buffer) resource (previously created by openal_buffer_create()).
-
wavfile -
Path to .wav file on local file system.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- openal_buffer_data() - Load a buffer with data
- openal_stream() - Begin streaming on a source
openal_context_create
(PECL openal >= 0.1.0)
openal_context_create — Create an audio processing context
Opis
$device
)Parametry
-
device -
An Open AL(Device) resource (previously created by openal_device_open()).
Zwracane wartości
Returns an Open AL(Context) resource on success or
FALSE on failure.
Zobacz też:
- openal_device_open() - Initialize the OpenAL audio layer
- openal_context_destroy() - Destroys a context
openal_context_current
(PECL openal >= 0.1.0)
openal_context_current — Make the specified context current
Opis
$context
)Parametry
-
context -
An Open AL(Context) resource (previously created by openal_context_create()).
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
openal_context_destroy
(PECL openal >= 0.1.0)
openal_context_destroy — Destroys a context
Opis
$context
)Parametry
-
context -
An Open AL(Context) resource (previously created by openal_context_create()).
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
openal_context_process
(PECL openal >= 0.1.0)
openal_context_process — Process the specified context
Opis
$context
)Parametry
-
context -
An Open AL(Context) resource (previously created by openal_context_create()).
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- openal_context_create() - Create an audio processing context
- openal_context_current() - Make the specified context current
- openal_context_suspend() - Suspend the specified context
openal_context_suspend
(PECL openal >= 0.1.0)
openal_context_suspend — Suspend the specified context
Opis
$context
)Parametry
-
context -
An Open AL(Context) resource (previously created by openal_context_create()).
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- openal_context_create() - Create an audio processing context
- openal_context_current() - Make the specified context current
- openal_context_process() - Process the specified context
openal_device_close
(PECL openal >= 0.1.0)
openal_device_close — Close an OpenAL device
Opis
$device
)Parametry
-
device -
An Open AL(Device) resource (previously created by openal_device_open()) to be closed.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
openal_device_open
(PECL openal >= 0.1.0)
openal_device_open — Initialize the OpenAL audio layer
Opis
$device_desc
] )Parametry
-
device_desc -
Open an audio device optionally specified by
device_desc. Ifdevice_descis not specified the first available audio device will be used.
Zwracane wartości
Returns an Open AL(Device) resource on success or
FALSE on failure.
Zobacz też:
- openal_device_close() - Close an OpenAL device
- openal_context_create() - Create an audio processing context
openal_listener_get
(PECL openal >= 0.1.0)
openal_listener_get — Retrieve a listener property
Opis
Parametry
-
property -
Property to retrieve, one of:
AL_GAIN(float),AL_POSITION(array(float,float,float)),AL_VELOCITY(array(float,float,float)) iAL_ORIENTATION(array(float,float,float)).
Zwracane wartości
Returns a float or array of floats (as appropriate) lub FALSE w przypadku niepowodzenia.
openal_listener_set
(PECL openal >= 0.1.0)
openal_listener_set — Set a listener property
Opis
Parametry
-
property -
Property to set, one of:
AL_GAIN(float),AL_POSITION(array(float,float,float)),AL_VELOCITY(array(float,float,float)) iAL_ORIENTATION(array(float,float,float)). -
setting -
Value to set, either float, or an array of floats as appropriate.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
openal_source_create
(PECL openal >= 0.1.0)
openal_source_create — Generate a source resource
Opis
Zwracane wartości
Returns an Open AL(Source) resource on success or
FALSE on failure.
Zobacz też:
- openal_source_set() - Set source property
- openal_source_play() - Start playing the source
- openal_source_destroy() - Destroy a source resource
openal_source_destroy
(PECL openal >= 0.1.0)
openal_source_destroy — Destroy a source resource
Opis
$source
)Parametry
-
source -
An Open AL(Source) resource (previously created by openal_source_create()).
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
openal_source_get
(PECL openal >= 0.1.0)
openal_source_get — Retrieve an OpenAL source property
Opis
Parametry
-
source -
An Open AL(Source) resource (previously created by openal_source_create()).
-
property -
Property to get, one of:
AL_SOURCE_RELATIVE(int),AL_SOURCE_STATE(int),AL_PITCH(float),AL_GAIN(float),AL_MIN_GAIN(float),AL_MAX_GAIN(float),AL_MAX_DISTANCE(float),AL_ROLLOFF_FACTOR(float),AL_CONE_OUTER_GAIN(float),AL_CONE_INNER_ANGLE(float),AL_CONE_OUTER_ANGLE(float),AL_REFERENCE_DISTANCE(float),AL_POSITION(array(float,float,float)),AL_VELOCITY(array(float,float,float)),AL_DIRECTION(array(float,float,float)).
Zwracane wartości
Returns the type associated with the property being retrieved
lub FALSE w przypadku niepowodzenia.
Zobacz też:
- openal_source_create() - Generate a source resource
- openal_source_set() - Set source property
- openal_source_play() - Start playing the source
openal_source_pause
(PECL openal >= 0.1.0)
openal_source_pause — Pause the source
Opis
$source
)Parametry
-
source -
An Open AL(Source) resource (previously created by openal_source_create()).
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- openal_source_stop() - Stop playing the source
- openal_source_play() - Start playing the source
- openal_source_rewind() - Rewind the source
openal_source_play
(PECL openal >= 0.1.0)
openal_source_play — Start playing the source
Opis
$source
)Parametry
-
source -
An Open AL(Source) resource (previously created by openal_source_create()).
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- openal_source_stop() - Stop playing the source
- openal_source_pause() - Pause the source
- openal_source_rewind() - Rewind the source
openal_source_rewind
(PECL openal >= 0.1.0)
openal_source_rewind — Rewind the source
Opis
$source
)Parametry
-
source -
An Open AL(Source) resource (previously created by openal_source_create()).
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- openal_source_stop() - Stop playing the source
- openal_source_pause() - Pause the source
- openal_source_play() - Start playing the source
openal_source_set
(PECL openal >= 0.1.0)
openal_source_set — Set source property
Opis
Parametry
-
source -
An Open AL(Source) resource (previously created by openal_source_create()).
-
property -
Property to set, one of:
AL_BUFFER(OpenAL(Source)),AL_LOOPING(bool),AL_SOURCE_RELATIVE(int),AL_SOURCE_STATE(int),AL_PITCH(float),AL_GAIN(float),AL_MIN_GAIN(float),AL_MAX_GAIN(float),AL_MAX_DISTANCE(float),AL_ROLLOFF_FACTOR(float),AL_CONE_OUTER_GAIN(float),AL_CONE_INNER_ANGLE(float),AL_CONE_OUTER_ANGLE(float),AL_REFERENCE_DISTANCE(float),AL_POSITION(array(float,float,float)),AL_VELOCITY(array(float,float,float)),AL_DIRECTION(array(float,float,float)). -
setting -
Value to assign to specified
property. Refer to the description ofpropertyfor a description of the value(s) expected.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- openal_source_create() - Generate a source resource
- openal_source_get() - Retrieve an OpenAL source property
- openal_source_play() - Start playing the source
openal_source_stop
(PECL openal >= 0.1.0)
openal_source_stop — Stop playing the source
Opis
$source
)Parametry
-
source -
An Open AL(Source) resource (previously created by openal_source_create()).
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- openal_source_play() - Start playing the source
- openal_source_pause() - Pause the source
- openal_source_rewind() - Rewind the source
openal_stream
(PECL openal >= 0.1.0)
openal_stream — Begin streaming on a source
Opis
$source
, int $format
, int $rate
)Parametry
-
source -
An Open AL(Source) resource (previously created by openal_source_create()).
-
format -
Format of
data, one of:AL_FORMAT_MONO8,AL_FORMAT_MONO16,AL_FORMAT_STEREO8iAL_FORMAT_STEREO16 -
rate -
Frequency of data to stream given in Hz.
Zwracane wartości
Returns a stream resource on success lub FALSE w przypadku niepowodzenia.
Zobacz też:
- openal_source_create() - Generate a source resource
- fwrite() - Zapis pliku binarnie bezpieczny
Spis treści
- openal_buffer_create — Generate OpenAL buffer
- openal_buffer_data — Load a buffer with data
- openal_buffer_destroy — Destroys an OpenAL buffer
- openal_buffer_get — Retrieve an OpenAL buffer property
- openal_buffer_loadwav — Load a .wav file into a buffer
- openal_context_create — Create an audio processing context
- openal_context_current — Make the specified context current
- openal_context_destroy — Destroys a context
- openal_context_process — Process the specified context
- openal_context_suspend — Suspend the specified context
- openal_device_close — Close an OpenAL device
- openal_device_open — Initialize the OpenAL audio layer
- openal_listener_get — Retrieve a listener property
- openal_listener_set — Set a listener property
- openal_source_create — Generate a source resource
- openal_source_destroy — Destroy a source resource
- openal_source_get — Retrieve an OpenAL source property
- openal_source_pause — Pause the source
- openal_source_play — Start playing the source
- openal_source_rewind — Rewind the source
- openal_source_set — Set source property
- openal_source_stop — Stop playing the source
- openal_stream — Begin streaming on a source
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- OpenAL Funkcje
- openal_buffer_create — Generate OpenAL buffer
- openal_buffer_data — Load a buffer with data
- openal_buffer_destroy — Destroys an OpenAL buffer
- openal_buffer_get — Retrieve an OpenAL buffer property
- openal_buffer_loadwav — Load a .wav file into a buffer
- openal_context_create — Create an audio processing context
- openal_context_current — Make the specified context current
- openal_context_destroy — Destroys a context
- openal_context_process — Process the specified context
- openal_context_suspend — Suspend the specified context
- openal_device_close — Close an OpenAL device
- openal_device_open — Initialize the OpenAL audio layer
- openal_listener_get — Retrieve a listener property
- openal_listener_set — Set a listener property
- openal_source_create — Generate a source resource
- openal_source_destroy — Destroy a source resource
- openal_source_get — Retrieve an OpenAL source property
- openal_source_pause — Pause the source
- openal_source_play — Start playing the source
- openal_source_rewind — Rewind the source
- openal_source_set — Set source property
- openal_source_stop — Stop playing the source
- openal_stream — Begin streaming on a source
- ID3 — Tagi ID3
- KTaglib
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- KTaglib_MPEG_File — The KTaglib_MPEG_File class
- KTaglib_MPEG_AudioProperties — The KTaglib_MPEG_AudioProperties class
- KTaglib_Tag — The KTaglib_Tag class
- KTaglib_ID3v2_Tag — The KTaglib_ID3v2_Tag class
- KTaglib_ID3v2_Frame — The KTaglib_ID3v2_Frame class
- KTaglib_ID3v2_AttachedPictureFrame — The KTaglib_ID3v2_AttachedPictureFrame class
- oggvorbis — OGG/Vorbis
- OpenAL — OpenAL Audio Bindings
Serwisy uwierzytelnienia
Kerberos V
Wstęp
These package allows you to access Kerberos V administration servers. You can create, modify, and delete Kerberos V principals and policies.
More information about Kerberos can be found at » http://web.mit.edu/kerberos/www/.
Documentation for Kerberos and KADM5 can be found at » http://web.mit.edu/kerberos/www/krb5-1.2/krb5-1.2.8/doc/admin_toc.html.
Instalacja/Konfiguracja
Spis treści
Wymagania
Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.
Instalacja
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/kadm5.
Informacja:
If this option is used without specifying the path to KADM5, PHP will use the built-in KADM5 client libraries. Users who run other applications that use KADM5 (for example, running PHP 4 and PHP 5 as concurrent apache modules, or auth-kadm5) should always specify the path to KADM5: --with-kadm5=/path/to/kadm5. This will force PHP to use the client libraries installed by KADM5, avoiding any conflicts.
DLL z tym rozszerzeniem PECL można pobrać zarówno ze strony » PHP Downloads lub z » http://pecl4win.php.net/
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Stałe predefiniowane
Spis treści
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
Constants for Attribute Flags
The functions kadm5_create_principal(), kadm5_modify_principal(), and kadm5_modify_principal() allow to specify special attributes using a bitfield. The symbols are defined below:
| constant |
|---|
| KRB5_KDB_DISALLOW_POSTDATED |
| KRB5_KDB_DISALLOW_FORWARDABLE |
| KRB5_KDB_DISALLOW_TGT_BASED |
| KRB5_KDB_DISALLOW_RENEWABLE |
| KRB5_KDB_DISALLOW_PROXIABLE |
| KRB5_KDB_DISALLOW_DUP_SKEY |
| KRB5_KDB_DISALLOW_ALL_TIX |
| KRB5_KDB_REQUIRES_PRE_AUTH |
| KRB5_KDB_REQUIRES_HW_AUTH |
| KRB5_KDB_REQUIRES_PWCHANGE |
| KRB5_KDB_DISALLOW_SVR |
| KRB5_KDB_PWCHANGE_SERVER |
| KRB5_KDB_SUPPORT_DESMD5 |
| KRB5_KDB_NEW_PRINC |
Constants for Options
The functions kadm5_create_principal(), kadm5_modify_principal(), and kadm5_get_principal() allow to specify or return principal's options as an associative array. The keys for the associative array are defined as string constants below:
| constant | funcdef | description |
|---|---|---|
| KADM5_PRINCIPAL | long | The expire time of the princial as a Kerberos timestamp. |
| KADM5_PRINC_EXPIRE_TIME | long | The expire time of the princial as a Kerberos timestamp. |
| KADM5_LAST_PW_CHANGE | long | The time this principal's password was last changed. |
| KADM5_PW_EXPIRATION | long | The expire time of the principal's current password, as a Kerberos timestamp. |
| KADM5_MAX_LIFE | long | The maximum lifetime of any Kerberos ticket issued to this principal. |
| KADM5_MAX_RLIFE | long | The maximum renewable lifetime of any Kerberos ticket issued to or for this principal. |
| KADM5_MOD_NAME | string | The name of the Kerberos principal that most recently modified this principal. |
| KADM5_MOD_TIME | long | The time this principal was last modified, as a Kerberos timestamp. |
| KADM5_KVNO | long | The version of the principal's current key. |
| KADM5_POLICY | string | The name of the policy controlling this principal. |
| KADM5_CLEARPOLICY | long | Standard procedure is to assign the 'default' policy to new principals. KADM5_CLEARPOLICY suppresses this behaviour. |
| KADM5_LAST_SUCCESS | long | The KDC time of the last successfull AS_REQ. |
| KADM5_LAST_FAILED | long | The KDC time of the last failed AS_REQ. |
| KADM5_FAIL_AUTH_COUNT | long | The number of consecutive failed AS_REQs. |
| KADM5_RANDKEY | long |
Generates a random password for the principal. The parameter
password will be ignored.
|
| KADM5_ATTRIBUTES | long | A bitfield of attributes for use by the KDC. |
Przykłady
Spis treści
Basic usage
This simple example shows how to connect, query, print resulting principals and disconnect from a KADM5 database.
Przykład #1 KADM5 extension overview example
<?php
$handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");
print "<h1>get_principals</h1>\n";
$principals = kadm5_get_principals($handle);
for( $i=0; $i<count($principals); $i++)
print "$principals[$i]<br>\n";
print "<h1>get_policies</h1>\n";
$policies = kadm5_get_policies($handle);
for( $i=0; $i<count($policies); $i++)
print "$policies[$i]<br>\n";
print "<h1>get_principal burbach@GONICUS.LOCAL</h1>\n";
$options = kadm5_get_principal($handle, "burbach@GONICUS.LOCAL" );
$keys = array_keys($options);
for( $i=0; $i<count($keys); $i++) {
$value = $options[$keys[$i]];
print "$keys[$i]: $value<br>\n";
}
$options = array(KADM5_PRINC_EXPIRE_TIME => 0);
kadm5_modify_principal($handle, "burbach@GONICUS.LOCAL", $options);
kadm5_destroy($handle);
?>
KADM5 Funkcje
kadm5_chpass_principal
(PECL kadm5 >= 0.2.3)
kadm5_chpass_principal — Changes the principal's password
Opis
$handle
, string $principal
, string $password
)
kadm5_chpass_principal() sets the new password
password for the principal.
Parametry
-
handle -
A KADM5 handle.
-
principal -
The principal.
-
password -
The new password.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Example of changing principal's password
<?php
$handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");
kadm5_chpass_principal($handle, "burbach@GONICUS.LOCAL", "newpassword");
kadm5_destroy($handle);
?>
kadm5_create_principal
(PECL kadm5 >= 0.2.3)
kadm5_create_principal — Creates a kerberos principal with the given parameters
Opis
$handle
, string $principal
[, string $password
[, array $options
]] )
Creates a principal with the given
password.
Parametry
-
handle -
A KADM5 handle.
-
principal -
The principal.
-
password -
If
passwordis omitted or isNULL, a random key will be generated. -
options -
It is possible to specify several optional parameters within the array
options. Allowed are the following options:KADM5_PRINC_EXPIRE_TIME,KADM5_PW_EXPIRATION,KADM5_ATTRIBUTES,KADM5_MAX_LIFE,KADM5_KVNO,KADM5_POLICY,KADM5_CLEARPOLICY,KADM5_MAX_RLIFE.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Example of principal's creation
<?php
$handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");
$attributes = KRB5_KDB_REQUIRES_PRE_AUTH | KRB5_KDB_DISALLOW_PROXIABLE;
$options = array(KADM5_PRINC_EXPIRE_TIME => 0,
KADM5_POLICY => "default",
KADM5_ATTRIBUTES => $attributes);
kadm5_create_principal($handle, "burbach@GONICUS.LOCAL", "password", $options);
kadm5_destroy($handle);
?>
Zobacz też:
- kadm5_modify_principal() - Modifies a kerberos principal with the given parameters
- kadm5_delete_principal() - Deletes a kerberos principal
kadm5_delete_principal
(PECL kadm5 >= 0.2.3)
kadm5_delete_principal — Deletes a kerberos principal
Opis
$handle
, string $principal
)
Removes the principal from the Kerberos database.
Parametry
-
handle -
A KADM5 handle.
-
principal -
The removed principal.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 kadm5_delete_principal() example
<?php
$handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");
kadm5_delete_principal($handle, "burbach@GONICUS.LOCAL");
kadm5_destroy($handle);
?>
Zobacz też:
- kadm5_modify_principal() - Modifies a kerberos principal with the given parameters
- kadm5_create_principal() - Creates a kerberos principal with the given parameters
kadm5_destroy
(PECL kadm5 >= 0.2.3)
kadm5_destroy — Closes the connection to the admin server and releases all related resources
Opis
$handle
)Closes the connection to the admin server and releases all related resources.
Parametry
-
handle -
A KADM5 handle.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
kadm5_flush
(PECL kadm5 >= 0.2.3)
kadm5_flush — Flush all changes to the Kerberos database
Opis
$handle
)Flush all changes to the Kerberos database, leaving the connection to the Kerberos admin server open.
Parametry
-
handle -
A KADM5 handle.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
kadm5_get_policies
(PECL kadm5 >= 0.2.3)
kadm5_get_policies — Gets all policies from the Kerberos database
Opis
$handle
)Gets an array containing the policies's names.
Parametry
-
handle -
A KADM5 handle.
Zwracane wartości
Returns array of policies on success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 kadm5_get_policies() example
<?php
$handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");
print "<h1>get_policies</h1>\n";
foreach (kadm5_get_policies($handle) as $policy) {
echo "$policy<br />\n";
}
kadm5_destroy($handle);
?>
kadm5_get_principal
(PECL kadm5 >= 0.2.3)
kadm5_get_principal — Gets the principal's entries from the Kerberos database
Opis
$handle
, string $principal
)Gets the principal's entries from the Kerberos database.
Parametry
-
handle -
A KADM5 handle.
-
principal -
The principal.
Zwracane wartości
Returns array of options containing the following keys: KADM5_PRINCIPAL,
KADM5_PRINC_EXPIRE_TIME, KADM5_PW_EXPIRATION, KADM5_ATTRIBUTES,
KADM5_MAX_LIFE, KADM5_MOD_NAME, KADM5_MOD_TIME, KADM5_KVNO, KADM5_POLICY,
KADM5_MAX_RLIFE, KADM5_LAST_SUCCESS, KADM5_LAST_FAILED,
KADM5_FAIL_AUTH_COUNT on success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 kadm5_get_principal() example
<?php
$handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");
print "<h1>get_principal burbach@GONICUS.LOCAL</h1>\n";
$options = kadm5_get_principal($handle, "burbach@GONICUS.LOCAL" );
foreach ($options as $key => $value) {
echo "$key: $value<br />\n";
}
kadm5_destroy($handle);
?>
kadm5_get_principals
(PECL kadm5 >= 0.2.3)
kadm5_get_principals — Gets all principals from the Kerberos database
Opis
$handle
)kadm5_get_principals() returns an array containing the principals's names.
Parametry
-
handle -
A KADM5 handle.
Zwracane wartości
Returns array of principals on success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 kadm5_get_principals() example
<?php
$handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");
print "<h1>get_principals</h1>\n";
foreach (kadm5_get_principals($handle) as $principal) {
echo "$principal<br />\n";
}
kadm5_destroy($handle);
?>
kadm5_init_with_password
(PECL kadm5 >= 0.2.3)
kadm5_init_with_password — Opens a connection to the KADM5 library
Opis
$admin_server
, string $realm
, string $principal
, string $password
)
Opens a connection with the KADM5 library using the
principal and the given
password to obtain initial credentials from the
admin_server.
Parametry
-
admin_server -
The server.
-
realm -
Defines the authentication domain for the connection.
-
principal -
The principal.
-
password -
If
passwordis omitted or isNULL, a random key will be generated.
Zwracane wartości
Returns a KADM5 handle on success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 KADM5 initialization example
<?php
$handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");
$attributes = KRB5_KDB_REQUIRES_PRE_AUTH | KRB5_KDB_DISALLOW_PROXIABLE;
$options = array(KADM5_PRINC_EXPIRE_TIME => 0,
KADM5_POLICY => "default",
KADM5_ATTRIBUTES => $attributes);
kadm5_create_principal($handle, "burbach@GONICUS.LOCAL", "password", $options);
kadm5_destroy($handle);
?>
Notatki
Informacja:
Connection should be closed after use with kadm5_destroy().
Zobacz też:
- kadm5_destroy() - Closes the connection to the admin server and releases all related resources
kadm5_modify_principal
(PECL kadm5 >= 0.2.3)
kadm5_modify_principal — Modifies a kerberos principal with the given parameters
Opis
$handle
, string $principal
, array $options
)
Modifies a principal according to the given
options.
Parametry
-
handle -
A KADM5 handle.
-
principal -
The principal.
-
options -
It is possible to specify several optional parameters within the array
options. Allowed are the following options:KADM5_PRINC_EXPIRE_TIME,KADM5_PW_EXPIRATION,KADM5_ATTRIBUTES,KADM5_MAX_LIFE,KADM5_KVNO,KADM5_POLICY,KADM5_CLEARPOLICY,KADM5_MAX_RLIFE.KADM5_FAIL_AUTH_COUNT.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Example of modifying principal
<?php
$handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");
$attributes = KRB5_KDB_REQUIRES_PRE_AUTH;
$options = array(KADM5_PRINC_EXPIRE_TIME => 3451234,
KADM5_POLICY => "gonicus",
KADM5_ATTRIBUTES => $attributes);
kadm5_modify_principal($handle, "burbach@GONICUS.LOCAL", $options);
kadm5_destroy($handle);
?>
Zobacz też:
- kadm5_create_principal() - Creates a kerberos principal with the given parameters
- kadm5_delete_principal() - Deletes a kerberos principal
Spis treści
- kadm5_chpass_principal — Changes the principal's password
- kadm5_create_principal — Creates a kerberos principal with the given parameters
- kadm5_delete_principal — Deletes a kerberos principal
- kadm5_destroy — Closes the connection to the admin server and releases all related resources
- kadm5_flush — Flush all changes to the Kerberos database
- kadm5_get_policies — Gets all policies from the Kerberos database
- kadm5_get_principal — Gets the principal's entries from the Kerberos database
- kadm5_get_principals — Gets all principals from the Kerberos database
- kadm5_init_with_password — Opens a connection to the KADM5 library
- kadm5_modify_principal — Modifies a kerberos principal with the given parameters
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Przykłady
- KADM5 Funkcje
- kadm5_chpass_principal — Changes the principal's password
- kadm5_create_principal — Creates a kerberos principal with the given parameters
- kadm5_delete_principal — Deletes a kerberos principal
- kadm5_destroy — Closes the connection to the admin server and releases all related resources
- kadm5_flush — Flush all changes to the Kerberos database
- kadm5_get_policies — Gets all policies from the Kerberos database
- kadm5_get_principal — Gets the principal's entries from the Kerberos database
- kadm5_get_principals — Gets all principals from the Kerberos database
- kadm5_init_with_password — Opens a connection to the KADM5 library
- kadm5_modify_principal — Modifies a kerberos principal with the given parameters
Radius
Wstęp
This package is based on the libradius (Remote Authentication Dial In User Service) of FreeBSD. It allows clients to perform authentication and accounting by means of network requests to remote servers.
This PECL extension adds full support for Radius Authentication (» RFC 2865) and Radius Accounting (» RFC 2866). This package is available for Unix (tested on FreeBSD and Linux) and for Windows.
Informacja:
An exact description for libradius can be found » here. A detailed description of the configuration file can be found » here.
Instalacja/Konfiguracja
Spis treści
Wymagania
Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.
Instalacja
To rozszerzenie » PECL nie jest dołączane do PHP.
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/radius.
DLL z tym rozszerzeniem PECL można pobrać zarówno ze strony » PHP Downloads lub z » http://pecl4win.php.net/
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
-
RADIUS_ACCESS_REQUEST() - Authentication Request
-
RADIUS_ACCESS_ACCEPT() - Access accepted
-
RADIUS_ACCESS_REJECT() - Access rejected
-
RADIUS_ACCOUNTING_REQUEST() - Accounting request
-
RADIUS_ACCOUNTING_RESPONSE() - Accounting response
-
RADIUS_ACCESS_CHALLENGE() - Accsess challenge
-
RADIUS_USER_NAME(string) - Username
-
RADIUS_USER_PASSWORD(string) - Password
-
RADIUS_CHAP_PASSWORD(string) - Chap Password: chappass = md5(ident + plaintextpass + challenge)
-
RADIUS_NAS_IP_ADDRESS(string) - NAS IP-Adress
-
RADIUS_NAS_PORT(int) - NAS Port
-
RADIUS_SERVICE_TYPE(int) -
Type of Service, one of:
RADIUS_LOGINRADIUS_FRAMEDRADIUS_CALLBACK_LOGINRADIUS_CALLBACK_FRAMEDRADIUS_OUTBOUNDRADIUS_ADMINISTRATIVERADIUS_NAS_PROMPTRADIUS_AUTHENTICATE_ONLYRADIUS_CALLBACK_NAS_PROMPT
-
RADIUS_FRAMED_PROTOCOL(int) -
Framed Protocol, one of:
RADIUS_PPPRADIUS_SLIPRADIUS_ARAPRADIUS_GANDALFRADIUS_XYLOGICS
-
RADIUS_FRAMED_IP_ADDRESS(int) - IPv4 Internet network address
-
RADIUS_FRAMED_IP_NETMASK(string) - Netmask
-
RADIUS_FRAMED_ROUTING(int) - Routing
-
RADIUS_FILTER_ID(string) - Filter ID
-
RADIUS_FRAMED_MTU(int) - MTU
-
RADIUS_FRAMED_COMPRESSION(int) -
Compression, one of:
RADIUS_COMP_NONERADIUS_COMP_VJRADIUS_COMP_IPXHDR
-
RADIUS_LOGIN_IP_HOST(string) - Login IP Host
-
RADIUS_LOGIN_SERVICE(int) - Login Service
-
RADIUS_LOGIN_TCP_PORT(int) - Login TCP Port
-
RADIUS_REPLY_MESSAGE(string) - Reply Message
-
RADIUS_CALLBACK_NUMBER(string) - Callback Number
-
RADIUS_CALLBACK_ID(string) - Callback ID
-
RADIUS_FRAMED_ROUTE(string) - Framed Route
-
RADIUS_FRAMED_IPX_NETWORK(string) - Framed IPX Network
-
RADIUS_STATE(string) - State
-
RADIUS_CLASS(int) - Class
-
RADIUS_VENDOR_SPECIFIC(int) - Vendor specific attribute
-
RADIUS_SESSION_TIMEOUT(int) - Session timeout
-
RADIUS_IDLE_TIMEOUT(int) - Idle timeout
-
RADIUS_TERMINATION_ACTION(int) - Termination action
-
RADIUS_CALLED_STATION_ID(int) - Called Station Id
-
RADIUS_CALLING_STATION_ID(string) - Calling Station Id
-
RADIUS_NAS_IDENTIFIER(int) - NAS ID
-
RADIUS_PROXY_STATE(int) - Proxy State
-
RADIUS_LOGIN_LAT_SERVICE(int) - Login LAT Service
-
RADIUS_LOGIN_LAT_NODE(int) - Login LAT Node
-
RADIUS_LOGIN_LAT_GROUP(int) - Login LAT Group
-
RADIUS_FRAMED_APPLETALK_LINK(int) - Framed Appletalk Link
-
RADIUS_FRAMED_APPLETALK_NETWORK(int) - Framed Appletalk Network
-
RADIUS_FRAMED_APPLETALK_ZONE(int) - Framed Appletalk Zone
-
RADIUS_CHAP_CHALLENGE(string) - Challenge
-
RADIUS_NAS_PORT_TYPE(int) -
NAS port type, one of:
RADIUS_ASYNCRADIUS_SYNCRADIUS_ISDN_SYNCRADIUS_ISDN_ASYNC_V120RADIUS_ISDN_ASYNC_V110RADIUS_VIRTUALRADIUS_PIAFSRADIUS_HDLC_CLEAR_CHANNELRADIUS_X_25RADIUS_X_75RADIUS_G_3_FAXRADIUS_SDSLRADIUS_ADSL_CAPRADIUS_ADSL_DMTRADIUS_IDSLRADIUS_ETHERNETRADIUS_XDSLRADIUS_CABLERADIUS_WIRELESS_OTHERRADIUS_WIRELESS_IEEE_802_11
-
RADIUS_PORT_LIMIT(int) - Port Limit
-
RADIUS_LOGIN_LAT_PORT(int) - Login LAT Port
-
RADIUS_CONNECT_INFO(string) - Connect info
-
RADIUS_ACCT_STATUS_TYPE(int) -
Accounting status type, one of:
RADIUS_STARTRADIUS_STOPRADIUS_ACCOUNTING_ONRADIUS_ACCOUNTING_OFF
-
RADIUS_ACCT_DELAY_TIME(int) - Accounting delay time
-
RADIUS_ACCT_INPUT_OCTETS(int) - Accounting input bytes
-
RADIUS_ACCT_OUTPUT_OCTETS(int) - Accounting output bytes
-
RADIUS_ACCT_SESSION_ID(int) - Accounting session ID
-
RADIUS_ACCT_AUTHENTIC(int) -
Accounting authentic, one of:
RADIUS_AUTH_RADIUSRADIUS_AUTH_LOCALRADIUS_AUTH_REMOTE
-
RADIUS_ACCT_SESSION_TIME(int) - Accounting session time
-
RADIUS_ACCT_INPUT_PACKETS(int) - Accounting input packets
-
RADIUS_ACCT_OUTPUT_PACKETS(int) - Accounting output packets
-
RADIUS_ACCT_TERMINATE_CAUSE(int) -
Accounting terminate cause, one of:
RADIUS_TERM_USER_REQUESTRADIUS_TERM_LOST_CARRIERRADIUS_TERM_LOST_SERVICERADIUS_TERM_IDLE_TIMEOUTRADIUS_TERM_SESSION_TIMEOUTRADIUS_TERM_ADMIN_RESETRADIUS_TERM_ADMIN_REBOOTRADIUS_TERM_PORT_ERRORRADIUS_TERM_NAS_ERRORRADIUS_TERM_NAS_REQUESTRADIUS_TERM_NAS_REBOOTRADIUS_TERM_PORT_UNNEEDEDRADIUS_TERM_PORT_PREEMPTEDRADIUS_TERM_PORT_SUSPENDEDRADIUS_TERM_SERVICE_UNAVAILABLERADIUS_TERM_CALLBACKRADIUS_TERM_USER_ERRORRADIUS_TERM_HOST_REQUEST
-
RADIUS_ACCT_MULTI_SESSION_ID(string) - Accounting multi session ID
-
RADIUS_ACCT_LINK_COUNT(int) - Accounting link count
-
RADIUS_VENDOR_MICROSOFT(int) -
Microsoft specific vendor attributes (» RFC 2548), one of:
RADIUS_MICROSOFT_MS_CHAP_RESPONSERADIUS_MICROSOFT_MS_CHAP_ERRORRADIUS_MICROSOFT_MS_CHAP_PW_1RADIUS_MICROSOFT_MS_CHAP_PW_2RADIUS_MICROSOFT_MS_CHAP_LM_ENC_PWRADIUS_MICROSOFT_MS_CHAP_NT_ENC_PWRADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_POLICYRADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_TYPESRADIUS_MICROSOFT_MS_RAS_VENDORRADIUS_MICROSOFT_MS_CHAP_DOMAINRADIUS_MICROSOFT_MS_CHAP_CHALLENGERADIUS_MICROSOFT_MS_CHAP_MPPE_KEYSRADIUS_MICROSOFT_MS_BAP_USAGERADIUS_MICROSOFT_MS_LINK_UTILIZATION_THRESHOLDRADIUS_MICROSOFT_MS_LINK_DROP_TIME_LIMITRADIUS_MICROSOFT_MS_MPPE_SEND_KEYRADIUS_MICROSOFT_MS_MPPE_RECV_KEYRADIUS_MICROSOFT_MS_RAS_VERSIONRADIUS_MICROSOFT_MS_OLD_ARAP_PASSWORDRADIUS_MICROSOFT_MS_NEW_ARAP_PASSWORDRADIUS_MICROSOFT_MS_ARAP_PASSWORD_CHANGE_REASONRADIUS_MICROSOFT_MS_FILTERRADIUS_MICROSOFT_MS_ACCT_AUTH_TYPERADIUS_MICROSOFT_MS_ACCT_EAP_TYPERADIUS_MICROSOFT_MS_CHAP2_RESPONSERADIUS_MICROSOFT_MS_CHAP2_SUCCESSRADIUS_MICROSOFT_MS_CHAP2_PWRADIUS_MICROSOFT_MS_PRIMARY_DNS_SERVERRADIUS_MICROSOFT_MS_SECONDARY_DNS_SERVERRADIUS_MICROSOFT_MS_PRIMARY_NBNS_SERVERRADIUS_MICROSOFT_MS_SECONDARY_NBNS_SERVERRADIUS_MICROSOFT_MS_ARAP_CHALLENGE
Przykłady
Howto start?
- get a radius resource
- configure the library
- create the request
- put attributes
- send the request
- receive attributes
- close the radius resource (optional)
The package contains an example php script. This script demonstrates howto authenticate with radius using PAP or CHAP (md5). If you authenticate with Microsoft Radius servers then its not possible to use CHAP (md5). If you would like to authenticate with Microsoft Servers you have to use MS-CHAPv1 or MS-CHAPv2, but its more complicated, because you need md4, sha1 and des to generate the right data. The enclosed examples demonstrate all authentication-methods, including MS-CHAPv1 and MS-CHAPv2. To get the MS-CHAP to work you need the mcrypt and the mhash extension, starting with version 1.2 of the package, the mcrypt extension is no longer needed.
Radius Funkcje
Contact Information
If you have comments, bugfixes, enhancements or want to help to develop this you can send me a mail at » mbretter@php.net.
radius_acct_open
(PECL radius >= 1.1.0)
radius_acct_open — Creates a Radius handle for accounting
Opis
Zwracane wartości
Returns a handle on success, FALSE on error. This function only fails if
insufficient memory is available.
Przykłady
Przykład #1 radius_acct_open() example
<?php
$res = radius_acct_open ()
or die ("Could not create handle");
print("Handle successfully created");
?>
radius_add_server
(PECL radius >= 1.1.0)
radius_add_server — Adds a server
Opis
$radius_handle
, string $hostname
, int $port
, string $secret
, int $timeout
, int $max_tries
)
radius_add_server() may be called multiple times, and it
may be used together with radius_config(). At most 10
servers may be specified. When multiple servers are given, they are tried
in round-robin fashion until a valid response is received, or until each
server's max_tries limit has been reached.
Parametry
-
radius_handle -
-
hostname -
The
hostnameparameter specifies the server host, either as a fully qualified domain name or as a dotted-quad IP address in text form. -
port -
The
portspecifies the UDP port to contact on the server. If port is given as 0, the library looks up theradius/udporradacct/udpservice in the network services database, and uses the port found there. If no entry is found, the library uses the standard Radius ports, 1812 for authentication and 1813 for accounting. -
secret -
The shared secret for the server host is passed to the
secretparameter. The Radius protocol ignores all but the leading 128 bytes of the shared secret. -
timeout -
The timeout for receiving replies from the server is passed to the
timeoutparameter, in units of seconds. -
max_tries -
The maximum number of repeated requests to make before giving up is passed into the
max_tries.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 radius_add_server() example
<?php
if (!radius_add_server($res, 'radius.example.com', 1812, 'testing123', 3, 3)) {
echo 'RadiusError:' . radius_strerror($res). "\n<br>";
exit;
}
?>
radius_auth_open
(PECL radius >= 1.1.0)
radius_auth_open — Creates a Radius handle for authentication
Opis
Zwracane wartości
Returns a handle on success, FALSE on error. This function only fails if
insufficient memory is available.
Przykłady
Przykład #1 radius_auth_open() example
<?php
$radh = radius_auth_open()
or die ("Could not create handle");
echo "Handle successfully created";
?>
radius_close
(PECL radius >= 1.1.0)
radius_close — Frees all ressources
Opis
$radius_handle
)It is not needed to call this function because php frees all resources at the end of each request.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
radius_config
(PECL radius >= 1.1.0)
radius_config — Causes the library to read the given configuration file
Opis
$radius_handle
, string $file
)Before issuing any Radius requests, the library must be made aware of the servers it can contact. The easiest way to configure the library is to call radius_config(). radius_config() causes the library to read a configuration file whose format is described in » radius.conf.
Parametry
-
radius_handle -
-
file -
The pathname of the configuration file is passed as the file argument to radius_config(). The library can also be configured programmatically by calls to radius_add_server().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
radius_create_request
(PECL radius >= 1.1.0)
radius_create_request — Create accounting or authentication request
Opis
$radius_handle
, int $type
)A Radius request consists of a code specifying the kind of request, and zero or more attributes which provide additional information. To begin constructing a new request, call radius_create_request().
Informacja: Attention: You must call this function, before you can put any attribute!
Parametry
-
radius_handle -
-
type -
Type is
RADIUS_ACCESS_REQUESTorRADIUS_ACCOUNTING_REQUEST.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 radius_create_request() example
<?php
if (!radius_create_request($res, RADIUS_ACCESS_REQUEST)) {
echo 'RadiusError:' . radius_strerror($res). "\n<br />";
exit;
}
?>
radius_cvt_addr
(PECL radius >= 1.1.0)
radius_cvt_addr — Converts raw data to IP-Address
Opis
$data
)
Przykłady
Przykład #1 radius_cvt_addr() example
<?php
while ($resa = radius_get_attr($res)) {
if (!is_array($resa)) {
printf ("Error getting attribute: %s\n", radius_strerror($res));
exit;
}
$attr = $resa['attr'];
$data = $resa['data'];
switch ($attr) {
case RADIUS_FRAMED_IP_ADDRESS:
$ip = radius_cvt_addr($data);
echo "IP: $ip<br>\n";
break;
case RADIUS_FRAMED_IP_NETMASK:
$mask = radius_cvt_addr($data);
echo "MASK: $mask<br>\n";
break;
}
}
?>
Zobacz też:
- radius_cvt_int() - Converts raw data to integer
- radius_cvt_string() - Converts raw data to string
radius_cvt_int
(PECL radius >= 1.1.0)
radius_cvt_int — Converts raw data to integer
Opis
$data
)
Przykłady
Przykład #1 radius_cvt_int() example
<?php
while ($resa = radius_get_attr($res)) {
if (!is_array($resa)) {
printf ("Error getting attribute: %s\n", radius_strerror($res));
exit;
}
$attr = $resa['attr'];
$data = $resa['data'];
switch ($attr) {
case RADIUS_FRAMED_MTU:
$mtu = radius_cvt_int($data);
echo "MTU: $mtu<br>\n";
break;
}
}
?>
Zobacz też:
- radius_cvt_addr() - Converts raw data to IP-Address
- radius_cvt_string() - Converts raw data to string
radius_cvt_string
(PECL radius >= 1.1.0)
radius_cvt_string — Converts raw data to string
Opis
$data
)
Przykłady
Przykład #1 radius_cvt_string() example
<?php
while ($resa = radius_get_attr($res)) {
if (!is_array($resa)) {
printf ("Error getting attribute: %s\n", radius_strerror($res));
exit;
}
$attr = $resa['attr'];
$data = $resa['data'];
switch ($attr) {
case RADIUS_FILTER_ID:
$id = radius_cvt_string($data);
echo "Filter ID: $id<br>\n";
break;
}
}
?>
Zobacz też:
- radius_cvt_addr() - Converts raw data to IP-Address
- radius_cvt_int() - Converts raw data to integer
radius_demangle_mppe_key
(PECL radius >= 1.2.0)
radius_demangle_mppe_key — Derives mppe-keys from mangled data
Opis
$radius_handle
, string $mangled
)When using MPPE with MS-CHAPv2, the send- and recv-keys are mangled (see » RFC 2548), however this function is useless, because I don't think that there is or will be a PPTP-MPPE implementation in PHP.
Zwracane wartości
Returns the demangled string, or FALSE on error.
radius_demangle
(PECL radius >= 1.2.0)
radius_demangle — Demangles data
Opis
$radius_handle
, string $mangled
)Some data (Passwords, MS-CHAPv1 MPPE-Keys) is mangled for security reasons, and must be demangled before you can use them.
Zwracane wartości
Returns the demangled string, or FALSE on error.
radius_get_attr
(PECL radius >= 1.1.0)
radius_get_attr — Extracts an attribute
Opis
Like Radius requests, each response may contain zero or more attributes. After a response has been received successfully by radius_send_request(), its attributes can be extracted one by one using radius_get_attr(). Each time radius_get_attr() is called, it gets the next attribute from the current response.
Zwracane wartości
Returns an associative array containing the attribute-type and the data, or error number <= 0.
Przykłady
Przykład #1 radius_get_attr() example
<?php
while ($resa = radius_get_attr($res)) {
if (!is_array($resa)) {
printf("Error getting attribute: %s\n", radius_strerror($res));
exit;
}
$attr = $resa['attr'];
$data = $resa['data'];
printf("Got Attr:%d %d Bytes %s\n", $attr, strlen($data), bin2hex($data));
}
?>
Zobacz też:
- radius_put_attr() - Attaches a binary attribute
- radius_get_vendor_attr() - Extracts a vendor specific attribute
- radius_put_vendor_attr() - Attaches a vendor specific binary attribute
- radius_send_request() - Sends the request and waites for a reply
radius_get_vendor_attr
(PECL radius >= 1.1.0)
radius_get_vendor_attr — Extracts a vendor specific attribute
Opis
$data
)
If radius_get_attr() returns
RADIUS_VENDOR_SPECIFIC,
radius_get_vendor_attr() may be called to determine the
vendor.
Zwracane wartości
Returns an associative array containing the attribute-type, vendor and the
data, or FALSE on error.
Przykłady
Przykład #1 radius_get_vendor_attr() example
<?php
while ($resa = radius_get_attr($res)) {
if (!is_array($resa)) {
printf ("Error getting attribute: %s\n", radius_strerror($res));
exit;
}
$attr = $resa['attr'];
$data = $resa['data'];
printf("Got Attr:%d %d Bytes %s\n", $attr, strlen($data), bin2hex($data));
if ($attr == RADIUS_VENDOR_SPECIFIC) {
$resv = radius_get_vendor_attr($data);
if (is_array($resv)) {
$vendor = $resv['vendor'];
$attrv = $resv['attr'];
$datav = $resv['data'];
printf("Got Vendor Attr:%d %d Bytes %s\n", $attrv, strlen($datav), bin2hex($datav));
}
}
}
?>
Zobacz też:
- radius_get_attr() - Extracts an attribute
- radius_put_vendor_attr() - Attaches a vendor specific binary attribute
radius_put_addr
(PECL radius >= 1.1.0)
radius_put_addr — Attaches an IP-Address attribute
Opis
$radius_handle
, int $type
, string $addr
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
radius_put_attr
(PECL radius >= 1.1.0)
radius_put_attr — Attaches a binary attribute
Opis
$radius_handle
, int $type
, string $value
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 radius_put_attr() example
<?php
mt_srand(time());
$chall = mt_rand();
$chapval = md5(pack('Ca*',1 , 'sepp' . $chall));
$pass = pack('CH*', 1, $chapval);
if (!radius_put_attr($res, RADIUS_CHAP_PASSWORD, $pass)) {
echo 'RadiusError:' . radius_strerror($res). "\n<br />";
exit;
}
?>
Zobacz też:
- radius_get_attr() - Extracts an attribute
- radius_get_vendor_attr() - Extracts a vendor specific attribute
- radius_put_vendor_attr() - Attaches a vendor specific binary attribute
radius_put_int
(PECL radius >= 1.1.0)
radius_put_int — Attaches an integer attribute
Opis
$radius_handle
, int $type
, int $value
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 radius_put_int() example
<?php
if (!radius_put_int($res, RAD_FRAMED_PROTOCOL, RAD_PPP)) {
echo 'RadiusError:' . radius_strerror($res). "\n<br />";
exit;
}
?>
Zobacz też:
- radius_put_string() - Attaches a string attribute
- radius_put_vendor_int() - Attaches a vendor specific integer attribute
- radius_put_vendor_string() - Attaches a vendor specific string attribute
radius_put_string
(PECL radius >= 1.1.0)
radius_put_string — Attaches a string attribute
Opis
$radius_handle
, int $type
, string $value
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 radius_put_string() example
<?php
if (!radius_put_string($res, RADIUS_USER_NAME, 'billy')) {
echo 'RadiusError:' . radius_strerror($res). "\n<br />";
exit;
}
?>
Zobacz też:
- radius_put_int() - Attaches an integer attribute
- radius_put_vendor_int() - Attaches a vendor specific integer attribute
- radius_put_vendor_string() - Attaches a vendor specific string attribute
radius_put_vendor_addr
(PECL radius >= 1.1.0)
radius_put_vendor_addr — Attaches a vendor specific IP-Address attribute
Opis
$radius_handle
, int $vendor
, int $type
, string $addr
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
radius_put_vendor_attr
(PECL radius >= 1.1.0)
radius_put_vendor_attr — Attaches a vendor specific binary attribute
Opis
$radius_handle
, int $vendor
, int $type
, string $value
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 radius_put_vendor_attr() example
<?php
if (!radius_put_vendor_attr($res, RADIUS_VENDOR_MICROSOFT, RAD_MICROSOFT_MS_CHAP_CHALLENGE, $challenge)) {
echo 'RadiusError:' . radius_strerror($res). "\n<br />";
exit;
}
?>
radius_put_vendor_int
(PECL radius >= 1.1.0)
radius_put_vendor_int — Attaches a vendor specific integer attribute
Opis
$radius_handle
, int $vendor
, int $type
, int $value
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
radius_put_vendor_string
(PECL radius >= 1.1.0)
radius_put_vendor_string — Attaches a vendor specific string attribute
Opis
$radius_handle
, int $vendor
, int $type
, string $value
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
radius_request_authenticator
(PECL radius >= 1.1.0)
radius_request_authenticator — Returns the request authenticator
Opis
$radius_handle
)The request authenticator is needed for demangling mangled data like passwords and encryption-keys.
Zwracane wartości
Returns the request authenticator as string, or FALSE on error.
radius_send_request
(PECL radius >= 1.1.0)
radius_send_request — Sends the request and waites for a reply
Opis
$radius_handle
)After the Radius request has been constructed, it is sent by radius_send_request().
The radius_send_request() function sends the request and waits for a valid reply, retrying the defined servers in round-robin fashion as necessary.
Zwracane wartości
If a valid response is received, radius_send_request()
returns the Radius code which specifies the type of the response. This will
typically be RADIUS_ACCESS_ACCEPT,
RADIUS_ACCESS_REJECT, or
RADIUS_ACCESS_CHALLENGE. If no valid response is
received, radius_send_request() returns FALSE.
radius_server_secret
(PECL radius >= 1.1.0)
radius_server_secret — Returns the shared secret
Opis
$radius_handle
)The shared secret is needed as salt for demangling mangled data like passwords and encryption-keys.
Zwracane wartości
Returns the server's shared secret as string, or FALSE on error.
radius_strerror
(PECL radius >= 1.1.0)
radius_strerror — Returns an error message
Opis
$radius_handle
)If Radius-functions fail then they record an error message. This error message can be retrieved with this function.
Zwracane wartości
Returns error messages as string from failed radius functions.
Spis treści
- radius_acct_open — Creates a Radius handle for accounting
- radius_add_server — Adds a server
- radius_auth_open — Creates a Radius handle for authentication
- radius_close — Frees all ressources
- radius_config — Causes the library to read the given configuration file
- radius_create_request — Create accounting or authentication request
- radius_cvt_addr — Converts raw data to IP-Address
- radius_cvt_int — Converts raw data to integer
- radius_cvt_string — Converts raw data to string
- radius_demangle_mppe_key — Derives mppe-keys from mangled data
- radius_demangle — Demangles data
- radius_get_attr — Extracts an attribute
- radius_get_vendor_attr — Extracts a vendor specific attribute
- radius_put_addr — Attaches an IP-Address attribute
- radius_put_attr — Attaches a binary attribute
- radius_put_int — Attaches an integer attribute
- radius_put_string — Attaches a string attribute
- radius_put_vendor_addr — Attaches a vendor specific IP-Address attribute
- radius_put_vendor_attr — Attaches a vendor specific binary attribute
- radius_put_vendor_int — Attaches a vendor specific integer attribute
- radius_put_vendor_string — Attaches a vendor specific string attribute
- radius_request_authenticator — Returns the request authenticator
- radius_send_request — Sends the request and waites for a reply
- radius_server_secret — Returns the shared secret
- radius_strerror — Returns an error message
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Przykłady
- Radius Funkcje
- radius_acct_open — Creates a Radius handle for accounting
- radius_add_server — Adds a server
- radius_auth_open — Creates a Radius handle for authentication
- radius_close — Frees all ressources
- radius_config — Causes the library to read the given configuration file
- radius_create_request — Create accounting or authentication request
- radius_cvt_addr — Converts raw data to IP-Address
- radius_cvt_int — Converts raw data to integer
- radius_cvt_string — Converts raw data to string
- radius_demangle_mppe_key — Derives mppe-keys from mangled data
- radius_demangle — Demangles data
- radius_get_attr — Extracts an attribute
- radius_get_vendor_attr — Extracts a vendor specific attribute
- radius_put_addr — Attaches an IP-Address attribute
- radius_put_attr — Attaches a binary attribute
- radius_put_int — Attaches an integer attribute
- radius_put_string — Attaches a string attribute
- radius_put_vendor_addr — Attaches a vendor specific IP-Address attribute
- radius_put_vendor_attr — Attaches a vendor specific binary attribute
- radius_put_vendor_int — Attaches a vendor specific integer attribute
- radius_put_vendor_string — Attaches a vendor specific string attribute
- radius_request_authenticator — Returns the request authenticator
- radius_send_request — Sends the request and waites for a reply
- radius_server_secret — Returns the shared secret
- radius_strerror — Returns an error message
Rozszerzenia daty i czasu
Calendar
Wstęp
The calendar extension presents a series of functions to simplify converting between different calendar formats. The intermediary or standard it is based on is the Julian Day Count. The Julian Day Count is a count of days starting from January 1st, 4713 B.C. To convert between calendar systems, you must first convert to Julian Day Count, then to the calendar system of your choice. Julian Day Count is very different from the Julian Calendar! For more information on Julian Day Count, visit » http://www.hermetic.ch/cal_stud/jdn.htm. For more information on calendar systems visit » http://www.fourmilab.ch/documents/calendar/. Excerpts from this page are included in these instructions, and are in quotes.
Instalacja/Konfiguracja
Spis treści
Wymagania
Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.
Instalacja
To get these functions to work, you have to compile PHP with --enable-calendar .
PHP w wersji dla systemów Windows posiada wbudowaną obsługę dla tego rozszerzenia. Nie trzeba ładować żadnych dodatkowych rozszerzeń, aby używać tych funkcji.
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
-
CAL_GREGORIAN(integer) -
CAL_JULIAN(integer) -
CAL_JEWISH(integer) -
CAL_FRENCH(integer) -
CAL_NUM_CALS(integer) -
CAL_DOW_DAYNO(integer) -
CAL_DOW_SHORT(integer) -
CAL_DOW_LONG(integer) -
CAL_MONTH_GREGORIAN_SHORT(integer) -
CAL_MONTH_GREGORIAN_LONG(integer) -
CAL_MONTH_JULIAN_SHORT(integer) -
CAL_MONTH_JULIAN_LONG(integer) -
CAL_MONTH_JEWISH(integer) -
CAL_MONTH_FRENCH(integer)
The following constants are available since PHP 4.3.0 :
-
CAL_EASTER_DEFAULT(integer) -
CAL_EASTER_ROMAN(integer) -
CAL_EASTER_ALWAYS_GREGORIAN(integer) -
CAL_EASTER_ALWAYS_JULIAN(integer)
The following constants are available since PHP 5.0.0 :
Calendar Funkcje
cal_days_in_month
(PHP 4 >= 4.1.0, PHP 5)
cal_days_in_month — Return the number of days in a month for a given year and calendar
Opis
$calendar
, int $month
, int $year
)
This function will return the number of days in the
month of year for
the specified calendar.
Parametry
-
calendar -
Calendar to use for calculation
-
month -
Month in the selected calendar
-
year -
Year in the selected calendar
Zwracane wartości
The length in days of the selected month in the given calendar
Przykłady
Przykład #1 cal_days_in_month() example
<?php
$num = cal_days_in_month(CAL_GREGORIAN, 8, 2003); // 31
echo "There was $num days in August 2003";
?>
cal_from_jd
(PHP 4 >= 4.1.0, PHP 5)
cal_from_jd — Converts from Julian Day Count to a supported calendar
Opis
$jd
, int $calendar
)
cal_from_jd() converts the Julian day given in
jd into a date of the specified
calendar. Supported
calendar values are
CAL_GREGORIAN,
CAL_JULIAN,
CAL_JEWISH and
CAL_FRENCH.
Parametry
-
jd -
Julian day as integer
-
calendar -
Calendar to convert to
Zwracane wartości
Returns an array containing calendar information like month, day, year, day of week, abbreviated and full names of weekday and month and the date in string form "month/day/year".
Przykłady
Przykład #1 cal_from_jd() example
<?php
$today = unixtojd(mktime(0, 0, 0, 8, 16, 2003));
print_r(cal_from_jd($today, CAL_GREGORIAN));
?>
Powyższy przykład wyświetli:
Array
(
[date] => 8/16/2003
[month] => 8
[day] => 16
[year] => 2003
[dow] => 6
[abbrevdayname] => Sat
[dayname] => Saturday
[abbrevmonth] => Aug
[monthname] => August
)
Zobacz też:
- cal_to_jd() - Converts from a supported calendar to Julian Day Count
- jdtofrench() - Converts a Julian Day Count to the French Republican Calendar
- jdtogregorian() - Converts Julian Day Count to Gregorian date
- jdtojewish() - Converts a Julian day count to a Jewish calendar date
- jdtojulian() - Converts a Julian Day Count to a Julian Calendar Date
- jdtounix() - Convert Julian Day to Unix timestamp
cal_info
(PHP 4 >= 4.1.0, PHP 5)
cal_info — Returns information about a particular calendar
Opis
$calendar = -1
] )
cal_info() returns information on the
specified calendar.
Calendar information is returned as an array containing the
elements calname, calsymbol,
month, abbrevmonth and
maxdaysinmonth. The names of the different calendars
which can be used as calendar are as follows:
-
0 or
CAL_GREGORIAN- Gregorian Calendar -
1 or
CAL_JULIAN- Julian Calendar -
2 or
CAL_JEWISH- Jewish Calendar -
3 or
CAL_FRENCH- French Revolutionary Calendar
If no calendar is specified information on all
supported calendars is returned as an array.
Parametry
-
calendar -
Calendar to return information for. If no calendar is specified information about all calendars is returned.
Zwracane wartości
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.0.0 |
The calendar parameter becomes optional
and defaults to "all calendars" if omitted.
|
Przykłady
Przykład #1 cal_info() example
<?php
$info = cal_info(0);
print_r($info);
?>
Powyższy przykład wyświetli:
Array
(
[months] => Array
(
[1] => January
[2] => February
[3] => March
[4] => April
[5] => May
[6] => June
[7] => July
[8] => August
[9] => September
[10] => October
[11] => November
[12] => December
)
[abbrevmonths] => Array
(
[1] => Jan
[2] => Feb
[3] => Mar
[4] => Apr
[5] => May
[6] => Jun
[7] => Jul
[8] => Aug
[9] => Sep
[10] => Oct
[11] => Nov
[12] => Dec
)
[maxdaysinmonth] => 31
[calname] => Gregorian
[calsymbol] => CAL_GREGORIAN
)
cal_to_jd
(PHP 4 >= 4.1.0, PHP 5)
cal_to_jd — Converts from a supported calendar to Julian Day Count
Opis
$calendar
, int $month
, int $day
, int $year
)
cal_to_jd() calculates the Julian day count
for a date in the specified calendar.
Supported calendars are
CAL_GREGORIAN,
CAL_JULIAN,
CAL_JEWISH and
CAL_FRENCH.
Parametry
-
calendar -
Calendar to convert from, one of
CAL_GREGORIAN,CAL_JULIAN,CAL_JEWISHorCAL_FRENCH. -
month -
The month as a number, the valid range depends on the
calendar -
day -
The day as a number, the valid range depends on the
calendar -
year -
The year as a number, the valid range depends on the
calendar
Zwracane wartości
A Julian Day number.
Zobacz też:
- cal_from_jd() - Converts from Julian Day Count to a supported calendar
- frenchtojd() - Converts a date from the French Republican Calendar to a Julian Day Count
- gregoriantojd() - Converts a Gregorian date to Julian Day Count
- jewishtojd() - Converts a date in the Jewish Calendar to Julian Day Count
- juliantojd() - Converts a Julian Calendar date to Julian Day Count
- unixtojd() - Convert Unix timestamp to Julian Day
easter_date
(PHP 4, PHP 5)
easter_date — Get Unix timestamp for midnight on Easter of a given year
Opis
$year
] )Returns the Unix timestamp corresponding to midnight on Easter of the given year.
This function will generate a warning if the year is outside of the range for Unix timestamps (i.e. before 1970 or after 2037).
The date of Easter Day was defined by the Council of Nicaea in AD325 as the Sunday after the first full moon which falls on or after the Spring Equinox. The Equinox is assumed to always fall on 21st March, so the calculation reduces to determining the date of the full moon and the date of the following Sunday. The algorithm used here was introduced around the year 532 by Dionysius Exiguus. Under the Julian Calendar (for years before 1753) a simple 19-year cycle is used to track the phases of the Moon. Under the Gregorian Calendar (for years after 1753 - devised by Clavius and Lilius, and introduced by Pope Gregory XIII in October 1582, and into Britain and its then colonies in September 1752) two correction factors are added to make the cycle more accurate.
Parametry
-
year -
The year as a number between 1970 an 2037
Zwracane wartości
The easter date as a unix timestamp.
Rejestr zmian
| Wersja | Opis |
|---|---|
| Since 4.3.0 |
The year parameter is optional and defaults
to the current year according to the local time if omitted.
|
Przykłady
Przykład #1 easter_date() example
<?php
echo date("M-d-Y", easter_date(1999)); // Apr-04-1999
echo date("M-d-Y", easter_date(2000)); // Apr-23-2000
echo date("M-d-Y", easter_date(2001)); // Apr-15-2001
?>
Zobacz też:
- easter_days() - Get number of days after March 21 on which Easter falls for a given year for calculating Easter before 1970 or after 2037
easter_days
(PHP 4, PHP 5)
easter_days — Get number of days after March 21 on which Easter falls for a given year
Opis
$year
[, int $method = CAL_EASTER_DEFAULT
]] )Returns the number of days after March 21 on which Easter falls for a given year. If no year is specified, the current year is assumed.
This function can be used instead of easter_date() to calculate Easter for years which fall outside the range of Unix timestamps (i.e. before 1970 or after 2037).
The date of Easter Day was defined by the Council of Nicaea in AD325 as the Sunday after the first full moon which falls on or after the Spring Equinox. The Equinox is assumed to always fall on 21st March, so the calculation reduces to determining the date of the full moon and the date of the following Sunday. The algorithm used here was introduced around the year 532 by Dionysius Exiguus. Under the Julian Calendar (for years before 1753) a simple 19-year cycle is used to track the phases of the Moon. Under the Gregorian Calendar (for years after 1753 - devised by Clavius and Lilius, and introduced by Pope Gregory XIII in October 1582, and into Britain and its then colonies in September 1752) two correction factors are added to make the cycle more accurate.
Parametry
-
year -
The year as a positive number
-
method -
Allows to calculate easter dates based on the Gregorian calendar during the years 1582 - 1752 when set to
CAL_EASTER_ROMAN. See the calendar constants for more valid constants.
Zwracane wartości
The number of days after March 21st that the Easter Sunday
is in the given year.
Rejestr zmian
| Wersja | Opis |
|---|---|
| Since 4.3.0 |
The year parameter is optional and defaults
to the current year according to the local time if omitted.
|
| Since 4.3.0 |
The method parameter was introduced.
|
Przykłady
Przykład #1 easter_days() example
<?php
echo easter_days(1999); // 14, i.e. April 4
echo easter_days(1492); // 32, i.e. April 22
echo easter_days(1913); // 2, i.e. March 23
?>
FrenchToJD
(PHP 4, PHP 5)
FrenchToJD — Converts a date from the French Republican Calendar to a Julian Day Count
Opis
$month
, int $day
, int $year
)Converts a date from the French Republican Calendar to a Julian Day Count.
These routines only convert dates in years 1 through 14 (Gregorian dates 22 September 1792 through 22 September 1806). This more than covers the period when the calendar was in use.
Parametry
-
month -
The month as a number from 1 (for Vendémiaire) to 13 (for the period of 5-6 days at the end of each year)
-
day -
The day as a number from 1 to 30
-
year -
The year as a number between 1 and 14
Zwracane wartości
The julian day for the given french revolution date as an integer.
Zobacz też:
- jdtofrench() - Converts a Julian Day Count to the French Republican Calendar
- cal_to_jd() - Converts from a supported calendar to Julian Day Count
GregorianToJD
(PHP 4, PHP 5)
GregorianToJD — Converts a Gregorian date to Julian Day Count
Opis
$month
, int $day
, int $year
)Valid Range for Gregorian Calendar 4714 B.C. to 9999 A.D.
Although this function can handle dates all the way back to 4714 B.C., such use may not be meaningful. The Gregorian calendar was not instituted until October 15, 1582 (or October 5, 1582 in the Julian calendar). Some countries did not accept it until much later. For example, Britain converted in 1752, The USSR in 1918 and Greece in 1923. Most European countries used the Julian calendar prior to the Gregorian.
Parametry
-
month -
The month as a number from 1 (for January) to 12 (for December)
-
day -
The day as a number from 1 to 31
-
year -
The year as a number between -4714 and 9999
Zwracane wartości
The julian day for the given gregorian date as an integer.
Przykłady
Przykład #1 Calendar functions
<?php
$jd = GregorianToJD(10, 11, 1970);
echo "$jd\n";
$gregorian = JDToGregorian($jd);
echo "$gregorian\n";
?>
Zobacz też:
- jdtogregorian() - Converts Julian Day Count to Gregorian date
- cal_to_jd() - Converts from a supported calendar to Julian Day Count
JDDayOfWeek
(PHP 4, PHP 5)
JDDayOfWeek — Returns the day of the week
Opis
Returns the day of the week. Can return a string or an integer depending on the mode.
Parametry
-
julianday -
A julian day number as integer
-
mode -
Calendar week modes Mode Meaning 0 (Default) Return the day number as an int (0=Sunday, 1=Monday, etc) 1 Returns string containing the day of week (English-Gregorian) 2 Return a string containing the abbreviated day of week (English-Gregorian)
Zwracane wartości
The gregorian weekday as either an integer or string.
JDMonthName
(PHP 4, PHP 5)
JDMonthName — Returns a month name
Opis
$julianday
, int $mode
)
Returns a string containing a month name.
mode tells this function which calendar to
convert the Julian Day Count to, and what type of month names are
to be returned.
| Mode | Meaning | Values |
|---|---|---|
| 0 | Gregorian - abbreviated | Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec |
| 1 | Gregorian | January, February, March, April, May, June, July, August, September, October, November, December |
| 2 | Julian - abbreviated | Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec |
| 3 | Julian | January, February, March, April, May, June, July, August, September, October, November, December |
| 4 | Jewish | Tishri, Heshvan, Kislev, Tevet, Shevat, AdarI, AdarII, Nisan, Iyyar, Sivan, Tammuz, Av, Elul |
| 5 | French Republican | Vendemiaire, Brumaire, Frimaire, Nivose, Pluviose, Ventose, Germinal, Floreal, Prairial, Messidor, Thermidor, Fructidor, Extra |
Parametry
-
jday -
The Julian Day to operate on
-
calendar -
The calendar to take the month name from
Zwracane wartości
The month name for the given Julian Day and calendar.
JDToFrench
(PHP 4, PHP 5)
JDToFrench — Converts a Julian Day Count to the French Republican Calendar
Opis
$juliandaycount
)Converts a Julian Day Count to the French Republican Calendar.
Parametry
-
julianday -
A julian day number as integer
Zwracane wartości
The french revolution date as a string in the form "month/day/year"
Zobacz też:
- frenchtojd() - Converts a date from the French Republican Calendar to a Julian Day Count
- cal_from_jd() - Converts from Julian Day Count to a supported calendar
JDToGregorian
(PHP 4, PHP 5)
JDToGregorian — Converts Julian Day Count to Gregorian date
Opis
$julianday
)Converts Julian Day Count to a string containing the Gregorian date in the format of "month/day/year".
Parametry
-
julianday -
A julian day number as integer
Zwracane wartości
The gregorian date as a string in the form "month/day/year"
Zobacz też:
- gregoriantojd() - Converts a Gregorian date to Julian Day Count
- cal_from_jd() - Converts from Julian Day Count to a supported calendar
jdtojewish
(PHP 4, PHP 5)
jdtojewish — Converts a Julian day count to a Jewish calendar date
Opis
$juliandaycount
[, bool $hebrew = false
[, int $fl = 0
]] )Converts a Julian Day Count to the Jewish Calendar.
Parametry
-
julianday -
A julian day number as integer
-
hebrew -
If the
hebrewparameter is set toTRUE, theflparameter is used for Hebrew, string based, output format. -
fl -
The available formats are:
CAL_JEWISH_ADD_ALAFIM_GERESH,CAL_JEWISH_ADD_ALAFIM,CAL_JEWISH_ADD_GERESHAYIM.
Zwracane wartości
The jewish date as a string in the form "month/day/year"
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.0.0 |
The fl parameter was added.
|
| 4.3.0 |
The hebrew parameter was added.
|
Przykłady
Przykład #1 jdtojewish() Example
<?php
echo jdtojewish(gregoriantojd(10, 8, 2002), true,
CAL_JEWISH_ADD_GERESHAYIM + CAL_JEWISH_ADD_ALAFIM + CAL_JEWISH_ADD_ALAFIM_GERESH);
?>
Zobacz też:
- jewishtojd() - Converts a date in the Jewish Calendar to Julian Day Count
- cal_from_jd() - Converts from Julian Day Count to a supported calendar
JDToJulian
(PHP 4, PHP 5)
JDToJulian — Converts a Julian Day Count to a Julian Calendar Date
Opis
$julianday
)Converts Julian Day Count to a string containing the Julian Calendar Date in the format of "month/day/year".
Parametry
-
julianday -
A julian day number as integer
Zwracane wartości
The julian date as a string in the form "month/day/year"
Zobacz też:
- juliantojd() - Converts a Julian Calendar date to Julian Day Count
- cal_from_jd() - Converts from Julian Day Count to a supported calendar
jdtounix
(PHP 4, PHP 5)
jdtounix — Convert Julian Day to Unix timestamp
Opis
$jday
)
This function will return a Unix timestamp corresponding to the
Julian Day given in jday or FALSE if
jday is not inside the Unix epoch
(Gregorian years between 1970 and 2037 or 2440588 <=
jday <= 2465342 ). The time returned is
localtime (and not GMT).
Parametry
-
jday -
A julian day number between 2440588 and 2465342.
Zwracane wartości
The unix timestamp for the start of the given julian day.
JewishToJD
(PHP 4, PHP 5)
JewishToJD — Converts a date in the Jewish Calendar to Julian Day Count
Opis
$month
, int $day
, int $year
)Although this function can handle dates all the way back to the year 1 (3761 B.C.), such use may not be meaningful. The Jewish calendar has been in use for several thousand years, but in the early days there was no formula to determine the start of a month. A new month was started when the new moon was first observed.
Parametry
-
month -
The month as a number from 1 to 13
-
day -
The day as a number from 1 to 30
-
year -
The year as a number between 1 and 9999
Zwracane wartości
The julian day for the given jewish date as an integer.
Zobacz też:
- jdtojewish() - Converts a Julian day count to a Jewish calendar date
- cal_to_jd() - Converts from a supported calendar to Julian Day Count
JulianToJD
(PHP 4, PHP 5)
JulianToJD — Converts a Julian Calendar date to Julian Day Count
Opis
$month
, int $day
, int $year
)Valid Range for Julian Calendar 4713 B.C. to 9999 A.D.
Although this function can handle dates all the way back to 4713 B.C., such use may not be meaningful. The calendar was created in 46 B.C., but the details did not stabilize until at least 8 A.D., and perhaps as late at the 4th century. Also, the beginning of a year varied from one culture to another - not all accepted January as the first month.
Remember, the current calendar system being used worldwide is the Gregorian calendar. gregoriantojd() can be used to convert such dates to their Julian Day count.
Parametry
-
month -
The month as a number from 1 (for January) to 12 (for December)
-
day -
The day as a number from 1 to 31
-
year -
The year as a number between -4713 and 9999
Zwracane wartości
The julian day for the given julian date as an integer.
Zobacz też:
- jdtojulian() - Converts a Julian Day Count to a Julian Calendar Date
- cal_to_jd() - Converts from a supported calendar to Julian Day Count
unixtojd
(PHP 4, PHP 5)
unixtojd — Convert Unix timestamp to Julian Day
Opis
$timestamp = time()
] )
Return the Julian Day for a Unix timestamp
(seconds since 1.1.1970), or for the current day if no
timestamp is given.
Parametry
-
timestamp -
A unix timestamp to convert.
Zwracane wartości
A julian day number as integer.
Spis treści
- cal_days_in_month — Return the number of days in a month for a given year and calendar
- cal_from_jd — Converts from Julian Day Count to a supported calendar
- cal_info — Returns information about a particular calendar
- cal_to_jd — Converts from a supported calendar to Julian Day Count
- easter_date — Get Unix timestamp for midnight on Easter of a given year
- easter_days — Get number of days after March 21 on which Easter falls for a given year
- FrenchToJD — Converts a date from the French Republican Calendar to a Julian Day Count
- GregorianToJD — Converts a Gregorian date to Julian Day Count
- JDDayOfWeek — Returns the day of the week
- JDMonthName — Returns a month name
- JDToFrench — Converts a Julian Day Count to the French Republican Calendar
- JDToGregorian — Converts Julian Day Count to Gregorian date
- jdtojewish — Converts a Julian day count to a Jewish calendar date
- JDToJulian — Converts a Julian Day Count to a Julian Calendar Date
- jdtounix — Convert Julian Day to Unix timestamp
- JewishToJD — Converts a date in the Jewish Calendar to Julian Day Count
- JulianToJD — Converts a Julian Calendar date to Julian Day Count
- unixtojd — Convert Unix timestamp to Julian Day
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Calendar Funkcje
- cal_days_in_month — Return the number of days in a month for a given year and calendar
- cal_from_jd — Converts from Julian Day Count to a supported calendar
- cal_info — Returns information about a particular calendar
- cal_to_jd — Converts from a supported calendar to Julian Day Count
- easter_date — Get Unix timestamp for midnight on Easter of a given year
- easter_days — Get number of days after March 21 on which Easter falls for a given year
- FrenchToJD — Converts a date from the French Republican Calendar to a Julian Day Count
- GregorianToJD — Converts a Gregorian date to Julian Day Count
- JDDayOfWeek — Returns the day of the week
- JDMonthName — Returns a month name
- JDToFrench — Converts a Julian Day Count to the French Republican Calendar
- JDToGregorian — Converts Julian Day Count to Gregorian date
- jdtojewish — Converts a Julian day count to a Jewish calendar date
- JDToJulian — Converts a Julian Day Count to a Julian Calendar Date
- jdtounix — Convert Julian Day to Unix timestamp
- JewishToJD — Converts a date in the Jewish Calendar to Julian Day Count
- JulianToJD — Converts a Julian Calendar date to Julian Day Count
- unixtojd — Convert Unix timestamp to Julian Day
Data i Czas
Wstęp
Te funkcje pozwalają pobierać datę i czas z serwera, na którym uruchomione są skrypty PHP. Można ich używać do formatowania daty i czasu na wiele różnych sposobów.
Informacje o dacie i czasie są wewnętrzenie przechowywane jako liczby 64 bitowe, dlatego obsługiwane są wszystkie dające się wyobrazić daty (włącznie z latami ujemnymi). Zakres dat jest od 292 miliardów lat w przeszłości do 292 miliardów lat w przyszłości.
Informacja: Proszę pamiętać, że poniższe funkcje są zależne od lokalnych ustawień danego serwera. Należy się upewnić, że podczas pracy z nimi bierzemy pod uwagę czas zimowy i lata przestępne (należy użyć np. $date = strtotime('+7 days', $date), a nie $date += 7*24*60*60).
Informacja: Strefy czasowe, do których odwołujemy się w tym rozdziale można znaleźć w Lista obsługiwanych stref czasowych.
Instalacja/Konfiguracja
Spis treści
Wymagania
Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.
Instalacja
By używać tych funkcji, nie trzeba niczego instalować. Są one częścią jądra PHP.
Informacja: Pobieranie najnowszej bazy danych stref czasowych
Najnowszą wersję bazy danych stref czasowych można zainstalować poprzez PECL » timezonedb.
Informacja: Eksperymentalna obsługa daty i czasu w PHP 5.1.x
Chociaż klasa DateTime (i powiązane z nią funkcje) są włączone domyślnie dopiero od PHP 5.2.0, to jest możliwe dodanie eksperymentalnej obsługi już w PHP 5.1.x, poprzez użycie następującego znacznika przed przystąpieniem do konfiguracji/kompilacji: CFLAGS=-DEXPERIMENTAL_DATE_SUPPORT=1
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| date.default_latitude | "31.7667" | PHP_INI_ALL | Available since PHP 5.0.0. |
| date.default_longitude | "35.2333" | PHP_INI_ALL | Available since PHP 5.0.0. |
| date.sunrise_zenith | "90.583333" | PHP_INI_ALL | Available since PHP 5.0.0. |
| date.sunset_zenith | "90.583333" | PHP_INI_ALL | Available since PHP 5.0.0. |
| date.timezone | "" | PHP_INI_ALL | Available since PHP 5.1.0. |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
date.default_latitudefloat -
The default latitude.
-
date.default_longitudefloat -
The default longitude.
-
date.sunrise_zenithfloat -
The default sunrise zenith.
-
date.sunset_zenithfloat -
The default sunset zenith.
-
date.timezonestring -
The default timezone used by all date/time functions. Prior to PHP 5.4.0, this would only work if the TZ environment variable was not set. The precedence order for which timezone is used if none is explicitly mentioned is described in the date_default_timezone_get() page. See Lista obsługiwanych stref czasowych for a list of supported timezones.
Informacja: The first four configuration options are currently only used by date_sunrise() and date_sunset().
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
The DATE_ constants are defined since PHP 5.1.1 and they offer standard date representations, which can be used along with the date format functions (like date()).
Following constants exists since PHP 5.1.2 and specify a format returned by functions date_sunrise() and date_sunset().
The DateTime class
(PHP 5 >= 5.2.0)
Wstęp
Representation of date and time.
Krótki opis klasy
$format
, string $time
[, DateTimeZone $timezone
] )Stałe predefiniowane
-
DateTime::ATOMDATE_ATOM - Atom (example: 2005-08-15T15:52:01+00:00)
- HTTP Cookies (example: Monday, 15-Aug-05 15:52:01 UTC)
-
DateTime::ISO8601DATE_ISO8601 - ISO-8601 (example: 2005-08-15T15:52:01+0000)
-
DateTime::RFC822DATE_RFC822 - RFC 822 (example: Mon, 15 Aug 05 15:52:01 +0000)
-
DateTime::RFC850DATE_RFC850 - RFC 850 (example: Monday, 15-Aug-05 15:52:01 UTC)
-
DateTime::RFC1036DATE_RFC1036 - RFC 1036 (example: Mon, 15 Aug 05 15:52:01 +0000)
-
DateTime::RFC1123DATE_RFC1123 - RFC 1123 (example: Mon, 15 Aug 2005 15:52:01 +0000)
-
DateTime::RFC2822DATE_RFC2822 - RFC 2822 (Mon, 15 Aug 2005 15:52:01 +0000)
-
DateTime::RFC3339DATE_RFC3339 -
Same as
DATE_ATOM(since PHP 5.1.3) -
DateTime::RSSDATE_RSS - RSS (Mon, 15 Aug 2005 15:52:01 +0000)
-
DateTime::W3CDATE_W3C - World Wide Web Consortium (example: 2005-08-15T15:52:01+00:00)
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.2.2 | DateTime object comparison with the comparison operators changed to work as expected. Previously, all DateTime objects were considered equal (using ==). |
DateTime::add
date_add
(PHP 5 >= 5.3.0)
DateTime::add -- date_add — Adds an amount of days, months, years, hours, minutes and seconds to a DateTime object
Opis
Styl obiektowy
Styl proceduralny
Adds the specified DateInterval object to the specified DateTime object.
Parametry
-
object -
Tylko styl proceduralny: Obiekt DateTime zwracany przez date_create(). Funkcja modyfikuje ten obiekt.
-
interval -
A DateInterval object
Zwracane wartości
Zwraca zmodyfikowany obiekt DateTime lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 DateTime::add() example
Styl obiektowy
<?php
$date = new DateTime('2000-01-01');
$date->add(new DateInterval('P10D'));
echo $date->format('Y-m-d') . "\n";
?>
Styl proceduralny
<?php
$date = date_create('2000-01-01');
date_add($date, date_interval_create_from_date_string('10 days'));
echo date_format($date, 'Y-m-d');
?>
Powyższe przykłady wyświetlą:
2000-01-11
Przykład #2 Further DateTime::add() examples
<?php
$date = new DateTime('2000-01-01');
$date->add(new DateInterval('PT10H30S'));
echo $date->format('Y-m-d H:i:s') . "\n";
$date = new DateTime('2000-01-01');
$date->add(new DateInterval('P7Y5M4DT4H3M2S'));
echo $date->format('Y-m-d H:i:s') . "\n";
?>
Powyższy przykład wyświetli:
2000-01-01 10:00:30 2007-06-05 04:03:02
Przykład #3 Beware when adding months
<?php
$date = new DateTime('2000-12-31');
$interval = new DateInterval('P1M');
$date->add($interval);
echo $date->format('Y-m-d') . "\n";
$date->add($interval);
echo $date->format('Y-m-d') . "\n";
?>
Powyższy przykład wyświetli:
2001-01-31 2001-03-03
Notatki
DateTime::modify() is an alternative when using PHP 5.2.
Zobacz też:
- DateTime::sub() - Subtracts an amount of days, months, years, hours, minutes and seconds from a DateTime object
- DateTime::diff() - Returns the difference between two DateTime objects
- DateTime::modify() - Alters the timestamp
DateTime::__construct
date_create
(PHP 5 >= 5.2.0)
DateTime::__construct -- date_create — Returns new DateTime object
Opis
Styl obiektowy
Styl proceduralny
Returns new DateTime object.
Parametry
-
time -
Łańcuch daty/czasu. Prawidłowe formaty są wyjaśnione pod adresem Formaty daty i czasu.
Enter
NULLhere to obtain the current time when using the$timezoneparameter. -
timezone -
A DateTimeZone object representing the desired time zone.
If
$timezoneis omitted, the current timezone will be used.Informacja:
The
$timezoneparameter and the current timezone are ignored when the$timeparameter either is a UNIX timestamp (e.g. @946684800) or specifies a timezone (e.g. 2010-01-28T15:00:00+02:00).
Zwracane wartości
Returns a new DateTime instance.
Styl proceduralny zwraca FALSE w przypadku niepowodzenia.
Błędy/Wyjątki
Emits Exception in case of an error.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.0 | If an invalid date is specified, then an exception is now thrown. Previously an error was emitted. |
Przykłady
Przykład #1 DateTime::__construct() example
Styl obiektowy
<?php
try {
$date = new DateTime('2000-01-01');
} catch (Exception $e) {
echo $e->getMessage();
exit(1);
}
echo $date->format('Y-m-d');
?>
Styl proceduralny
<?php
$date = date_create('2000-01-01');
if (!$date) {
$e = date_get_last_errors();
foreach ($e['errors'] as $error) {
echo "$error\n";
}
exit(1);
}
echo date_format($date, 'Y-m-d');
?>
Powyższe przykłady wyświetlą:
2000-01-01
Przykład #2 Intricacies of DateTime::__construct()
<?php
// Specified date/time in your computer's time zone.
$date = new DateTime('2000-01-01');
echo $date->format('Y-m-d H:i:sP') . "\n";
// Specified date/time in the specified time zone.
$date = new DateTime('2000-01-01', new DateTimeZone('Pacific/Nauru'));
echo $date->format('Y-m-d H:i:sP') . "\n";
// Current date/time in your computer's time zone.
$date = new DateTime();
echo $date->format('Y-m-d H:i:sP') . "\n";
// Current date/time in the specified time zone.
$date = new DateTime(null, new DateTimeZone('Pacific/Nauru'));
echo $date->format('Y-m-d H:i:sP') . "\n";
// Using a UNIX timestamp. Notice the result is in the UTC time zone.
$date = new DateTime('@946684800');
echo $date->format('Y-m-d H:i:sP') . "\n";
// Non-existent values roll over.
$date = new DateTime('2000-02-30');
echo $date->format('Y-m-d H:i:sP') . "\n";
?>
Powyższy przykład wyświetli coś podobnego do:
2000-01-01 00:00:00-05:00 2000-01-01 00:00:00+12:00 2010-04-24 10:24:16-04:00 2010-04-25 02:24:16+12:00 2000-01-01 00:00:00+00:00 2000-03-01 00:00:00-05:00
Zobacz też:
- DateTime::createFromFormat() - Returns new DateTime object formatted according to the specified format
- DateTimeZone::__construct() - Creates new DateTimeZone object
- Date and Time Formats
- date.timezone ini setting
- date_default_timezone_set() - Sets the default timezone used by all date/time functions in a script
- DateTime::getLastErrors() - Returns the warnings and errors
- checkdate() - Waliduje datę gregoriańską
DateTime::createFromFormat
date_create_from_format
(PHP 5 >= 5.3.0)
DateTime::createFromFormat -- date_create_from_format — Returns new DateTime object formatted according to the specified format
Opis
Styl obiektowy
$format
, string $time
[, DateTimeZone $timezone
] )Styl proceduralny
Returns new DateTime object formatted according to the specified format.
Parametry
-
format -
The format that the passed in string should be in. See the formatting options below. In most cases, the same letters as for the date() can be used.
The following characters are recognized in the formatparameter stringformatcharacterDescription Example parsable values Day --- --- d and j Day of the month, 2 digits with or without leading zeros 01 to 31 or 1 to 31 D and l A textual representation of a day Mon through Sun or Sunday through Saturday S English ordinal suffix for the day of the month, 2 characters. It's ignored while processing. st, nd, rd or th. z The day of the year (starting from 0) 0 through 365 Month --- --- F and M A textual representation of a month, such as January or Sept January through December or Jan through Dec m and n Numeric representation of a month, with or without leading zeros 01 through 12 or 1 through 12 Year --- --- Y A full numeric representation of a year, 4 digits Examples: 1999 or 2003 y A two digit representation of a year Examples: 99 or 03 Time --- --- a and A Ante meridiem and Post meridiem am or pm g and h 12-hour format of an hour with or without leading zero 1 through 12 or 01 through 12 G and H 24-hour format of an hour with or without leading zeros 0 through 23 or 00 through 23 i Minutes with leading zeros 00 to 59 s Seconds, with leading zeros 00 through 59 u Microseconds (up to six digits) Example: 45, 654321 Timezone --- --- e, O, P and T Timezone identifier, or difference to UTC in hours, or difference to UTC with colon between hours and minutes, or timezone abbreviation Examples: UTC, GMT, Atlantic/Azores or +0200 or +02:00 or EST, MDT Full Date/Time --- --- U Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT) Example: 1292177455 Whitespace and Separators --- --- (space) One space or one tab Example: # One of the following separation symbol: ;, :, /, ., ,, -, ( or ) Example: / ;, :, /, ., ,, -, ( or ) The specified character. Example: - ? A random byte Example: ^ (Be aware that for UTF-8 characracters you might need more than one ?. In this case, using * is probably what you want instead) * Random bytes until the next separator or digit Example: * in Y-*-d with the string 2009-aWord-08 will match aWord ! Resets all fields (year, month, day, hour, minute, second, fraction and timzone information) to the Unix Epoch Without !, all fields will be set to the current date and time. | Resets all fields (year, month, day, hour, minute, second, fraction and timzone information) to the Unix Epoch if they have not been parsed yet Y-m-d| will set the year, month and day to the information found in the string to parse, and sets the hour, minute and second to 0. + If this format specifier is present, trailing data in the string will not cause an error, but a warning instead Use DateTime::getLastErrors() to find out whether trailing data was present. Unrecognized characters in the format string will cause the parsing to fail and an error message is appended to the returned structure. You can query error messages with DateTime::getLastErrors().
If
formatdoes not contain the character ! then portions of the generated time which are not specified informatwill be set to the current system time.If
formatcontains the character !, then portions of the generated time not provided informat, as well as values to the left-hand side of the !, will be set to corresponding values from the Unix epoch.The Unix epoch is 1970-01-01 00:00:00 UTC.
-
time -
String representing the time.
-
timezone -
A DateTimeZone object representing the desired time zone.
If
timezoneis omitted andtimecontains no timezone, the current timezone will be used.Informacja:
The
timezoneparameter and the current timezone are ignored when thetimeparameter either contains a UNIX timestamp (e.g. 946684800) or specifies a timezone (e.g. 2010-01-28T15:00:00+02:00).
Zwracane wartości
Returns a new DateTime instance lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 DateTime::createFromFormat() example
Styl obiektowy
<?php
$date = DateTime::createFromFormat('j-M-Y', '15-Feb-2009');
echo $date->format('Y-m-d');
?>
Styl proceduralny
<?php
$date = date_create_from_format('j-M-Y', '15-Feb-2009');
echo date_format($date, 'Y-m-d');
?>
Powyższe przykłady wyświetlą:
2009-02-15
Przykład #2 Intricacies of DateTime::createFromFormat()
<?php
echo 'Current time: ' . date('Y-m-d H:i:s') . "\n";
$format = 'Y-m-d';
$date = DateTime::createFromFormat($format, '2009-02-15');
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";
$format = 'Y-m-d H:i:s';
$date = DateTime::createFromFormat($format, '2009-02-15 15:16:17');
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";
$format = 'Y-m-!d H:i:s';
$date = DateTime::createFromFormat($format, '2009-02-15 15:16:17');
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";
$format = '!d';
$date = DateTime::createFromFormat($format, '15');
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";
?>
Powyższy przykład wyświetli coś podobnego do:
Current time: 2010-04-23 10:29:35 Format: Y-m-d; 2009-02-15 10:29:35 Format: Y-m-d H:i:s; 2009-02-15 15:16:17 Format: Y-m-!d H:i:s; 1970-01-15 15:16:17 Format: !d; 1970-01-15 00:00:00
Zobacz też:
- DateTime::__construct() - Returns new DateTime object
- DateTime::getLastErrors() - Returns the warnings and errors
- checkdate() - Waliduje datę gregoriańską
- strptime() - Parse a time/date generated with strftime
DateTime::diff
date_diff
(PHP 5 >= 5.3.0)
DateTime::diff -- date_diff — Returns the difference between two DateTime objects
Opis
Styl obiektowy
Styl proceduralny
Returns the difference between two DateTime objects.
Parametry
-
datetime -
The date to compare to.
-
absolute -
Whether to return absolute difference.
Zwracane wartości
The DateInterval object representing the
difference between the two dates lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 DateTime::diff() example
Styl obiektowy
<?php
$datetime1 = new DateTime('2009-10-11');
$datetime2 = new DateTime('2009-10-13');
$interval = $datetime1->diff($datetime2);
echo $interval->format('%R%a days');
?>
Styl proceduralny
<?php
$datetime1 = date_create('2009-10-11');
$datetime2 = date_create('2009-10-13');
$interval = date_diff($datetime1, $datetime2);
echo $interval->format('%R%a days');
?>
Powyższe przykłady wyświetlą:
+2 days
Przykład #2 DateTime object comparison
Informacja:
As of PHP 5.2.2, DateTime objects can be compared using comparison operators.
<?php
$date1 = new DateTime("now");
$date2 = new DateTime("tomorrow");
var_dump($date1 == $date2);
var_dump($date1 < $date2);
var_dump($date1 > $date2);
?>
Powyższy przykład wyświetli:
bool(false) bool(true) bool(false)
Zobacz też:
- DateInterval::format() - Formats the interval
- DateTime::add() - Adds an amount of days, months, years, hours, minutes and seconds to a DateTime object
- DateTime::sub() - Subtracts an amount of days, months, years, hours, minutes and seconds from a DateTime object
DateTime::format
date_format
(PHP 5 >= 5.2.0)
DateTime::format -- date_format — Returns date formatted according to given format
Opis
Styl obiektowy
$format
)Styl proceduralny
Returns date formatted according to given format.
Parametry
-
object -
Tylko styl proceduralny: Obiekt DateTime zwracany przez date_create()
-
format -
Format accepted by date().
Zwracane wartości
Returns the formatted date string on success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 DateTime::format() example
Styl obiektowy
<?php
$date = new DateTime('2000-01-01');
echo $date->format('Y-m-d H:i:s');
?>
Styl proceduralny
<?php
$date = date_create('2000-01-01');
echo date_format($date, 'Y-m-d H:i:s');
?>
Powyższy przykład wyświetli:
2000-01-01 00:00:00
Notatki
This method does not use locales. All output is in English.
Zobacz też:
- date() - Formatuje lokalny czas/datę
DateTime::getLastErrors
date_get_last_errors
(PHP 5 >= 5.3.0)
DateTime::getLastErrors -- date_get_last_errors — Returns the warnings and errors
Opis
Styl obiektowy
Styl proceduralny
Returns an array of warnings and errors found while parsing a date/time string.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns array containing info about warnings and errors.
Przykłady
Przykład #1 DateTime::getLastErrors() example
Styl obiektowy
<?php
try {
$date = new DateTime('asdfasdf');
} catch (Exception $e) {
// For demonstration purposes only...
print_r(DateTime::getLastErrors());
// The real object oriented way to do this is
// echo $e->getMessage();
}
?>
Styl proceduralny
<?php
$date = date_create('asdfasdf');
print_r(date_get_last_errors());
?>
Powyższe przykłady wyświetlą:
Array
(
[warning_count] => 1
[warnings] => Array
(
[6] => Double timezone specification
)
[error_count] => 1
[errors] => Array
(
[0] => The timezone could not be found in the database
)
)
DateTime::getOffset
date_offset_get
(PHP 5 >= 5.2.0)
DateTime::getOffset -- date_offset_get — Returns the timezone offset
Opis
Styl obiektowy
Styl proceduralny
Returns the timezone offset.
Parametry
-
object -
Tylko styl proceduralny: Obiekt DateTime zwracany przez date_create()
Zwracane wartości
Returns the timezone offset in seconds from UTC on success
lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 DateTime::getOffset() example
Styl obiektowy
<?php
$winter = new DateTime('2010-12-21', new DateTimeZone('America/New_York'));
$summer = new DateTime('2008-06-21', new DateTimeZone('America/New_York'));
echo $winter->getOffset() . "\n";
echo $summer->getOffset() . "\n";
?>
Styl proceduralny
<?php
$winter = date_create('2010-12-21', timezone_open('America/New_York'));
$summer = date_create('2008-06-21', timezone_open('America/New_York'));
echo date_offset_get($winter) . "\n";
echo date_offset_get($summer) . "\n";
?>
Powyższe przykłady wyświetlą:
-18000 -14400
Note: -18000 = -5 hours, -14400 = -4 hours.
DateTime::getTimestamp
date_timestamp_get
(PHP 5 >= 5.3.0)
DateTime::getTimestamp -- date_timestamp_get — Gets the Unix timestamp
Opis
Styl obiektowy
Styl proceduralny
Gets the Unix timestamp.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the Unix timestamp representing the date.
Przykłady
Przykład #1 DateTime::getTimestamp() example
Styl obiektowy
<?php
$date = new DateTime();
echo $date->getTimestamp();
?>
Styl proceduralny
<?php
$date = date_create();
echo date_timestamp_get($date);
?>
Powyższe przykłady wyświetlą coś podobnego do:
1272509157
Notatki
Using U as the parameter to DateTime::format() is an alternative when using PHP 5.2.
Zobacz też:
- DateTime::setTimestamp() - Sets the date and time based on an Unix timestamp
- DateTime::format() - Returns date formatted according to given format
DateTime::getTimezone
date_timezone_get
(PHP 5 >= 5.2.0)
DateTime::getTimezone -- date_timezone_get — Return time zone relative to given DateTime
Opis
Styl obiektowy
Styl proceduralny
Return time zone relative to given DateTime.
Parametry
-
object -
Tylko styl proceduralny: Obiekt DateTime zwracany przez date_create()
Zwracane wartości
Returns a DateTimeZone object on success
lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 DateTime::getTimezone() example
Styl obiektowy
<?php
$date = new DateTime(null, new DateTimeZone('Europe/London'));
$tz = $date->getTimezone();
echo $tz->getName();
?>
Styl proceduralny
<?php
$date = date_create(null, timezone_open('Europe/London'));
$tz = date_timezone_get($date);
echo timezone_name_get($tz);
?>
Powyższe przykłady wyświetlą:
Europe/London
Zobacz też:
- DateTime::setTimezone() - Sets the time zone for the DateTime object
DateTime::modify
date_modify
(PHP 5 >= 5.2.0)
DateTime::modify -- date_modify — Alters the timestamp
Opis
Styl obiektowy
Styl proceduralny
Alter the timestamp of a DateTime object by incrementing or decrementing in a format accepted by strtotime().
Parametry
-
object -
Tylko styl proceduralny: Obiekt DateTime zwracany przez date_create(). Funkcja modyfikuje ten obiekt.
-
modify -
Łańcuch daty/czasu. Prawidłowe formaty są wyjaśnione pod adresem Formaty daty i czasu.
Zwracane wartości
Zwraca zmodyfikowany obiekt DateTime lub FALSE w przypadku niepowodzenia.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.6 | Absolute date/time statements now take effect. Previously, only relative parts were used. |
| 5.3.0 | Zmieniono zwracaną
wartość w przypadku powodzenia z NULL na DateTime. |
Przykłady
Przykład #1 DateTime::modify() example
Styl obiektowy
<?php
$date = new DateTime('2006-12-12');
$date->modify('+1 day');
echo $date->format('Y-m-d');
?>
Styl proceduralny
<?php
$date = date_create('2006-12-12');
date_modify($date, '+1 day');
echo date_format($date, 'Y-m-d');
?>
Powyższe przykłady wyświetlą:
2006-12-13
Przykład #2 Beware when adding or subtracting months
<?php
$date = new DateTime('2000-12-31');
$date->modify('+1 month');
echo $date->format('Y-m-d') . "\n";
$date->modify('+1 month');
echo $date->format('Y-m-d') . "\n";
?>
Powyższy przykład wyświetli:
2001-01-31 2001-03-03
Zobacz też:
- strtotime() - Parsuje większość angielskich tekstowych opisów daty i czasu do uniksowego znacznika czasu
- DateTime::add() - Adds an amount of days, months, years, hours, minutes and seconds to a DateTime object
- DateTime::sub() - Subtracts an amount of days, months, years, hours, minutes and seconds from a DateTime object
- DateTime::setDate() - Sets the date
- DateTime::setISODate() - Sets the ISO date
- DateTime::setTime() - Sets the time
- DateTime::setTimestamp() - Sets the date and time based on an Unix timestamp
DateTime::__set_state
(PHP 5 >= 5.2.0)
DateTime::__set_state — The __set_state handler
Parametry
-
array -
Initialization array.
Zwracane wartości
Returns a new instance of a DateTime object.
DateTime::setDate
date_date_set
(PHP 5 >= 5.2.0)
DateTime::setDate -- date_date_set — Sets the date
Opis
Styl obiektowy
Styl proceduralny
Resets the current date of the DateTime object to a different date.
Parametry
-
object -
Tylko styl proceduralny: Obiekt DateTime zwracany przez date_create(). Funkcja modyfikuje ten obiekt.
-
year -
Year of the date.
-
month -
Month of the date.
-
day -
Day of the date.
Zwracane wartości
Zwraca zmodyfikowany obiekt DateTime lub FALSE w przypadku niepowodzenia.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.0 | Zmieniono zwracaną
wartość w przypadku powodzenia z NULL na DateTime. |
Przykłady
Przykład #1 DateTime::setDate() example
Styl obiektowy
<?php
$date = new DateTime();
$date->setDate(2001, 2, 3);
echo $date->format('Y-m-d');
?>
Styl proceduralny
<?php
$date = date_create();
date_date_set($date, 2001, 2, 3);
echo date_format($date, 'Y-m-d');
?>
Powyższe przykłady wyświetlą:
2001-02-03
Przykład #2 Values exceeding ranges are added to their parent values
<?php
$date = new DateTime();
$date->setDate(2001, 2, 28);
echo $date->format('Y-m-d') . "\n";
$date->setDate(2001, 2, 29);
echo $date->format('Y-m-d') . "\n";
$date->setDate(2001, 14, 3);
echo $date->format('Y-m-d') . "\n";
?>
Powyższy przykład wyświetli:
2001-02-28 2001-03-01 2002-02-03
Zobacz też:
- DateTime::setISODate() - Sets the ISO date
- DateTime::setTime() - Sets the time
DateTime::setISODate
date_isodate_set
(PHP 5 >= 5.2.0)
DateTime::setISODate -- date_isodate_set — Sets the ISO date
Opis
Styl obiektowy
Styl proceduralny
Set a date according to the ISO 8601 standard - using weeks and day offsets rather than specific dates.
Parametry
-
object -
Tylko styl proceduralny: Obiekt DateTime zwracany przez date_create(). Funkcja modyfikuje ten obiekt.
-
year -
Year of the date.
-
week -
Week of the date.
-
day -
Offset from the first day of the week.
Zwracane wartości
Zwraca zmodyfikowany obiekt DateTime lub FALSE w przypadku niepowodzenia.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.0 | Zmieniono zwracaną
wartość w przypadku powodzenia z NULL na DateTime. |
Przykłady
Przykład #1 DateTime::setISODate() example
Styl obiektowy
<?php
$date = new DateTime();
$date->setISODate(2008, 2);
echo $date->format('Y-m-d') . "\n";
$date->setISODate(2008, 2, 7);
echo $date->format('Y-m-d') . "\n";
?>
Styl proceduralny
<?php
$date = date_create();
date_isodate_set($date, 2008, 2);
echo date_format($date, 'Y-m-d') . "\n";
date_isodate_set($date, 2008, 2, 7);
echo date_format($date, 'Y-m-d') . "\n";
?>
Powyższe przykłady wyświetlą:
2008-01-07 2008-01-13
Przykład #2 Values exceeding ranges are added to their parent values
<?php
$date = new DateTime();
$date->setISODate(2008, 2, 7);
echo $date->format('Y-m-d') . "\n";
$date->setISODate(2008, 2, 8);
echo $date->format('Y-m-d') . "\n";
$date->setISODate(2008, 53, 7);
echo $date->format('Y-m-d') . "\n";
?>
Powyższy przykład wyświetli:
2008-01-13 2008-01-14 2009-01-04
Przykład #3 Finding the month a week is in
<?php
$date = new DateTime();
$date->setISODate(2008, 14);
echo $date->format('n');
?>
Powyższe przykłady wyświetlą:
3
Zobacz też:
- DateTime::setDate() - Sets the date
- DateTime::setTime() - Sets the time
DateTime::setTime
date_time_set
(PHP 5 >= 5.2.0)
DateTime::setTime -- date_time_set — Sets the time
Opis
Styl obiektowy
Styl proceduralny
Resets the current time of the DateTime object to a different time.
Parametry
-
object -
Tylko styl proceduralny: Obiekt DateTime zwracany przez date_create(). Funkcja modyfikuje ten obiekt.
-
hour -
Hour of the time.
-
minute -
Minute of the time.
-
second -
Second of the time.
Zwracane wartości
Zwraca zmodyfikowany obiekt DateTime lub FALSE w przypadku niepowodzenia.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.0 | Zmieniono zwracaną
wartość w przypadku powodzenia z NULL na DateTime. |
Przykłady
Przykład #1 DateTime::setTime() example
Styl obiektowy
<?php
$date = new DateTime('2001-01-01');
$date->setTime(14, 55);
echo $date->format('Y-m-d H:i:s') . "\n";
$date->setTime(14, 55, 24);
echo $date->format('Y-m-d H:i:s') . "\n";
?>
Styl proceduralny
<?php
$date = date_create('2001-01-01');
date_time_set($date, 14, 55);
echo date_format($date, 'Y-m-d H:i:s') . "\n";
date_time_set($date, 14, 55, 24);
echo date_format($date, 'Y-m-d H:i:s') . "\n";
?>
Powyższe przykłady wyświetlą coś podobnego do:
2000-01-01 14:55:00 2000-01-01 14:55:24
Przykład #2 Values exceeding ranges are added to their parent values
<?php
$date = new DateTime('2001-01-01');
$date->setTime(14, 55, 24);
echo $date->format('Y-m-d H:i:s') . "\n";
$date->setTime(14, 55, 65);
echo $date->format('Y-m-d H:i:s') . "\n";
$date->setTime(14, 65, 24);
echo $date->format('Y-m-d H:i:s') . "\n";
$date->setTime(25, 55, 24);
echo $date->format('Y-m-d H:i:s') . "\n";
?>
Powyższy przykład wyświetli:
2001-01-01 14:55:24 2001-01-01 14:56:05 2001-01-01 15:05:24 2001-01-02 01:55:24
Zobacz też:
- DateTime::setDate() - Sets the date
- DateTime::setISODate() - Sets the ISO date
DateTime::setTimestamp
date_timestamp_set
(PHP 5 >= 5.3.0)
DateTime::setTimestamp -- date_timestamp_set — Sets the date and time based on an Unix timestamp
Opis
Styl obiektowy
Styl proceduralny
Sets the date and time based on an Unix timestamp.
Parametry
-
object -
Tylko styl proceduralny: Obiekt DateTime zwracany przez date_create(). Funkcja modyfikuje ten obiekt.
-
unixtimestamp -
Unix timestamp representing the date.
Zwracane wartości
Zwraca zmodyfikowany obiekt DateTime lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 DateTime::setTimestamp() example
Styl obiektowy
<?php
$date = new DateTime();
echo $date->format('U = Y-m-d H:i:s') . "\n";
$date->setTimestamp(1171502725);
echo $date->format('U = Y-m-d H:i:s') . "\n";
?>
Styl proceduralny
<?php
$date = date_create();
echo date_format($date, 'U = Y-m-d H:i:s') . "\n";
date_timestamp_set($date, 1171502725);
echo date_format($date, 'U = Y-m-d H:i:s') . "\n";
?>
Powyższe przykłady wyświetlą coś podobnego do:
1272508903 = 2010-04-28 22:41:43 1171502725 = 2007-02-14 20:25:25
Notatki
Using the Unix timestamp format to construct a new DateTime object is an alternative when using PHP 5.2, as shown in the example below.
Przykład #2 DateTime::setTimestamp() alternative in PHP 5.2
<?php
$ts = 1171502725;
$date = new DateTime("@$ts");
echo $date->format('U = Y-m-d H:i:s') . "\n";
?>
Powyższy przykład wyświetli coś podobnego do:
1171502725 = 2007-02-14 20:25:25
Zobacz też:
- DateTime::getTimestamp() - Gets the Unix timestamp
DateTime::setTimezone
date_timezone_set
(PHP 5 >= 5.2.0)
DateTime::setTimezone -- date_timezone_set — Sets the time zone for the DateTime object
Opis
Styl obiektowy
Styl proceduralny
Parametry
-
object -
Tylko styl proceduralny: Obiekt DateTime zwracany przez date_create(). Funkcja modyfikuje ten obiekt.
-
timezone -
A DateTimeZone object representing the desired time zone.
Zwracane wartości
Zwraca zmodyfikowany obiekt DateTime lub FALSE w przypadku niepowodzenia.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.0 | Zmieniono zwracaną
wartość w przypadku powodzenia z NULL na DateTime. |
Przykłady
Przykład #1 DateTime::setTimeZone() example
Styl obiektowy
<?php
$date = new DateTime('2000-01-01', new DateTimeZone('Pacific/Nauru'));
echo $date->format('Y-m-d H:i:sP') . "\n";
$date->setTimezone(new DateTimeZone('Pacific/Chatham'));
echo $date->format('Y-m-d H:i:sP') . "\n";
?>
Styl proceduralny
<?php
$date = date_create('2000-01-01', timezone_open('Pacific/Nauru'));
echo date_format($date, 'Y-m-d H:i:sP') . "\n";
date_timezone_set($date, timezone_open('Pacific/Chatham'));
echo date_format($date, 'Y-m-d H:i:sP') . "\n";
?>
Powyższe przykłady wyświetlą:
2000-01-01 00:00:00+12:00 2000-01-01 01:45:00+13:45
Zobacz też:
- DateTime::getTimezone() - Return time zone relative to given DateTime
- DateTimeZone::__construct() - Creates new DateTimeZone object
DateTime::sub
date_sub
(PHP 5 >= 5.3.0)
DateTime::sub -- date_sub — Subtracts an amount of days, months, years, hours, minutes and seconds from a DateTime object
Opis
Styl obiektowy
Styl proceduralny
Subtracts the specified DateInterval object from the specified DateTime object.
Parametry
-
object -
Tylko styl proceduralny: Obiekt DateTime zwracany przez date_create(). Funkcja modyfikuje ten obiekt.
-
interval -
A DateInterval object
Zwracane wartości
Zwraca zmodyfikowany obiekt DateTime lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 DateTime::sub() example
Styl obiektowy
<?php
$date = new DateTime('2000-01-20');
$date->sub(new DateInterval('P10D'));
echo $date->format('Y-m-d') . "\n";
?>
Styl proceduralny
<?php
$date = date_create('2000-01-20');
date_sub($date, date_interval_create_from_date_string('10 days'));
echo date_format($date, 'Y-m-d');
?>
Powyższe przykłady wyświetlą:
2000-01-10
Przykład #2 Further DateTime::sub() examples
<?php
$date = new DateTime('2000-01-20');
$date->sub(new DateInterval('PT10H30S'));
echo $date->format('Y-m-d H:i:s') . "\n";
$date = new DateTime('2000-01-20');
$date->sub(new DateInterval('P7Y5M4DT4H3M2S'));
echo $date->format('Y-m-d H:i:s') . "\n";
?>
Powyższy przykład wyświetli:
2000-01-19 13:59:30 1992-08-15 19:56:58
Przykład #3 Beware when subtracting months
<?php
$date = new DateTime('2001-04-30');
$interval = new DateInterval('P1M');
$date->sub($interval);
echo $date->format('Y-m-d') . "\n";
$date->sub($interval);
echo $date->format('Y-m-d') . "\n";
?>
Powyższy przykład wyświetli:
2001-03-30 2001-03-02
Notatki
DateTime::modify() is an alternative when using PHP 5.2.
Zobacz też:
- DateTime::add() - Adds an amount of days, months, years, hours, minutes and seconds to a DateTime object
- DateTime::diff() - Returns the difference between two DateTime objects
- DateTime::modify() - Alters the timestamp
DateTime::__wakeup
(PHP 5 >= 5.2.0)
DateTime::__wakeup — The __wakeup handler
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Initializes a DateTime object.
Spis treści
- DateTime::add — Adds an amount of days, months, years, hours, minutes and seconds to a DateTime object
- DateTime::__construct — Returns new DateTime object
- DateTime::createFromFormat — Returns new DateTime object formatted according to the specified format
- DateTime::diff — Returns the difference between two DateTime objects
- DateTime::format — Returns date formatted according to given format
- DateTime::getLastErrors — Returns the warnings and errors
- DateTime::getOffset — Returns the timezone offset
- DateTime::getTimestamp — Gets the Unix timestamp
- DateTime::getTimezone — Return time zone relative to given DateTime
- DateTime::modify — Alters the timestamp
- DateTime::__set_state — The __set_state handler
- DateTime::setDate — Sets the date
- DateTime::setISODate — Sets the ISO date
- DateTime::setTime — Sets the time
- DateTime::setTimestamp — Sets the date and time based on an Unix timestamp
- DateTime::setTimezone — Sets the time zone for the DateTime object
- DateTime::sub — Subtracts an amount of days, months, years, hours, minutes and seconds from a DateTime object
- DateTime::__wakeup — The __wakeup handler
The DateTimeZone class
(PHP 5 >= 5.2.0)
Wstęp
Representation of time zone.
Krótki opis klasy
Stałe predefiniowane
-
DateTimeZone::AFRICA -
Africa time zones.
-
DateTimeZone::AMERICA -
America time zones.
-
DateTimeZone::ANTARCTICA -
Antarctica time zones.
-
DateTimeZone::ARCTIC -
Arctic time zones.
-
DateTimeZone::ASIA -
Asia time zones.
-
DateTimeZone::ATLANTIC -
Atlantic time zones.
-
DateTimeZone::AUSTRALIA -
Australia time zones.
-
DateTimeZone::EUROPE -
Europe time zones.
-
DateTimeZone::INDIAN -
Indian time zones.
-
DateTimeZone::PACIFIC -
Pacific time zones.
-
DateTimeZone::UTC -
UTC time zones.
-
DateTimeZone::ALL -
All time zones.
-
DateTimeZone::ALL_WITH_BC -
All time zones including backwards compatible.
-
DateTimeZone::PER_COUNTRY -
Time zones per country.
DateTimeZone::__construct
timezone_open
(PHP 5 >= 5.2.0)
DateTimeZone::__construct -- timezone_open — Creates new DateTimeZone object
Opis
Styl obiektowy
$timezone
)Styl proceduralny
Creates new DateTimeZone object.
Zwracane wartości
Returns DateTimeZone on success.
Styl proceduralny zwraca FALSE w przypadku niepowodzenia.
Błędy/Wyjątki
This method throws Exception if the timezone supplied is not recognised as a valid timezone.
Przykłady
Przykład #1 Catching errors when instantiating DateTimeZone
<?php
// Error handling by catching exceptions
$timezones = array('Europe/London', 'Mars/Phobos', 'Jupiter/Europa');
foreach ($timezones as $tz) {
try {
$mars = new DateTimeZone($tz);
} catch(Exception $e) {
echo $e->getMessage() . '<br />';
}
}
?>
Powyższy przykład wyświetli:
DateTimeZone::__construct() [datetimezone.--construct]: Unknown or bad timezone (Mars/Phobos) DateTimeZone::__construct() [datetimezone.--construct]: Unknown or bad timezone (Jupiter/Europa)
DateTimeZone::getLocation
timezone_location_get
(PHP 5 >= 5.3.0)
DateTimeZone::getLocation -- timezone_location_get — Returns location information for a timezone
Opis
Styl obiektowy
Styl proceduralny
Returns location information for a timezone, including country code, latitude/longitude and comments.
Zwracane wartości
Array containing location information about timezone.
Przykłady
Przykład #1 DateTimeZone::getLocation() example
<?php
$tz = new DateTimeZone("Europe/Prague");
print_r($tz->getLocation());
print_r(timezone_location_get($tz));
?>
Powyższy przykład wyświetli:
Array
(
[country_code] => CZ
[latitude] => 50.08333
[longitude] => 14.43333
[comments] =>
)
Array
(
[country_code] => CZ
[latitude] => 50.08333
[longitude] => 14.43333
[comments] =>
)
DateTimeZone::getName
timezone_name_get
(PHP 5 >= 5.2.0)
DateTimeZone::getName -- timezone_name_get — Returns the name of the timezone
Opis
Styl obiektowy
Styl proceduralny
Returns the name of the timezone.
Parametry
-
object -
The DateTimeZone for which to get a name.
Zwracane wartości
One of the timezone names in the list of timezones.
DateTimeZone::getOffset
timezone_offset_get
(PHP 5 >= 5.2.0)
DateTimeZone::getOffset -- timezone_offset_get — Returns the timezone offset from GMT
Opis
Styl obiektowy
Styl proceduralny
This function returns the offset to GMT for the date/time specified in the
datetime parameter. The GMT offset is calculated
with the timezone information contained in the DateTimeZone object being used.
Parametry
-
object -
Tylko styl proceduralny: Obiekt DateTimeZone zwracany przez timezone_open()
-
datetime -
DateTime that contains the date/time to compute the offset from.
Zwracane wartości
Returns time zone offset in seconds on success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 DateTimeZone::getOffset() examples
<?php
// Create two timezone objects, one for Taipei (Taiwan) and one for
// Tokyo (Japan)
$dateTimeZoneTaipei = new DateTimeZone("Asia/Taipei");
$dateTimeZoneJapan = new DateTimeZone("Asia/Tokyo");
// Create two DateTime objects that will contain the same Unix timestamp, but
// have different timezones attached to them.
$dateTimeTaipei = new DateTime("now", $dateTimeZoneTaipei);
$dateTimeJapan = new DateTime("now", $dateTimeZoneJapan);
// Calculate the GMT offset for the date/time contained in the $dateTimeTaipei
// object, but using the timezone rules as defined for Tokyo
// ($dateTimeZoneJapan).
$timeOffset = $dateTimeZoneJapan->getOffset($dateTimeTaipei);
// Should show int(32400) (for dates after Sat Sep 8 01:00:00 1951 JST).
var_dump($timeOffset);
?>
DateTimeZone::getTransitions
timezone_transitions_get
(PHP 5 >= 5.2.0)
DateTimeZone::getTransitions -- timezone_transitions_get — Returns all transitions for the timezone
Opis
Styl obiektowy
$timestamp_begin
[, int $timestamp_end
]] )Styl proceduralny
$object
[, int $timestamp_begin
[, int $timestamp_end
]] )Parametry
-
object -
Tylko styl proceduralny: Obiekt DateTimeZone zwracany przez timezone_open()
-
timestamp_begin -
Begin timestamp.
-
timestamp_end -
End timestamp.
Zwracane wartości
Returns numerically indexed array containing associative array with all
transitions on success lub FALSE w przypadku niepowodzenia.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.0 |
The optional timestamp_begin and timestamp_end
were added.
|
Przykłady
Przykład #1 A timezone_transitions_get() example
<?php
$timezone = new DateTimeZone("Europe/London");
$transitions = $timezone->getTransitions();
print_r(array_slice($transitions, 0, 3));
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[0] => Array
(
[ts] => -9223372036854775808
[time] => -292277022657-01-27T08:29:52+0000
[offset] => 3600
[isdst] => 1
[abbr] => BST
)
[1] => Array
(
[ts] => -1691964000
[time] => 1916-05-21T02:00:00+0000
[offset] => 3600
[isdst] => 1
[abbr] => BST
)
[2] => Array
(
[ts] => -1680472800
[time] => 1916-10-01T02:00:00+0000
[offset] => 0
[isdst] =>
[abbr] => GMT
)
)
DateTimeZone::listAbbreviations
timezone_abbreviations_list
(PHP 5 >= 5.2.0)
DateTimeZone::listAbbreviations -- timezone_abbreviations_list — Returns associative array containing dst, offset and the timezone name
Opis
Styl obiektowy
Styl proceduralny
Zwracane wartości
Returns array on success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 A timezone_abbreviations_list() example
<?php
$timezone_abbreviations = DateTimeZone::listAbbreviations();
print_r($timezone_abbreviations["acst"]);
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[0] => Array
(
[dst] => 1
[offset] => -14400
[timezone_id] => America/Porto_Acre
)
[1] => Array
(
[dst] => 1
[offset] => -14400
[timezone_id] => America/Eirunepe
)
[2] => Array
(
[dst] => 1
[offset] => -14400
[timezone_id] => America/Rio_Branco
)
[3] => Array
(
[dst] => 1
[offset] => -14400
[timezone_id] => Brazil/Acre
)
)
DateTimeZone::listIdentifiers
timezone_identifiers_list
(PHP 5 >= 5.2.0)
DateTimeZone::listIdentifiers -- timezone_identifiers_list — Returns numerically index array with all timezone identifiers
Opis
Styl obiektowy
$what = DateTimeZone::ALL
[, string $country = NULL
]] )Styl proceduralny
Parametry
-
what -
One of DateTimeZone class constants.
-
country -
A two-letter ISO 3166-1 compatible country code.
Informacja: This option is only used when
whatis set toDateTimeZone::PER_COUNTRY.
Zwracane wartości
Returns array on success lub FALSE w przypadku niepowodzenia.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.0 |
Added the optional what and
country parameters.
|
Przykłady
Przykład #1 A timezone_identifiers_list() example
<?php
$timezone_identifiers = DateTimeZone::listIdentifiers();
for ($i=0; $i < 5; $i++) {
echo "$timezone_identifiers[$i]\n";
}
?>
Powyższy przykład wyświetli coś podobnego do:
Africa/Abidjan Africa/Accra Africa/Addis_Ababa Africa/Algiers Africa/Asmara
Spis treści
- DateTimeZone::__construct — Creates new DateTimeZone object
- DateTimeZone::getLocation — Returns location information for a timezone
- DateTimeZone::getName — Returns the name of the timezone
- DateTimeZone::getOffset — Returns the timezone offset from GMT
- DateTimeZone::getTransitions — Returns all transitions for the timezone
- DateTimeZone::listAbbreviations — Returns associative array containing dst, offset and the timezone name
- DateTimeZone::listIdentifiers — Returns numerically index array with all timezone identifiers
The DateInterval class
(PHP 5 >= 5.3.0)
Wstęp
Representation of date interval. A date interval stores either a fixed amount of time (in years, months, days, hours etc) or a relative time string in the format that DateTime's constructor supports.
Krótki opis klasy
Właściwości
- y
-
Number of years.
- m
-
Number of months.
- d
-
Number of days.
- h
-
Number of hours.
- i
-
Number of minutes.
- s
-
Number of seconds.
- invert
-
Is 1 if the interval is inverted and 0 otherwise. See DateInterval::format().
- days
-
Total number of days between the starting and ending dates in a DateTime::diff() calculation. days will be
FALSEin other circumstances.
DateInterval::__construct
(PHP 5 >= 5.3.0)
DateInterval::__construct — Creates new DateInterval object
Opis
$interval_spec
)Creates new DateInterval object.
Parametry
-
interval_spec -
Interval specification.
The format starts with the letter P, for "period." Each duration period is represented by an integer value followed by a period designator. If the duration contains time elements, that portion of the specification is preceded by the letter T.
interval_specPeriod DesignatorsPeriod Designator Description Y years M months D days W weeks. These get converted into days, so can not be combined with D. H hours M minutes S seconds Here are some simple examples. Two days is P2D. Two seconds is PT2S. Six years and five minutes is P6YT5M.
Informacja:
The unit types must be entered from the largest scale unit on the left to the smallest scale unit on the right. So years before months, months before days, days before minutes, etc. Thus one year and four days must be represented as P1Y4D, not P4D1Y.
The specification can also be represented as a date time. A sample of one year and four days would be P0001-00-04T00:00:00. But the values in this format can not exceed a given period's roll-over-point (e.g. 25 hours is invalid).
These formats are based on the » ISO 8601 duration specification.
Przykłady
Przykład #1 DateInterval example
<?php
$interval = new DateInterval('P2Y4DT6H8M');
var_dump($interval);
?>
Powyższy przykład wyświetli:
object(DateInterval)#1 (8) {
["y"]=>
int(2)
["m"]=>
int(0)
["d"]=>
int(4)
["h"]=>
int(6)
["i"]=>
int(8)
["s"]=>
int(0)
["invert"]=>
int(0)
["days"]=>
bool(false)
}
Zobacz też:
- DateInterval::format() - Formats the interval
- DateTime::add() - Adds an amount of days, months, years, hours, minutes and seconds to a DateTime object
- DateTime::sub() - Subtracts an amount of days, months, years, hours, minutes and seconds from a DateTime object
- DateTime::diff() - Returns the difference between two DateTime objects
DateInterval::createFromDateString
(PHP 5 >= 5.3.0)
DateInterval::createFromDateString — Sets up a DateInterval from the relative parts of the string
Opis
Uses the normal date parsers and sets up a DateInterval from the relative parts of the parsed string.
Parametry
-
time -
Date with relative parts.
Zwracane wartości
Returns new DateInterval instance if success.
DateInterval::format
(PHP 5 >= 5.3.0)
DateInterval::format — Formats the interval
Opis
$format
)Formats the interval.
Parametry
-
format -
The following characters are recognized in the formatparameter string. Each format character must be prefixed by a percent sign (%).formatcharacterDescription Example values % Literal % % Y Years, numeric, at least 2 digits with leading 0 01, 03 y Years, numeric 1, 3 M Months, numeric, at least 2 digits with leading 0 01, 03, 12 m Months, numeric 1, 3, 12 D Days, numeric, at least 2 digits with leading 0 01, 03, 31 d Days, numeric 1, 3, 31 a Total amount of days 4, 18, 8123 H Hours, numeric, at least 2 digits with leading 0 01, 03, 23 h Hours, numeric 1, 3, 23 I Minutes, numeric, at least 2 digits with leading 0 01, 03, 59 i Minutes, numeric 1, 3, 59 S Seconds, numeric, at least 2 digits with leading 0 01, 03, 57 s Seconds, numeric 1, 3, 57 R Sign "-" when negative, "+" when positive -, + r Sign "-" when negative, empty when positive -,
Zwracane wartości
Returns the formatted interval.
Notatki
Informacja:
The DateInterval::format() method does not recalculate carry over points in time strings nor in date segments. This is expected because it is not possible to overflow values like "32 days" which could be interpreted as anything from "1 month and 4 days" to "1 month and 1 day".
Przykłady
Przykład #1 DateInterval example
<?php
$interval = new DateInterval('P2Y4DT6H8M');
echo $interval->format('%d days');
?>
Powyższy przykład wyświetli:
4 days
Przykład #2 DateInterval and carry over points
<?php
$interval = new DateInterval('P32D');
echo $interval->format('%d days');
?>
Powyższy przykład wyświetli:
32 days
Przykład #3 DateInterval and DateTime::diff() with the %a and %d modifiers
<?php
$january = new DateTime('2010-01-01');
$february = new DateTime('2010-02-01');
$interval = $february->diff($january);
// %a will output the total number of days.
echo $interval->format('%a total days')."\n";
// While %d will only output the number of days not already covered by the
// month.
echo $interval->format('%m month, %d days');
?>
Powyższy przykład wyświetli:
31 total days 1 month, 0 days
Spis treści
- DateInterval::__construct — Creates new DateInterval object
- DateInterval::createFromDateString — Sets up a DateInterval from the relative parts of the string
- DateInterval::format — Formats the interval
The DatePeriod class
(PHP 5 >= 5.3.0)
Wstęp
Representation of date period.
Krótki opis klasy
$start
, DateInterval $interval
, int $recurrences
[, int $options
] )Stałe predefiniowane
-
DatePeriod::EXCLUDE_START_DATE -
Exclude start date, used in DatePeriod::__construct().
DatePeriod::__construct
(PHP 5 >= 5.3.0)
DatePeriod::__construct — Creates new DatePeriod object
Opis
$start
, DateInterval $interval
, int $recurrences
[, int $options
] )$start
, DateInterval $interval
, DateTime $end
[, int $options
] )$isostr
[, int $options
] )Creates new DatePeriod object.
Parametry
-
start -
Start date.
-
interval -
Interval.
-
recurrences -
Number of recurrences.
-
end -
End date.
-
isostr -
String containing the ISO interval.
-
options -
Can be set to
DatePeriod::EXCLUDE_START_DATE.
Spis treści
- DatePeriod::__construct — Creates new DatePeriod object
Funkcje daty i czasu
checkdate
(PHP 4, PHP 5)
checkdate — Waliduje datę gregoriańską
Opis
$miesiąc
, int $dzień
, int $rok
)Sprawdza prawdziwość daty podanej jako argument. Data jest uznana za prawidłową, jeśli wszystkie dane parametry są prawidłowe.
Parametry
-
miesiąc -
Miesiąc zawiera się w przedziale od 1 do 12 włącznie.
-
dzień -
Dzień wewnątrz przedziału dozwolonych numerów dni dla danego parametru
miesiąc. Każdyrokprzestępny jest brany pod uwagę. -
rok -
Rok zawiera się w przedziale pomiędzy 1 i 32767 włącznie.
Zwracane wartości
Zwraca TRUE jeśli dana data jest poprawna; w przeciwnym razie zwraca FALSE.
Przykłady
Przykład #1 checkdate() - przykład
<?php
var_dump(checkdate(12, 31, 2000));
var_dump(checkdate(2, 29, 2001));
?>
Powyższy przykład wyświetli:
bool(true) bool(false)
Zobacz też:
- mktime() - Oblicza uniksowy znacznik czasu dla podanej daty
- strtotime() - Parsuje większość angielskich tekstowych opisów daty i czasu do uniksowego znacznika czasu
Opis
Ta funkcja jest aliasem dla: DateTime::add()
date_create_from_format
(PHP 5 >= 5.3.0)
date_create_from_format — Alias dla DateTime::createFromFormat()
Opis
Ta funkcja jest aliasem dla: DateTime::createFromFormat()
Opis
Ta funkcja jest aliasem dla: DateTime::__construct()
Opis
Ta funkcja jest aliasem dla: DateTime::setDate()
date_default_timezone_get
(PHP 5 >= 5.1.0)
date_default_timezone_get — Gets the default timezone used by all date/time functions in a script
Opis
In order of preference, this function returns the default timezone by:
-
Reading the timezone set using the date_default_timezone_set() function (if any)
-
Prior to PHP 5.4.0 only: Reading the TZ environment variable (if non empty)
-
Reading the value of the date.timezone ini option (if set)
-
Prior to PHP 5.4.0 only: Querying the host operating system (if supported and allowed by the OS). This uses an algorithm that has to guess the timezone. This is by no means going to work correctly for every situation. A warning is shown when this stage is reached. Do not rely on it to be guessed correctly, and set date.timezone to the correct timezone instead.
If none of the above succeed, date_default_timezone_get() will return a default timezone of UTC.
Zwracane wartości
Returns a string.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.4.0 | The TZ environment variable is no longer used to guess the timezone. |
| 5.4.0 | The timezone is no longer guessed from information available through the operating system as the guessed timezone can not be relied on. |
Przykłady
Przykład #1 Getting the default timezone
<?php
date_default_timezone_set('Europe/London');
if (date_default_timezone_get()) {
echo 'date_default_timezone_set: ' . date_default_timezone_get() . '<br />';
}
if (ini_get('date.timezone')) {
echo 'date.timezone: ' . ini_get('date.timezone');
}
?>
Powyższy przykład wyświetli coś podobnego do:
date_default_timezone_set: Europe/London date.timezone: Europe/London
Przykład #2 Getting the abbreviation of a timezone
<?php
date_default_timezone_set('America/Los_Angeles');
echo date_default_timezone_get() . ' => ' . date('e') . ' => ' . date('T');
?>
Powyższy przykład wyświetli:
America/Los_Angeles => America/Los_Angeles => PST
Zobacz też:
- date_default_timezone_set() - Sets the default timezone used by all date/time functions in a script
- Lista obsługiwanych stref czasowych
date_default_timezone_set
(PHP 5 >= 5.1.0)
date_default_timezone_set — Sets the default timezone used by all date/time functions in a script
Opis
$timezone_identifier
)date_default_timezone_set() sets the default timezone used by all date/time functions.
Informacja:
Since PHP 5.1.0 (when the date/time functions were rewritten), every call to a date/time function will generate a
E_NOTICEif the timezone isn't valid, and/or aE_WARNINGmessage if using the system settings or the TZ environment variable.
Instead of using this function to set the default timezone in your script, you can also use the INI setting date.timezone to set the default timezone.
Parametry
-
timezone_identifier -
The timezone identifier, like UTC or Europe/Lisbon. The list of valid identifiers is available in the Lista obsługiwanych stref czasowych.
Zwracane wartości
This function returns FALSE if the
timezone_identifier isn't valid, or TRUE
otherwise.
Przykłady
Przykład #1 Getting the default timezone
<?php
date_default_timezone_set('America/Los_Angeles');
$script_tz = date_default_timezone_get();
if (strcmp($script_tz, ini_get('date.timezone'))){
echo 'Script timezone differs from ini-set timezone.';
} else {
echo 'Script timezone and ini-set timezone match.';
}
?>
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.0 |
Now throws E_WARNING rather than
E_STRICT.
|
| 5.1.2 |
The function started to validate the
timezone_identifier parameter.
|
Zobacz też:
- date_default_timezone_get() - Gets the default timezone used by all date/time functions in a script
- Lista obsługiwanych stref czasowych
Opis
Ta funkcja jest aliasem dla: DateTime::diff()
Opis
Ta funkcja jest aliasem dla: DateTime::format()
Opis
Ta funkcja jest aliasem dla: DateTime::getLastErrors()
date_interval_create_from_date_string
(PHP 5 >= 5.3.0)
date_interval_create_from_date_string — Alias dla DateInterval::createFromDateString()
Opis
Ta funkcja jest aliasem dla: DateInterval::createFromDateString()
Opis
Ta funkcja jest aliasem dla: DateInterval::format()
Opis
Ta funkcja jest aliasem dla: DateTime::setISODate()
Opis
Ta funkcja jest aliasem dla: DateTime::modify()
Opis
Ta funkcja jest aliasem dla: DateTime::getOffset()
date_parse_from_format
(PHP 5 >= 5.3.0)
date_parse_from_format — Get info about given date formatted according to the specified format
Opis
$format
, string $date
)Returns associative array with detailed info about given date.
Parametry
-
format -
Format accepted by DateTime::createFromFormat().
-
date -
String representing the date.
Zwracane wartości
Returns associative array with detailed info about given date.
Przykłady
Przykład #1 date_parse_from_format() example
<?php
$date = "6.1.2009 13:00+01:00";
print_r(date_parse_from_format("j.n.Y H:iP", $date));
?>
Powyższy przykład wyświetli:
Array
(
[year] => 2009
[month] => 1
[day] => 6
[hour] => 13
[minute] => 0
[second] => 0
[fraction] =>
[warning_count] => 0
[warnings] => Array
(
)
[error_count] => 0
[errors] => Array
(
)
[is_localtime] => 1
[zone_type] => 1
[zone] => -60
[is_dst] =>
)
Zobacz też:
- DateTime::createFromFormat() - Returns new DateTime object formatted according to the specified format
- checkdate() - Waliduje datę gregoriańską
date_parse
(PHP 5 >= 5.2.0)
date_parse — Returns associative array with detailed info about given date
Opis
$date
)Zwracane wartości
Returns array with information about the parsed date
on success lub FALSE w przypadku niepowodzenia.
Błędy/Wyjątki
In case the date format has an error, the element 'errors' will contains the error messages.
Przykłady
Przykład #1 A date_parse() example
<?php
print_r(date_parse("2006-12-12 10:00:00.5"));
?>
Powyższy przykład wyświetli:
Array
(
[year] => 2006
[month] => 12
[day] => 12
[hour] => 10
[minute] => 0
[second] => 0
[fraction] => 0.5
[warning_count] => 0
[warnings] => Array()
[error_count] => 0
[errors] => Array()
[is_localtime] =>
)
Opis
Ta funkcja jest aliasem dla: DateTime::sub()
date_sun_info
(PHP 5 >= 5.1.2)
date_sun_info — Returns an array with information about sunset/sunrise and twilight begin/end
Opis
$time
, float $latitude
, float $longitude
)Parametry
-
time -
Timestamp.
-
latitude -
Latitude in degrees.
-
longitude -
Longitude in degrees.
Zwracane wartości
Returns array on success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 A date_sun_info() example
<?php
$sun_info = date_sun_info(strtotime("2006-12-12"), 31.7667, 35.2333);
foreach ($sun_info as $key => $val) {
echo "$key: " . date("H:i:s", $val) . "\n";
}
?>
Powyższy przykład wyświetli:
sunrise: 05:52:11 sunset: 15:41:21 transit: 10:46:46 civil_twilight_begin: 05:24:08 civil_twilight_end: 16:09:24 nautical_twilight_begin: 04:52:25 nautical_twilight_end: 16:41:06 astronomical_twilight_begin: 04:21:32 astronomical_twilight_end: 17:12:00
Zobacz też:
- date_sunrise() - Returns time of sunrise for a given day and location
- date_sunset() - Returns time of sunset for a given day and location
date_sunrise
(PHP 5)
date_sunrise — Returns time of sunrise for a given day and location
Opis
$timestamp
[, int $format = SUNFUNCS_RET_STRING
[, float $latitude = ini_get("date.default_latitude")
[, float $longitude = ini_get("date.default_longitude")
[, float $zenith = ini_get("date.sunrise_zenith")
[, float $gmt_offset = 0
]]]]] )
date_sunrise() returns the sunrise time for a given
day (specified as a timestamp) and location.
Parametry
-
timestamp -
The
timestampof the day from which the sunrise time is taken. -
format -
formatconstantsconstant description example SUNFUNCS_RET_STRING returns the result as string 16:46 SUNFUNCS_RET_DOUBLE returns the result as float 16.78243132 SUNFUNCS_RET_TIMESTAMP returns the result as integer (timestamp) 1095034606 -
latitude -
Defaults to North, pass in a negative value for South. See also: date.default_latitude
-
longitude -
Defaults to East, pass in a negative value for West. See also: date.default_longitude
-
zenith -
Default: date.sunrise_zenith
-
gmtoffset -
Specified in hours.
Zwracane wartości
Returns the sunrise time in a specified format on
success lub FALSE w przypadku niepowodzenia.
Błędy/Wyjątki
Każde wywołanie do funkcji date/time spowoduje wygenerowanie E_NOTICE
jeśli strefa czasowa jest nieprawidłowa, lub/i wiadomość E_STRICT
jeśli użyto ustawień systemu lub zmiennej środowiskowej TZ.
Patrz także date_default_timezone_set()
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.1.0 |
Teraz generuje błędy strefy czasowej o poziomie |
Przykłady
Przykład #1 date_sunrise() example
<?php
/* calculate the sunrise time for Lisbon, Portugal
Latitude: 38.4 North
Longitude: 9 West
Zenith ~= 90
offset: +1 GMT
*/
echo date("D M d Y"). ', sunrise time : ' .date_sunrise(time(), SUNFUNCS_RET_STRING, 38.4, -9, 90, 1);
?>
Powyższy przykład wyświetli coś podobnego do:
Mon Dec 20 2004, sunrise time : 08:54
date_sunset
(PHP 5)
date_sunset — Returns time of sunset for a given day and location
Opis
$timestamp
[, int $format = SUNFUNCS_RET_STRING
[, float $latitude = ini_get("date.default_latitude")
[, float $longitude = ini_get("date.default_longitude")
[, float $zenith = ini_get("date.sunset_zenith")
[, float $gmt_offset = 0
]]]]] )
date_sunset() returns the sunset time for a given
day (specified as a timestamp) and location.
Parametry
-
timestamp -
The
timestampof the day from which the sunset time is taken. -
format -
formatconstantsconstant description example SUNFUNCS_RET_STRING returns the result as string 16:46 SUNFUNCS_RET_DOUBLE returns the result as float 16.78243132 SUNFUNCS_RET_TIMESTAMP returns the result as integer (timestamp) 1095034606 -
latitude -
Defaults to North, pass in a negative value for South. See also: date.default_latitude
-
longitude -
Defaults to East, pass in a negative value for West. See also: date.default_longitude
-
zenith -
Default: date.sunset_zenith
-
gmtoffset -
Specified in hours.
Błędy/Wyjątki
Każde wywołanie do funkcji date/time spowoduje wygenerowanie E_NOTICE
jeśli strefa czasowa jest nieprawidłowa, lub/i wiadomość E_STRICT
jeśli użyto ustawień systemu lub zmiennej środowiskowej TZ.
Patrz także date_default_timezone_set()
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.1.0 |
Teraz generuje błędy strefy czasowej o poziomie |
Zwracane wartości
Returns the sunset time in a specified format on
success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 date_sunset() example
<?php
/* calculate the sunset time for Lisbon, Portugal
Latitude: 38.4 North
Longitude: 9 West
Zenith ~= 90
offset: +1 GMT
*/
echo date("D M d Y"). ', sunset time : ' .date_sunset(time(), SUNFUNCS_RET_STRING, 38.4, -9, 90, 1);
?>
Powyższy przykład wyświetli coś podobnego do:
Mon Dec 20 2004, sunset time : 18:13
Opis
Ta funkcja jest aliasem dla: DateTime::setTime()
Opis
Ta funkcja jest aliasem dla: DateTime::getTimestamp()
Opis
Ta funkcja jest aliasem dla: DateTime::setTimestamp()
Opis
Ta funkcja jest aliasem dla: DateTime::getTimezone()
Opis
Ta funkcja jest aliasem dla: DateTime::setTimezone()
date
(PHP 4, PHP 5)
date — Formatuje lokalny czas/datę
Opis
$format
[, int $znacznik_czasu
] )
Zwraca datę sformatowaną zgodnie z szablonem podanym w argumencie
jako znacznik_czasu, lub aktualnego czasu
w przypadku wywołania jej bez tego argumentu. Innymi słowy, znacznik_czasu
jest parametrem opcjonalnym, domyślnie pobierającym wartość funkcji time().
Parametry
-
format -
Format zwracanej daty string. Zobacz możliwe ustawienia formatowania poniżej.
Poniższych znaków używa się jako tekstu w parametrze formatZawartość parametru formatOpis Przykład zwróconej wartości Dzień --- --- d Dzień miesiąca, 2 cyfry z wiodącymi zerami 01 do 31 D Tekstowy opis angielskiej nazwy dnia, trzy litery Mon kończąc na Sun j Dzień miesiąca bez zer wiodących 1 do 31 l (mała litera 'L') Pełen angielski opis dnia tygodnia Sunday aż do Saturday N Liczbowa forma dnia tygodnia, zgodna z normą ISO-8601 (dodana w PHP 5.1.0) 1 (dla Poniedziałku) aż do 7 (dla Niedzieli) S Angielski przyrostek porządkowy dla dnia miesiąca, 2 litery st, nd, rd lub th. Dobrze wygląda w połączeniu z j w Liczbowa forma dnia tygodnia 0 (dla Niedzieli) aż do 6 (dla Soboty) z Dzień roku (Zaczynając od 0) 0 aż do 365 Week --- --- W Numer tygodnia w roku, zgodny z normą ISO-8601, Tygodnie rozpoczynają Poniedziałki (dostępne od PHP 4.1.0) Przykład: 42 (42. tydzień roku) Month --- --- F Pełen angielski opis, dnia miesiąca, taki jak January czy March January aż do December m Liczbowa forma miesiąca, z zerami wiodącymi 01 aż do 12 M Krótki, angielski opis miesiąca, trzy litery Jan a do Dec n Liczbowa forma miesiąca, bez zer wiodących 1 aż do 12 t Ilość dni w danym miesiącu 28 do 31 Rok --- --- L Informacja o tym, czy rok jest przestępnym 1 jeśli rok jest przestępny, 0 w przeciwnym wypadku. o Numer roku, zgodny z normą ISO-8601. Zwraca to taką samą wartość jak Y, z takim wyjątkiem, że numer tygodnia ISO (W) należy do poprzedniego lub następnego roku, niż rok użyty w tym miejscu. (dodane w PHP 5.1.0) Przykłady: 1999 lub 2003 Y Pełna liczbowa forma roku, 4 cyfry Przykłady: 1999 lub 2003 y Dwie cyfry reprezentujące rok Przykłady: 99 or 03 Czas --- --- a Pora dnia - dwie małe litery (przed/po południu) (ang. Ante/Post meridiem) am lub pm A Pora dnia - dwie duże litery (przed/po południu) (ang. Ante/Post meridiem) AM lub PM B Swatch Internet Time 000 aż do 999 g Godzina, w formacie 12-godzinnym, bez zer wiodących 1 aż do 12 G Godzina, w formacie 24-godzinnym, bez zer wiodących 0 aż do 23 h Godzina, w formacie 12-godzinnym, z zerami wiodącymi 01 aż do 12 H Godzina, w formacie 24-godzinnym, z zerami wiodącymi 00 through 23 i Minuty z zerami wiodącymi 00 do 59 s Sekundy, z zerami wiodącymi 00 aż do 59 u Mikrosekundy (dodano w PHP 5.2.2) Przykład: 54321 Strefa czasowa --- --- e Identyfikator strefy czasowej (dodano w PHP 5.1.0) Przykłady: UTC, GMT, Europe/Zagreb I (duże i) Informacja o tym, czy czas jest letni 1 jeśli czas jest letni, 0 w przeciwnym razie. O Różnica z czasem Greenwich (GMT) w godzinach Przykład: +0200 P Różnica z czasem Greenwich (GMT) z dwukropkiem pomiędzy godzinami i minutami (dodano w PHP 5.1.3) Przykład: +02:00 T Skrót dla strefy czasowej Przykłady: EST, MDT ... Z Różnica dla strefy czasowej w sekundach. Wyrównanie to jest zawsze ujemne dla stref położonych na zachód od południka 0, oraz dodatnie dla tych leżących na wschódod niego. -43200 aż do 50400 Pełna Data/Czas --- --- c Data w standardzie ISO 8601 (dodana w PHP 5) 2004-02-12T15:19:21+00:00 r Data sformatowana zgodnie z » RFC 2822 Przykład: Thu, 21 Dec 2000 16:01:07 +0200 U Sekundy liczone od ery UNIX-a (1 stycznia 1970 00:00:00 czasu Greenwich - GMT) Zobacz także time() Inne znaki umieszczone w łańcuchu formatującym zostaną przez parser przepisane. Z zwróci zawsze 0 podczas używania gmdate().
Informacja:
Odkąd ta funkcja przyjmuje jako znacznik czasu jedynie typ integer znak formatujący u przydaje się jedynie, gdy używamy funkcji date_format() z samodzielnie zdefiniowanymi znacznikami czasu stworzonymi za pomocą funkcji date_create().
-
timestamp -
Opcjonalny parametr uniksowy znacznik czasu
timestampjest typu integer i domyślnie jest ustawiony na bieżący czas lokalny jeślitimestampnie został podany. Innymi słowy, domyślnie to wartość funkcji time().
Zwracane wartości
Zwraca sformatowaną datę jako łańcuch. Jeśli użyto wartości parametru
znacznik_czasu innej niż liczbowa, cała funkcja zwróci FALSE oraz pojawi się
ostrzeżenie klasy E_WARNING.
Błędy/Wyjątki
Każde wywołanie do funkcji date/time spowoduje wygenerowanie E_NOTICE
jeśli strefa czasowa jest nieprawidłowa, lub/i wiadomość E_STRICT
jeśli użyto ustawień systemu lub zmiennej środowiskowej TZ.
Patrz także date_default_timezone_set()
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.1.0 | Poprawny zakres znacznika czasu to zwykle od piątku, 13 grudnia 1901 20:45:54 GMT (czasu Greenwich) do wtorku, 19 stycznia 2038 03:14:07 GMT. (Wartości te odpowiadają minimalnej i maksymalnej wartości 32-bitowej liczbie całkowitej ze znakiem). Jednakże przed PHP 5.1.0, w niektórych systemach (np. Windows) ten przedział był bardziej ograniczony i zawiera się w przedziale 01-01-1970 do 19-01-2038. |
| 5.1.0 |
Teraz generuje błędy strefy czasowej o poziomie |
| 5.1.1 |
Istnieją użyteczne stałe
standaryzujące formaty daty/czasu mogące być użyte w celu określenia
parametru format.
|
Przykłady
Przykład #1 Przykłady użycia funkcji date()
<?php
// ustawia domyślnie używaną strefę czasową. Dostępne od PHP 5.1
date_default_timezone_set('UTC');
// wypisuje np.: Monday
echo date("l");
// wypisuje coś jak: Monday 8th August 2005 03:12:46 PM
echo date('l jS F Y h:i:s A');
// wypisuje: 1 lipca, 2000 wypada w Saturday
echo "1 lipca, 2000 wypada w " . date("l", mktime(0, 0, 0, 7, 1, 2000));
/* użycie stałych jako parametru format */
// wypisuje coś jak: Mon, 15 Aug 2005 15:12:46 UTC
echo date(DATE_RFC822);
// wypisuje coś jak: 2000-07-01T00:00:00+00:00
echo date(DATE_ATOM, mktime(0, 0, 0, 7, 1, 2000));
?>
Możesz ochronić rozpoznawalne znaki w łańcuchu formatującym przed zinterpretowaniem przez poprzedzenie ich znakiem ucieczki - backslashem. Jeśli znak razem z backslashem jest specjalną sekwencją, możliwe, iż będzie trzeba poprzedzić kolejnym znakiem ucieczki całą sekwencję.
Przykład #2 Znaki ucieczki w funkcji date()
<?php
// wypisuje coś jak: jest Wednesday, 15th
echo date("\j\e\s\\t l, jS");
?>
Możliwe jest użycie funkcji date() razem z funkcją mktime() w celu znalezienia dat z przeszłości lub przyszłości.
Przykład #3 Przykład użycia date() i mktime()
<?php
$jutro = mktime(0, 0, 0, date("m") , date("d")+1, date("Y"));
$ostatni_miesiac = mktime(0, 0, 0, date("m")-1, date("d"), date("Y"));
$nastepny_rok = mktime(0, 0, 0, date("m"), date("d"), date("Y")+1);
?>
Informacja:
Rozwiązanie to jest rozsądniejsze, od prostego dodawania lub odejmowania określonej liczby sekund w dniu lub miesiącu, chociażby z powodu zmian czasu.
Poniżej znajduje się kilka przykładów zastosowania date(). Proszę zwrócić uwagę, że powinno się cytować wszystkie znaki aby uniknąć nieoczekiwanych rezultatów, a poza tym, nawet te znaki, które obecnie nie mają specjalnych znaczeń, mogą mieć przypisane jakieś znaczenie w przyszłych wersjach PHP. O ile to możliwe, należy używać cudzysłowów pojedynczych, żeby uniknąć np. zamiany \n na znak nowej linii.
Przykład #4 zastosowania date()
<?php
// Przypuśćmy, że dziś jest 10 marca, 2001, 5:16:18 pm, oraz, że jesteśmy w
// strefie czasowej MST (Mountain Standard Time)
$dzisiaj = date("F j, Y, g:i a"); // March 10, 2001, 5:16 pm
$dzisiaj = date("m.d.y"); // 03.10.01
$dzisiaj = date("j, n, Y"); // 10, 3, 2001
$dzisiaj = date("Ymd"); // 20010310
$dzisiaj = date('h-i-s, j-m-y, it is w Day z '); // 05-16-18, 10-03-01, 1631 1618 6 Satpm01
$dzisiaj = date('\t\o jS \d\z\i\e\ń'); // to 10. dzień
$dzisiaj = date("D M j G:i:s T Y"); // Sat Mar 10 17:16:18 MST 2001
$dzisiaj = date('H:m:s \m \t\o\ \m\i\e\s\i\ą\c'); // 17:03:18 m is month
$dzisiaj = date("H:i:s"); // 17:16:18
?>
Aby sformatować datę w innych językach, należy użyć funkcji setlocale() i strftime() zamiast date().
Notatki
Informacja:
Aby stworzyć znacznik czasu z tekstowego opisu daty, możesz użyć strtotime(). Dodatkowo, niektóre bazy danych mają funkcje konwertujące ich format daty na znacznik czasu (tak jak funkcja » UNIX_TIMESTAMP w MySQL).
Znacznik czasu z chwili wysłania zapytania jest dostępny w $_SERVER['REQUEST_TIME'] od PHP 5.1.
Zobacz też:
- getlastmod() - Gets time of last page modification
- gmdate() - Formatuje datę/czas dla strefy GMT/UTC
- mktime() - Oblicza uniksowy znacznik czasu dla podanej daty
- strftime() - Formatuje lokalną datę/czas zgodnie z lokalizacją
- time() - Zwraca aktualny uniksowy znacznik czasu
getdate
(PHP 4, PHP 5)
getdate — Pobiera informację o dacie/czasie
Opis
$znacznik_czasu = time()
] )
Funkcja zwraca tablicę (array) asocjacyjną zawierającą informacje o dacie podanej
jako znacznik_czasu, lub o aktualnej dacie, jeśli
nie podano parametru znacznik_czasu.
Parametry
Zwracane wartości
Zwraca asocjacyjną tablicę (array) z informacjami zależnymi
od podanego parametru znacznik_czasu. Zwrócona tablica
zawiera następujące elementy:
| Klucz | Opis | Przykłady zwracanych wartości |
|---|---|---|
| "seconds" | Ilość sekund | 0 do 59 |
| "minutes" | Liczba minut | 0 do 59 |
| "hours" | Ilość godzin | 0 do 23 |
| "mday" | Liczba będąca dniem miesiąca | 1 do 31 |
| "wday" | Dzień tygodnia w postacy cyfry | 0 (dla Niedzieli) aż do 6 (dla Soboty) |
| "mon" | Miesiąc w postaci liczby | 1 aż do 12 |
| "year" | Pełen rok w postaci liczby, 4 cyfry | Przykłady: 1999 lub 2003 |
| "yday" | Dzień danego roku, w postaci liczby | 0 aż do 365 |
| "weekday" | Pełna nazwa dnia tygodnia, w języku angielskim | Sunday aż do Saturday |
| "month" | Pełna nazwa miesiąca, w języku angielskim, jak np. January lub March | January aż do December |
| 0 | Sekundy, które upłynęły od Ery Uniksa, podobnie jak wartość zwracana przez time() i użyta przez funkcję date(). | Zależnie od systemu, zazwyczaj -2147483648 aż do 2147483647. |
Przykłady
Przykład #1 Przykład getdate()
<?php
$dzisiaj = getdate();
print_r($dzisiaj);
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[seconds] => 40
[minutes] => 58
[hours] => 21
[mday] => 17
[wday] => 2
[mon] => 6
[year] => 2003
[yday] => 167
[weekday] => Tuesday
[month] => June
[0] => 1055901520
)
Zobacz też:
- date() - Formatuje lokalny czas/datę
- idate() - Format a local time/date as integer
- localtime() - Pobiera czas lokalny
- time() - Zwraca aktualny uniksowy znacznik czasu
- setlocale() - Set locale information
gettimeofday
(PHP 4, PHP 5)
gettimeofday — Pobiera aktualny czas
Opis
Jest to interfejs do gettimeofday(2). Funkcja zwraca tablicę asocjacyjną zawierającą dane odebrane z wywołania systemowego.
- "sec" - sekundy
- "usec" - mikrosekundy
- "minuteswest" - minuty na zachód od Greenwich
- "dsttime" - rodzaj czasu: letni/zimowy
gmdate
(PHP 4, PHP 5)
gmdate — Formatuje datę/czas dla strefy GMT/UTC
Opis
$format
[, int $znacznik_czasu
] )Identyczna do funkcji date(), z wyjątkiem tego, że zawsze podaje czas Greenwich (Greenwich Mean Time - GMT). Na przykład w Polsce (GMT +0100 dla czasu zimowego) pierwsza linia zwraca "Jan 01 1998 00:00:00", podczas gdy druga "Dec 31 1997 23:00:00".
Przykład #1 przykład gmdate()
<?php
echo date ("M d Y H:i:s", mktime (0,0,0,1,1,1998));
echo gmdate ("M d Y H:i:s", mktime (0,0,0,1,1,1998));
?>
Informacja:
Przed PHP 5.1.0, ujemne znaczniki czasu (daty z przed 1970) nie działały na niektórych systemach (np. Windows).
Patrz także date(), mktime(), gmmktime() i strftime().
gmmktime
(PHP 4, PHP 5)
gmmktime — Ustala uniksowy znacznik czasu dla daty ze strefy GMT
Opis
$godzina
, int $minuta
, int $sekunda
, int $miesiąc
, int $dzień
, int $rok
[, int $letni/zimowy
] )Identyczna do mktime() z jednym wyjątkiem, że przekazywane argumenty reprezentują datę w strefie GMT.
gmstrftime
(PHP 4, PHP 5)
gmstrftime — Formatuje czas/datę ze strefy GMT/UTC zgodnie z lokalizacją
Opis
$format
[, int $znacznik_czasu
] )Zachowuje się identycznie jak strftime() z tym wyjątkiem, że zwracany jest czas strefy Greenwich (Greenwich Mean Time - GMT). Na przykład, uruchomiona we Wschodnim Czasie Standardowym (GMT -0500) pierwsza linia poniżej wyświetla "Dec 31 1998 20:00:00", podczas gdy druga "Jan 01 1999 01:00:00".
Przykłady
Przykład #1 przykład gmstrftime()
<?php
setlocale(LC_TIME, 'en_US');
echo strftime("%b %d %Y %H:%M:%S", mktime(20, 0, 0, 12, 31, 98)) . "\n";
echo gmstrftime("%b %d %Y %H:%M:%S", mktime(20, 0, 0, 12, 31, 98)) . "\n";
?>
idate
(PHP 5)
idate — Format a local time/date as integer
Opis
$format
[, int $timestamp = time()
] )
Returns a number formatted according to the given format string using the
given integer timestamp or the current local time
if no timestamp is given. In other words, timestamp
is optional and defaults to the value of time().
Unlike the function date(), idate()
accepts just one char in the format parameter.
Parametry
-
format -
The following characters are recognized in the formatparameter stringformatcharacterDescription B Swatch Beat/Internet Time d Day of the month h Hour (12 hour format) H Hour (24 hour format) i Minutes I (uppercase i) returns 1 if DST is activated, 0 otherwise L (uppercase l) returns 1 for leap year, 0 otherwise m Month number s Seconds t Days in current month U Seconds since the Unix Epoch - January 1 1970 00:00:00 UTC - this is the same as time() w Day of the week (0 on Sunday) W ISO-8601 week number of year, weeks starting on Monday y Year (1 or 2 digits - check note below) Y Year (4 digits) z Day of the year Z Timezone offset in seconds -
timestamp -
Opcjonalny parametr uniksowy znacznik czasu
timestampjest typu integer i domyślnie jest ustawiony na bieżący czas lokalny jeślitimestampnie został podany. Innymi słowy, domyślnie to wartość funkcji time().
Zwracane wartości
Returns an integer.
As idate() always returns an integer and as they can't start with a "0", idate() may return fewer digits than you would expect. See the example below.
Błędy/Wyjątki
Każde wywołanie do funkcji date/time spowoduje wygenerowanie E_NOTICE
jeśli strefa czasowa jest nieprawidłowa, lub/i wiadomość E_STRICT
jeśli użyto ustawień systemu lub zmiennej środowiskowej TZ.
Patrz także date_default_timezone_set()
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.1.0 |
Teraz generuje błędy strefy czasowej o poziomie |
Przykłady
Przykład #1 idate() example
<?php
$timestamp = strtotime('1st January 2004'); //1072915200
// this prints the year in a two digit format
// however, as this would start with a "0", it
// only prints "4"
echo idate('y', $timestamp);
?>
localtime
(PHP 4, PHP 5)
localtime — Pobiera czas lokalny
Opis
$znacznik_czasu
[, bool $asocjacyjna
]] )
Funkcja localtime() zwraca tablicę identyczną do tej
ze struktury zwracanej przez wywołanie identycznej funkcji w C. Pierwszym
argumentem funkcji jest znacznik czasu. Jeśli żaden znacznik czasu nie
zostanie podany, funkcja wykorzystuje aktualny czas, taki jak zwrócony przez
time().
Drugi argument, asocjacyjna, jeśli jest ustawiony na FALSE, lub nie
jest podany, powoduje zwrócenie zwykłej, indeksowanej liczbowo tablicy.
Jeśli zaś jest ustawiony na TRUE, to funkcja zwróci tablicę asocjacyjną
zawierającą wszystkie rozmaite elementy struktury zwracanej przez wywołanie
funkcji w C. Nazwy kluczy tablicy są następujące:
- "tm_sec" - sekundy
- "tm_min" - minuty
- "tm_hour" - godziny
- "tm_mday" - dzień miesiąca
- "tm_mon" - miesiąc roku, 0 to styczeń
- "tm_year" - ilość lat od 1900
- "tm_wday" - dzień tygodnia
- "tm_yday" - dzień roku
- "tm_isdst" - czy aktualnie jest czas zimowy
Informacja: Miesiące rozpoczynają się od 0 (Sty) do 11 (Gru) i dni tygodnia rozpoczynają się od 0 (Nie) do 6 (Sob).
Przykład #1 time() przykład
<?php
$localtime = localtime();
$localtime_assoc = localtime(time(), true);
print_r($localtime);
print_r($localtime_assoc);
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[0] => 24
[1] => 3
[2] => 19
[3] => 3
[4] => 3
[5] => 105
[6] => 0
[7] => 92
[8] => 1
)
Array
(
[tm_sec] => 24
[tm_min] => 3
[tm_hour] => 19
[tm_mday] => 3
[tm_mon] => 3
[tm_year] => 105
[tm_wday] => 0
[tm_yday] => 92
[tm_isdst] => 1
)
microtime
(PHP 4, PHP 5)
microtime — Zwraca aktualny uniksowy znacznik czasu z mikrosekundami
Opis
Zwraca łańcuch znaków "msec sec", gdzie sec jest aktualnym czasem, mierzonym jako liczba sekund od uniksowej Epoki (1 stycznia 1970, 0:00:00 GMT), natomiast msec jest aktualną liczbą mikrosekund. Funkcja ta dostępna jest wyłącznie na systemach operacyjnych, które obsługują wywołanie systemowe gettimeofday().
Obydwie części łańcucha znaków są podawane w sekundach.
Przykład #1 przykład microtime()
<?php
function getmicrotime(){
list($usec, $sec) = explode(" ",microtime());
return ((float)$usec + (float)$sec);
}
$time_start = getmicrotime();
for ($i=0; $i < 1000; $i++){
//nie rób nic przez 1000 iteracji
}
$time_end = getmicrotime();
$time = $time_end - $time_start;
echo "Nie robił nic przez $time sekund";
?>
Patrz także time().
mktime
(PHP 4, PHP 5)
mktime — Oblicza uniksowy znacznik czasu dla podanej daty
Opis
$godzina
, int $minuta
, int $sekunda
, int $miesiąc
, int $dzień
, int $rok
[, int $letni/zimowy
] )Uwaga: Proszę zwrócić uwagę na dziwną kolejność argumentów, zupełnie odmienną od spotykanej w standardowym wywołaniu uniksowym mktime(); która w dodatku nie jest praktyczna przy opuszczaniu argumentów od prawej do lewej (patrz niżej). Częstym błędem w skryptach są pomyłki w kolejności tych argumentów.
Funkcja zwraca uniksowy znacznik czasu odpowiadający podanym argumentom. Znacznik czasu jest liczbą całkowitą długą (long integer) zawierającą liczbę sekund dzielącą uniksową Epokę (1 stycznia 1970) od podanego w argumentach czasu.
Argumenty mogą być opuszczane w kolejności od prawej do lewej. Za każdy pominięty argument będzie wówczas wstawiona aktualna wartość, zgodnie z lokalnym czasem/datą.
Argument letni/zimowy może być ustawiony na 1, jeśli
to czas zimowy, lub 0 jeśli letni, lub -1 (domyślnie) jeśli niewiadomo,
czy letni czy zimowy. Jeśli niewiadomo, PHP spróbuje ustalić to
samodzielnie. Może to powodować nieoczekiwane (ale na pewno poprawne)
wyniki.
Informacja:
Argument
letni/zimowydodano w PHP 3.0.10.
Funkcja mktime() przydaje się przy wykonywaniu arytmetyki dat i walidacji, gdyż automatycznie policzy właściwą wartość dla danych spoza przedziałów. Na przykład, każda poniższa linia wyświetli "Jan-01-1998".
Przykład #1 przykład mktime()
<?php
echo date ("M-d-Y", mktime (0,0,0,12,32,1997));
echo date ("M-d-Y", mktime (0,0,0,13,1,1997));
echo date ("M-d-Y", mktime (0,0,0,1,1,1998));
echo date ("M-d-Y", mktime (0,0,0,1,1,98));
?>
rok może być liczbą dwu lub czterocyfrową, przy
czym wartości dwucyfrowe z przedziału 0-69 będą mapowane do 2000-2069,
a z przedziału 70-99 do 1970-1999 (w systemach, w których time_t jest
32-bitową liczbą całkowitą ze znakiem, co jest obecnie najpopularniejszym
rozwiązaniem, poprawny zakres argumentu rok
zawiera się pomiędzy 1902 a 2037).
Informacja: Windows
Żadna znana wersja systemu Windows nie obsługuje ujemnych znaczników czasu. Z tego powodu zakres poprawnych dat zawiera się pomiędzy rokiem 1970 a 2038.
Ostatni dzień dowolnego miesiąca może być wyrażony jako zerowy dzień następnego miesiąca, ale nie jako -1 dzień. Obydwa poniższe przykłady wyświetlą "Ostatni dzień lutego 2000 to: 29".
Przykład #2 Ostatni dzień miesiąca
<?php
$ostatni = mktime (0,0,0,3,0,2000);
echo strftime ("Ostatni dzień lutego 2000 to: %d", $ostatni);
$ostatni = mktime (0,0,0,4,-31,2000);
echo strftime ("Ostatni dzień lutego 2000 to: %d", $ostatni);
?>
Data z rokiem, miesiącem i dniem równym zero jest niepoprawna (w przeciwnym razie oznaczałoby to 30.11.1999, co mogłoby powodować dziwne rezultaty).
strftime
(PHP 4, PHP 5)
strftime — Formatuje lokalną datę/czas zgodnie z lokalizacją
Opis
$format
[, int $znacznik_czasu
] )Zwraca łańcuch znaków sformatowany zgodnie z podanym szablonem formatującym, przy użyciu podanego znacznika czasu lub aktualnego czasu, jeśli znacznik nie jest podany. Nazwy miesięcy, dni tygodnia, itp. respektują ustawienia lokalizacji przy użyciu funkcji setlocale().
Poniższe symbole są rozpoznawane w szablonie formatującym:
- %a - skrótowa nazwa dnia tygodnia zgodnie z lokalizacją
- %A - pełna nazwa dnia tygodnia zgodnie z lokalizacją
- %b - skrótowa nazwa miesiąca zgodnie z lokalizacją
- %B - pełna nazwa miesiąca zgodnie z lokalizacją
- %c - preferowana reprezentacja daty i czasu zgodnie z lokalizacją
- %C - numer wieku (rok podzielony przez 100 i skrócony do liczby całkowitej, przedział od 00 do 99)
- %d - dzień miesiąca jako liczba dziesiętna (przedział od 01 do 31)
- %D - to samo co %m/%d/%y
- %e - dzień miesiąca jako liczba dziesiętna, przy czym pojedyncza cyfra poprzedzona jest spacją (przedział od " 1" do "31")
- %g - tak jak %G, ale bez uwzględnienia wieku
- %G - rok w zapisie czterocyfrowym, powiązany z numerem tygodnia wg ISO. Symbol ten ma ten sam format i wartość jak %Y, z tym wyjątkiem, że jeśli numer tygodnia wg ISO należy do poprzedniego lub następnego roku, to poprzedni lub następny rok jest zwracany przez ten symbol.
- %h - tak jak %b
- %H - godzina jako liczba dziesiętna w systemie 24-godzinnym (przedział od 00 do 23)
- %I - godzina jako liczba dziesiętna w systemie 12-godzinnym (przedział od 01 do 12)
- %j - dzień roku jako liczba dziesiętna (przedział od 001 do 366)
- %m - miesiąc jako liczba dziesiętna (przedział od 01 do 12)
- %M - minuty jako liczba dziesiętna
- %n - znak nowej linii
- %p - albo "am" lub "pm" zgodnie z podanym czasem, albo łańcuchy znaków odpowiadające lokalizacji
- %r - czas w notacji a.m. lub p.m.
- %R - czas w notacji 24-godzinnej
- %S - sekundy jako liczba dziesiętna
- %t - znak tabulacji
- %T - aktualny czas, odpowiednik %H:%M:%S
-
%u - numer dnia tygodnia jako liczba dziesiętna [1,7], gdzie 1 oznacza
poniedziałek
Ostrzeżenie
Sun Solaris podaje niedzielę jako 1, pomimo że ISO 9889:1999 (aktualny standard języka C) jasno określa, że powinien to być poniedziałek.
- %U - numer tygodnia aktualnego roku jako liczba dziesiętna, począwszy od pierwszej niedzieli jako pierwszego dnia pierwszego tygodnia
- %V - numer tygodnia aktualnego roku wg ISO 8601:1988 jako liczba dziesiętna, przedział od 01 do 53, gdzie tydzień 1 jest pierwszym tygodniem, którym ma co najmniej 4 dni w aktualnym roku, przy czym pierwszym dniem tygodnia jest poniedziałek. (Przy użyciu %G lub %g otrzymuje się rok, który odpowiada numerowi tygodnia dla podanego znacznika czasu).
- %W - numer tygodnia aktualnego roku jako liczba dziesiętna, począwszy od pierwszego poniedziałku, jako pierwszego dnia pierwszego tygodnia
- %w - dzień tygodnia jako liczba dziesiętna, począwszy od niedzieli - numer 0
- %x - preferowana reprezentacja daty, zgodnie z lokalizacją, bez czasu
- %X - preferowana reprezentacja czasu, zgodnie z lokalizacją, bez daty
- %y - rok jako liczba dziesiętna, bez uwzględnienia wieku (przedział od 00 do 99)
- %Y - rok jako liczba dziesiętna, z wiekiem włącznie
- %Z - strefa czasowa, nazwa lub skrót
- %% - znak "%"
Informacja:
Nie wszystkie symbole konwersji mogą być obsługiwane przez twoją bibliotekę C, co oznacza, że nie będą obsługiwane przez PHP-owską funkcję strftime(). Oznacza to, że np. %e, %T i %D (oraz być może inne) nie będą funkcjonować w Windows.
Przykład #1 przykład strftime()
setlocale (LC_TIME, "C");
print (strftime ("%A, to w fińskim "));
setlocale (LC_TIME, "fi_FI");
print (strftime ("%A, we francuskim "));
setlocale (LC_TIME, "fr_FR");
print (strftime ("%A, a w niemieckim "));
setlocale (LC_TIME, "de_DE");
print (strftime ("%A.\n"));
Patrz także setlocale() i mktime() oraz » Otwarta Specyfikacja Grupowa strftime().
Opis
$date
, string $format
)
strptime() returns an array with the
date parsed, or FALSE on error.
Month and weekday names and other language dependent strings respect the
current locale set with setlocale() (LC_TIME).
Parametry
-
date(string) -
The string to parse (e.g. returned from strftime()).
-
format(string) -
The format used in
date(e.g. the same as used in strftime()). Note that some of the format options available to strftime() may not have any effect within strptime(); the exact subset that are supported will vary based on the operating system and C library in use.For more information about the format options, read the strftime() page.
Zwracane wartości
Returns an array lub FALSE w przypadku niepowodzenia.
| parameters | Description |
|---|---|
| "tm_sec" | Seconds after the minute (0-61) |
| "tm_min" | Minutes after the hour (0-59) |
| "tm_hour" | Hour since midnight (0-23) |
| "tm_mday" | Day of the month (1-31) |
| "tm_mon" | Months since January (0-11) |
| "tm_year" | Years since 1900 |
| "tm_wday" | Days since Sunday (0-6) |
| "tm_yday" | Days since January 1 (0-365) |
| "unparsed" | the date part which was not
recognized using the specified format |
Przykłady
Przykład #1 strptime() example
<?php
$format = '%d/%m/%Y %H:%M:%S';
$strf = strftime($format);
echo "$strf\n";
print_r(strptime($strf, $format));
?>
Powyższy przykład wyświetli coś podobnego do:
03/10/2004 15:54:19
Array
(
[tm_sec] => 19
[tm_min] => 54
[tm_hour] => 15
[tm_mday] => 3
[tm_mon] => 9
[tm_year] => 104
[tm_wday] => 0
[tm_yday] => 276
[unparsed] =>
)
Notatki
Informacja: Ta funkcja nie jest dostępna na platformie Windows.
Informacja:
Internally, this function calls the strptime() function provided by the system's C library. This function can exhibit noticeably different behaviour across different operating systems. The use of date_parse_from_format(), which does not suffer from these issues, is recommended on PHP 5.3.0 and later.
Informacja:
"tm_sec" includes any leap seconds (currently upto 2 a year). For more information on leap seconds, see the » Wikipedia article on leap seconds.
Informacja:
Prior to PHP 5.2.0, this function could return undefined behaviour. Notably, the "tm_sec", "tm_min" and "tm_hour" entries would return undefined values.
Zobacz też:
- checkdate() - Waliduje datę gregoriańską
- strftime() - Formatuje lokalną datę/czas zgodnie z lokalizacją
- date_parse_from_format() - Get info about given date formatted according to the specified format
- DateTime::createFromFormat() - Returns new DateTime object formatted according to the specified format
strtotime
(PHP 4, PHP 5)
strtotime — Parsuje większość angielskich tekstowych opisów daty i czasu do uniksowego znacznika czasu
Opis
$czas
[, int $teraz
] )
Funkcja przyjmuje tekst zawierający datę w formacie angielskim i stara
się przeliczyć ją na uniksowy znacznik czasu, relatywnie do znacznika
czasu podanego w teraz, lub aktualnego czasu,
jeśli znacznik nie zostanie podany. W przypadku fiaska, zwracane jest
-1.
Ponieważ strtotime() zachowuje się zgodnie ze składnią
daty wg GNU, warto zajrzeć do rozdziału podręcznika GNU zatytułowanego
» Formaty Wprowadzania Daty - Date
Input Formats. Opisana tam jest poprawna składnia argumentu
czas.
Przykład #1 przykłady strtotime()
<?php
echo strtotime ("now"), "\n";
echo strtotime ("10 September 2000"), "\n";
echo strtotime ("+1 day"), "\n";
echo strtotime ("+1 week"), "\n";
echo strtotime ("+1 week 2 days 4 hours 2 seconds"), "\n";
echo strtotime ("next Thursday"), "\n";
echo strtotime ("last Monday"), "\n";
?>
Przykład #2 Checking for failure
<?php
$str = 'Not Good';
if (($timestamp = strtotime($str)) === -1) {
echo "Tekst daty ($str) jest niepoprawny";
} else {
echo "$str == ". date('l dS of F Y h:i:s A',$timestamp);
}
?>
Informacja:
Poprawny zakres znacznika czasu to zwykle od piątku, 13 grudnia 1901 20:45:54 GMT (czasu Greenwich) do wtorku, 19 stycznia 2038 03:14:07 GMT. (Wartości te odpowiadają minimalnej i maksymalnej wartości 32-bitowej liczbie całkowitej ze znakiem).
time
(PHP 4, PHP 5)
time — Zwraca aktualny uniksowy znacznik czasu
Opis
Zwraca aktualny czas, podawany jako liczba sekund, które upłynęły od uniksowej Epoki (1 stycznia 1970 00:00:00 GMT).
Przykłady
Przykład #1 time() przykład
<?php
$nextWeek = time() + (7 * 24 * 60 * 60);
// 7 dni; 24 godziny; 60 minut; 60 sekund
echo 'Teraz: '. date('Y-m-d') ."\n";
echo 'Za tydzień: '. date('Y-m-d', $nextWeek) ."\n";
// lub używając strtotime():
echo 'Za tydzień: '. date('Y-m-d', strtotime('+1 week')) ."\n";
?>
Powyższy przykład wyświetli coś podobnego do:
Teraz: 2005-03-30 Za tydzień: 2005-04-06 Za tydzień: 2005-04-06
Notatki
Znacznik czasu rozpoczęcia żądania jest dostępny w $_SERVER['REQUEST_TIME'] od PHP 5.1.
Zobacz też:
- date() - Formatuje lokalny czas/datę
- microtime() - Zwraca aktualny uniksowy znacznik czasu z mikrosekundami
timezone_abbreviations_list
(PHP 5 >= 5.2.0)
timezone_abbreviations_list — Alias dla DateTimeZone::listAbbreviations()
Opis
Ta funkcja jest aliasem dla: DateTimeZone::listAbbreviations()
timezone_identifiers_list
(PHP 5 >= 5.2.0)
timezone_identifiers_list — Alias dla DateTimeZone::listIdentifiers()
Opis
Ta funkcja jest aliasem dla: DateTimeZone::listIdentifiers()
Opis
Ta funkcja jest aliasem dla: DateTimeZone::getLocation()
timezone_name_from_abbr
(PHP 5 >= 5.1.3)
timezone_name_from_abbr — Returns the timezone name from abbreviation
Opis
$abbr
[, int $gmtOffset = -1
[, int $isdst = -1
]] )Parametry
-
abbr -
Time zone abbreviation.
-
gmtOffset -
Offset from GMT in seconds. Defaults to -1 which means that first found time zone corresponding to
abbris returned. Otherwise exact offset is searched and only if not found then the first time zone with any offset is returned. -
isdst -
Daylight saving time indicator. Defaults to -1, which means that whether the time zone has daylight saving or not is not taken into consideration when searching. If this is set to 1, then the
gmtOffsetis assumed to be an offset with daylight saving in effect; if 0, thengmtOffsetis assumed to be an offset without daylight saving in effect. Ifabbrdoesn't exist then the time zone is searched solely by thegmtOffsetandisdst.
Zwracane wartości
Returns time zone name on success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 A timezone_name_from_abbr() example
<?php
echo timezone_name_from_abbr("CET") . "\n";
echo timezone_name_from_abbr("", 3600, 0) . "\n";
?>
Powyższy przykład wyświetli coś podobnego do:
Europe/Berlin Europe/Paris
Opis
Ta funkcja jest aliasem dla: DateTimeZone::getName()
Opis
Ta funkcja jest aliasem dla: DateTimeZone::getOffset()
Opis
Ta funkcja jest aliasem dla: DateTimeZone::__construct()
timezone_transitions_get
(PHP 5 >= 5.2.0)
timezone_transitions_get — Alias dla DateTimeZone::getTransitions()
Opis
Ta funkcja jest aliasem dla: DateTimeZone::getTransitions()
timezone_version_get
(PHP 5 >= 5.3.0)
timezone_version_get — Gets the version of the timezonedb
Opis
Returns the current version of the timezonedb.
Zwracane wartości
Returns a string.
Przykłady
Przykład #1 Getting the timezonedb version
<?php
echo timezone_version_get();
?>
Powyższy przykład wyświetli coś podobnego do:
2009.7
Spis treści
- checkdate — Waliduje datę gregoriańską
- date_add — Alias dla DateTime::add
- date_create_from_format — Alias dla DateTime::createFromFormat
- date_create — Alias dla DateTime::__construct
- date_date_set — Alias dla DateTime::setDate
- date_default_timezone_get — Gets the default timezone used by all date/time functions in a script
- date_default_timezone_set — Sets the default timezone used by all date/time functions in a script
- date_diff — Alias dla DateTime::diff
- date_format — Alias dla DateTime::format
- date_get_last_errors — Alias dla DateTime::getLastErrors
- date_interval_create_from_date_string — Alias dla DateInterval::createFromDateString
- date_interval_format — Alias dla DateInterval::format
- date_isodate_set — Alias dla DateTime::setISODate
- date_modify — Alias dla DateTime::modify
- date_offset_get — Alias dla DateTime::getOffset
- date_parse_from_format — Get info about given date formatted according to the specified format
- date_parse — Returns associative array with detailed info about given date
- date_sub — Alias dla DateTime::sub
- date_sun_info — Returns an array with information about sunset/sunrise and twilight begin/end
- date_sunrise — Returns time of sunrise for a given day and location
- date_sunset — Returns time of sunset for a given day and location
- date_time_set — Alias dla DateTime::setTime
- date_timestamp_get — Alias dla DateTime::getTimestamp
- date_timestamp_set — Alias dla DateTime::setTimestamp
- date_timezone_get — Alias dla DateTime::getTimezone
- date_timezone_set — Alias dla DateTime::setTimezone
- date — Formatuje lokalny czas/datę
- getdate — Pobiera informację o dacie/czasie
- gettimeofday — Pobiera aktualny czas
- gmdate — Formatuje datę/czas dla strefy GMT/UTC
- gmmktime — Ustala uniksowy znacznik czasu dla daty ze strefy GMT
- gmstrftime — Formatuje czas/datę ze strefy GMT/UTC zgodnie z lokalizacją
- idate — Format a local time/date as integer
- localtime — Pobiera czas lokalny
- microtime — Zwraca aktualny uniksowy znacznik czasu z mikrosekundami
- mktime — Oblicza uniksowy znacznik czasu dla podanej daty
- strftime — Formatuje lokalną datę/czas zgodnie z lokalizacją
- strptime — Parse a time/date generated with strftime
- strtotime — Parsuje większość angielskich tekstowych opisów daty i czasu do uniksowego znacznika czasu
- time — Zwraca aktualny uniksowy znacznik czasu
- timezone_abbreviations_list — Alias dla DateTimeZone::listAbbreviations
- timezone_identifiers_list — Alias dla DateTimeZone::listIdentifiers
- timezone_location_get — Alias dla DateTimeZone::getLocation
- timezone_name_from_abbr — Returns the timezone name from abbreviation
- timezone_name_get — Alias dla DateTimeZone::getName
- timezone_offset_get — Alias dla DateTimeZone::getOffset
- timezone_open — Alias dla DateTimeZone::__construct
- timezone_transitions_get — Alias dla DateTimeZone::getTransitions
- timezone_version_get — Gets the version of the timezonedb
Supported Date and Time Formats
Spis treści
This section describes all the different formats that the strtotime(), DateTime and date_create() parser understands. The formats are grouped by section. In most cases formats from different sections can be used in the same date/time string. For each of the supported formats, one or more examples are given, as well as a description for the format. Characters in single quotes in the formats are case-insensitive ('t' could be t or T), characters in double quotes are case-sensitive ("T" is only T).
Time Formats
| Description | Formats | Examples |
|---|---|---|
| frac | . [0-9]+ | ".21342", ".85" |
| hh | "0"?[1-9] | "1"[0-2] | "04", "7", "12" |
| HH | [01][0-9] | "2"[0-4] | "04", "7", "19" |
| meridian | [AaPp] .? [Mm] .? [\0\t ] | "A.m.", "pM", "am." |
| MM | [0-5][0-9] | "00", "12", "59" |
| II | [0-5][0-9] | "00", "12", "59" |
| space | [ \t] | |
| tz | "("? [A-Za-z]{1,6} ")"? | [A-Z][a-z]+([_/][A-Z][a-z]+)+ | "CEST", "Europe/Amsterdam", "America/Indiana/Knox" |
| tzcorrection | "GMT"? [+-] hh ":"? MM? | "+0400", "GMT-07:00", "-07:00" |
| Description | Format | Examples |
|---|---|---|
| Hour only, with meridian | hh space? meridian | "4 am", "5PM" |
| Hour and minutes, with meridian | hh [.:] MM space? meridian | "4:08 am", "7:19P.M." |
| Hour, minutes and seconds, with meridian | hh [.:] MM [.:] II space? meridian | "4:08:37 am", "7:19:19P.M." |
| MS SQL (Hour, minutes, seconds and fraction with meridian), PHP 5.3 and later only | hh ":" MM ":" II [.:] [0-9]+ meridian | "4:08:39:12313am" |
| Description | Format | Examples |
|---|---|---|
| Hour and minutes | 't'? HH [.:] MM | "04:08", "19.19", "T23:43" |
| Hour and minutes, no colon | 't'? HH MM | "0408", "t1919", "T2343" |
| Hour, minutes and seconds | 't'? HH [.:] MM [.:] II | "04.08.37", "t19:19:19" |
| Hour, minutes and seconds, no colon | 't'? HH MM II | "040837", "T191919" |
| Hour, minutes, seconds and timezone | 't'? HH [.:] MM [.:] II space? ( tzcorrection | tz ) | "040837CEST", "T191919-0700" |
| Hour, minutes, seconds and fraction | 't'? HH [.:] MM [.:] II frac | "04.08.37.81412", "19:19:19.532453" |
| Time zone information | tz | tzcorrection | "CEST", "Europe/Amsterdam", "+0430", "GMT-06:00" |
Date Formats
| Description | Format | Examples |
|---|---|---|
| daysuf | "st" | "nd" | "rd" | "th" | |
| dd | ([0-2]?[0-9] | "3"[01]) daysuf? | "7th", "22nd", "31" |
| DD | "0" [0-9] | [1-2][0-9] | "3" [01] | "07", "31" |
| m | 'january' | 'february' | 'march' | 'april' | 'may' | 'june' | 'july' | 'august' | 'september' | 'october' | 'november' | 'december' | 'jan' | 'feb' | 'mar' | 'apr' | 'may' | 'jun' | 'jul' | 'aug' | 'sep' | 'sept' | 'oct' | 'nov' | 'dec' | "I" | "II" | "III" | "IV" | "V" | "VI" | "VII" | "VIII" | "IX" | "X" | "XI" | "XII" | |
| M | 'jan' | 'feb' | 'mar' | 'apr' | 'may' | 'jun' | 'jul' | 'aug' | 'sep' | 'sept' | 'oct' | 'nov' | 'dec' | |
| mm | "0"? [0-9] | "1"[0-2] | "0", "04", "7", "12" |
| MM | "0" [0-9] | "1"[0-2] | "00", "04", "07", "12" |
| y | [0-9]{1,4} | "00", "78", "08", "8", "2008" |
| yy | [0-9]{2} | "00", "08", "78" |
| YY | [0-9]{4} | "2000", "2008", "1978" |
| Description | Format | Examples |
|---|---|---|
| American month and day | mm "/" dd | "5/12", "10/27" |
| American month, day and year | mm "/" dd "/" y | "12/22/78", "1/17/2006", "1/17/6" |
| Four digit year, month and day with slashes | YY "/" mm "/" dd | "2008/6/30", "1978/12/22" |
| Four digit year and month (GNU) | YY "-" mm | "2008-6", "2008-06", "1978-12" |
| Year, month and day with dashes | y "-" mm "-" dd | "2008-6-30", "78-12-22", "8-6-21" |
| Day, month and four digit year, with dots, tabs or dashes | dd [.\t-] mm [.-] YY | "30-6-2008", "22.12\t1978" |
| Day, month and two digit year, with dots or tabs | dd [.\t] mm "." yy | "30.6.08", "22\t12\t78" |
| Day, textual month and year | dd ([ \t.-])* m ([ \t.-])* y | "30-June 2008", "22DEC78", "14 III 1879" |
| Textual month and four digit year (Day reset to 1) | m ([ \t.-])* YY | "June 2008", "DEC1978", "March 1879" |
| Four digit year and textual month (Day reset to 1) | YY ([ \t.-])* m | "2008 June", "1978-XII", "1879.MArCH" |
| Textual month, day and year | m ([ .\t-])* dd [,.stndrh\t ]+ y | "July 1st, 2008", "April 17, 1790", "May.9,78" |
| Textual month and day | m ([ .\t-])* dd [,.stndrh\t ]* | "July 1st,", "Apr 17", "May.9" |
| Day and textual month | d ([ .\t-])* m | "1 July", "17 Apr", "9.May" |
| Month abbreviation, day and year | M "-" DD "-" y | "May-09-78", "Apr-17-1790" |
| Year, month abbreviation and day | y "-" M "-" DD | "78-Dec-22", "1814-MAY-17" |
| Year (and just the year) | YY | "1978", "2008" |
| Textual month (and just the month) | m | "March", "jun", "DEC" |
| Description | Format | Examples |
|---|---|---|
| Eight digit year, month and day | YY MM DD | "15810726", "19780417", "18140517" |
| Four digit year, month and day with slashes | YY "/" MM "/" DD | "2008/06/30", "1978/12/22" |
| Two digit year, month and day with dashes | yy "-" MM "-" DD | "08-06-30", "78-12-22" |
| Four digit year with optional sign, month and day | [+-]? YY "-" MM "-" DD | "-0002-07-26", "+1978-04-17", "1814-05-17" |
Informacja:
For the y and yy formats, years below 100 are handled in a special way when the y or yy symbol is used. If the year falls in the range 0 (inclusive) to 69 (inclusive), 2000 is added. If the year falls in the range 70 (inclusive) to 99 (inclusive) then 1900 is added. This means that "00-01-01" is interpreted as "2000-01-01".
Informacja:
The "Day, month and two digit year, with dots or tabs" format (dd [.\t] mm "." yy) only works for the year values 61 (inclusive) to 99 (inclusive) - outside those years the time format "HH [.:] MM [.:] SS" has precedence.
Informacja:
The "Year (and just the year)" format only works if a time string has already been found -- otherwise this format is recognised as HH MM.
Informacja:
It is possible to over- and underflow the dd and DD format. Day 0 means the last day of previous month, whereas overflows count into the next month. This makes "2008-08-00" equivalent to "2008-07-31" and "2008-06-31" equivalent to "2008-07-01" (June only has 30 days).
It is also possible to underflow the mm and MM formats with the value 0. A month value of 0 means December of the previous year. As example "2008-00-22" is equivalent to "2007-12-22".
If you combine the previous two facts and underflow both the day and the month, the following happens: "2008-00-00" first gets converted to "2007-12-00" which then gets converted to "2007-11-30". This also happens with the string "0000-00-00", which gets transformed into "-0001-11-30" (the year -1 in the ISO 8601 calendar, which is 2 BC in the proleptic Gregorian calendar).
Compound Formats
| Description | Formats | Examples |
|---|---|---|
| DD | "0" [0-9] | [1-2][0-9] | "3" [01] | "02", "12", "31" |
| doy | "00"[1-9] | "0"[1-9][0-9] | [1-2][0-9][0-9] | "3"[0-5][0-9] | "36"[0-6] | "36"[0-6] "000", "012", "366" |
| frac | . [0-9]+ | ".21342", ".85" |
| hh | "0"?[1-9] | "1"[0-2] | "04", "7", "12" |
| HH | [01][0-9] | "2"[0-4] | "04", "7", "19" |
| meridian | [AaPp] .? [Mm] .? [\0\t ] | "A.m.", "pM", "am." |
| ii | [0-5][0-9] | "04", "8", "59" |
| II | [0-5][0-9] | "04", "08", "59" |
| M | 'jan' | 'feb' | 'mar' | 'apr' | 'may' | 'jun' | 'jul' | 'aug' | 'sep' | 'sept' | 'oct' | 'nov' | 'dec' | |
| MM | [0-5][0-9] | "00", "12", "59" |
| space | [ \t] | |
| ss | [0-5][0-9] | "04", "8", "59" |
| SS | [0-5][0-9] | "04", "08", "59" |
| W | "0"[1-9] | [1-4][0-9] | "5"[0-3] | "05", "17", "53" |
| tzcorrection | "GMT"? [+-] hh ":"? MM? | "+0400", "GMT-07:00", "-07:00" |
| YY | [0-9]{4} | "2000", "2008", "1978" |
| Description | Format | Examples |
|---|---|---|
| Common Log Format | dd "/" M "/" YY : HH ":" II ":" SS space tzcorrection | "10/Oct/2000:13:55:36 -0700" |
| EXIF | YY ":" MM ":" DD " " HH ":" II ":" SS | "2008:08:07 18:11:31" |
| ISO year with ISO week | YY "-"? "W" W | "2008W27", "2008-W28" |
| ISO year with ISO week and day | YY "-"? "W" W "-"? [0-7] | "2008W273", "2008-W28-3" |
| MySQL | YY "-" MM "-" DD " " HH ":" II ":" SS | "2008-08-07 18:11:31" |
| PostgreSQL: Year with day-of-year | YY "."? doy | "2008.197", "2008197" |
| SOAP | YY "-" MM "-" DD "T" HH ":" II ":" SS frac tzcorrection? | "2008-07-01T22:35:17.02", "2008-07-01T22:35:17.03+08:00" |
| Unix Timestamp | "@" "-"? [0-9]+ | "@1215282385" |
| XMLRPC | YY MM DD "T" hh ":" II ":" SS | "20080701T22:38:07", "20080701T9:38:07" |
| XMLRPC (Compact) | YY MM DD 't' hh II SS | "20080701t223807", "20080701T093807" |
| WDDX | YY "-" mm "-" dd "T" hh ":" ii ":" ss | "2008-7-1T9:3:37" |
Informacja:
The "W" in the "ISO year with ISO week" and "ISO year with ISO week and day" formats is case-sensitive, you can only use the upper case "W".
The "T" in the SOAP, XMRPC and WDDX formats is case-sensitive, you can only use the upper case "T".
The "Unix Timestamp" format sets the timezone to UTC.
Relative Formats
| Description | Format |
|---|---|
| dayname | 'sunday' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat' | 'sun' |
| daytext | 'weekday' | 'weekdays' |
| number | [+-]?[0-9]+ |
| ordinal | 'first' | 'second' | 'third' | 'fourth' | 'fifth' | 'sixth' | 'seventh' | 'eighth' | 'ninth' | 'tenth' | 'eleventh' | 'twelfth' | 'next' | 'last' | 'previous' | 'this' |
| reltext | 'next' | 'last' | 'previous' | 'this' |
| space | [ \t]+ |
| unit | (('sec' | 'second' | 'min' | 'minute' | 'hour' | 'day' | 'fortnight' | 'forthnight' | 'month' | 'year') 's'?) | 'weeks' | daytext |
| Format | Description | Examples |
|---|---|---|
| 'yesterday' | Midnight of yesterday | "yesterday 14:00" |
| 'midnight' | The time is set to 00:00:00 | |
| 'today' | The time is set to 00:00:00 | |
| 'now' | Now - this is simply ignored | |
| 'noon' | The time is set to 12:00:00 | "yesterday noon" |
| 'tomorrow' | Midnight of tomorrow | |
| 'back of' hour | 15 minutes past the specified hour | "back of 7pm", "back of 15" |
| 'front of' hour | 15 minutes before the specified hour | "front of 5am", "front of 23" |
| 'first day' ' of'? | Sets the day of the first of the current month. This phrase is best used together with a month name following it. | "first day of January 2008" |
| 'last day' ' of'? | Sets the day to the last day of the current month. This phrase is best used together with a month name following it. | "last day of next month" |
| ordinal space dayname space 'of' | Calculates the x-th week day of the current month. | "first sat of July 2008" |
| 'last' space dayname space 'of' | Calculates the last week day of the current month. | "last sat of July 2008" |
| number space? (unit | 'week') | Handles relative time items where the value is a number. | "+5 weeks", "12 day", "-7 weekdays" |
| ordinal space unit | Handles relative time items where the value is text. | "fifth day", "second month" |
| 'ago' | Negates all the values of previously found relative time items. | "2 days ago", "8 days ago 14:00", "2 months 5 days ago", "2 months ago 5 days", "2 days ago ago" |
| dayname | Moves to the next day of this name. | "Monday" |
| reltext space 'week' | Handles the special format "weekday + last/this/next week". | "Monday next week" |
Informacja:
Relative statements are always processed after non-relative statements. This makes "+1 week july 2008" and "july 2008 +1 week" equivalent.
Exceptions to this rule are: "yesterday", "midnight", "today", "noon" and "tomorrow". Note that "tomorrow 11:00" and "11:00 tomorrow" are different. Considering today's date of "July 23rd, 2008" the first one produces "2008-07-24 11:00" where as the second one produces "2008-07-24 00:00". The reason for this is that those five statements directly influence the current time.
Informacja:
Observe the following remarks when the current day-of-week is the same as the day-of-week used in the date/time string. The current day-of-week could have been (re-)calculated by non-relative parts of the date/time string however.
- "dayname" does not advance to another day. (Example: "Wed July 23rd, 2008" means "2008-07-23").
- "number dayname" does not advance to another day. (Example: "1 wednesday july 23rd, 2008" means "2008-07-23").
- "number week dayname" will first add the number of weeks, but does not advance to another day. In this case "number week" and "dayname" are two distinct blocks. (Example: "+1 week wednesday july 23rd, 2008" means "2008-07-30").
- "ordinal dayname" does advance to another day. (Example "first wednesday july 23rd, 2008" means "2008-07-30").
- "number week ordinal dayname" will first add the number of weeks, and then advances to another day. In this case "number week" and "ordinal dayname" are two distinct blocks. (Example: "+1 week first wednesday july 23rd, 2008" means "2008-08-06").
- "ordinal dayname 'of' " does not advance to another day. (Example: "first wednesday of july 23rd, 2008" means "2008-07-02" because the specific phrase with 'of' resets the day-of-month to '1' and the '23rd' is ignored here).
Also observe that the "of" in "ordinal space dayname space 'of' " and "'last' space dayname space 'of' " does something special.
- It sets the day-of-month to 1.
- "ordinal dayname 'of' " does not advance to another day. (Example: "first tuesday of july 2008" means "2008-07-01").
- "ordinal dayname " does advance to another day. (Example: "first tuesday july 2008" means "2008-07-08", see also point 4 in the list above).
- "'last' dayname 'of' " takes the last dayname of the current month. (Example: "last wed of july 2008" means "2008-07-30")
- "'last' dayname" takes the last dayname from the current day. (Example: "last wed july 2008" means "2008-06-25"; "july 2008" first sets the current date to "2008-07-01" and then "last wed" moves to the previous Wednesday which is "2008-06-25").
Informacja:
Relative month values are calculated based on the length of months that they pass through. An example would be "+2 month 2011-11-30", which would produce "2012-01-30". This is due to November being 30 days in length, and December being 31 days in length, producing a total of 61 days.
Lista obsługiwanych stref czasowych
Spis treści
Tutaj znajdziesz kompletną listę stref czasowych obsługiwanych przez PHP, co oznacza, że mogą być użyte np. w date_default_timezone_set().
Informacja: Najnowsza wersja bazy danych stref czasowych może być zainstalowana przez PECL » timezonedb. Dla użytkowników Windows, skompilowane DLL mogą być ściagnięte ze strony PECL4Win: » php_timezonedb.dll.
Informacja: Ta lista jest oparta o wersję bazy danych stref czasowych 2012.2.
Afryka
| Africa/Abidjan | Africa/Accra | Africa/Addis_Ababa | Africa/Algiers | Africa/Asmara |
| Africa/Asmera | Africa/Bamako | Africa/Bangui | Africa/Banjul | Africa/Bissau |
| Africa/Blantyre | Africa/Brazzaville | Africa/Bujumbura | Africa/Cairo | Africa/Casablanca |
| Africa/Ceuta | Africa/Conakry | Africa/Dakar | Africa/Dar_es_Salaam | Africa/Djibouti |
| Africa/Douala | Africa/El_Aaiun | Africa/Freetown | Africa/Gaborone | Africa/Harare |
| Africa/Johannesburg | Africa/Juba | Africa/Kampala | Africa/Khartoum | Africa/Kigali |
| Africa/Kinshasa | Africa/Lagos | Africa/Libreville | Africa/Lome | Africa/Luanda |
| Africa/Lubumbashi | Africa/Lusaka | Africa/Malabo | Africa/Maputo | Africa/Maseru |
| Africa/Mbabane | Africa/Mogadishu | Africa/Monrovia | Africa/Nairobi | Africa/Ndjamena |
| Africa/Niamey | Africa/Nouakchott | Africa/Ouagadougou | Africa/Porto-Novo | Africa/Sao_Tome |
| Africa/Timbuktu | Africa/Tripoli | Africa/Tunis | Africa/Windhoek |
Ameryka
| America/Adak | America/Anchorage | America/Anguilla | America/Antigua | America/Araguaina |
| America/Argentina/Buenos_Aires | America/Argentina/Catamarca | America/Argentina/ComodRivadavia | America/Argentina/Cordoba | America/Argentina/Jujuy |
| America/Argentina/La_Rioja | America/Argentina/Mendoza | America/Argentina/Rio_Gallegos | America/Argentina/Salta | America/Argentina/San_Juan |
| America/Argentina/San_Luis | America/Argentina/Tucuman | America/Argentina/Ushuaia | America/Aruba | America/Asuncion |
| America/Atikokan | America/Atka | America/Bahia | America/Bahia_Banderas | America/Barbados |
| America/Belem | America/Belize | America/Blanc-Sablon | America/Boa_Vista | America/Bogota |
| America/Boise | America/Buenos_Aires | America/Cambridge_Bay | America/Campo_Grande | America/Cancun |
| America/Caracas | America/Catamarca | America/Cayenne | America/Cayman | America/Chicago |
| America/Chihuahua | America/Coral_Harbour | America/Cordoba | America/Costa_Rica | America/Creston |
| America/Cuiaba | America/Curacao | America/Danmarkshavn | America/Dawson | America/Dawson_Creek |
| America/Denver | America/Detroit | America/Dominica | America/Edmonton | America/Eirunepe |
| America/El_Salvador | America/Ensenada | America/Fort_Wayne | America/Fortaleza | America/Glace_Bay |
| America/Godthab | America/Goose_Bay | America/Grand_Turk | America/Grenada | America/Guadeloupe |
| America/Guatemala | America/Guayaquil | America/Guyana | America/Halifax | America/Havana |
| America/Hermosillo | America/Indiana/Indianapolis | America/Indiana/Knox | America/Indiana/Marengo | America/Indiana/Petersburg |
| America/Indiana/Tell_City | America/Indiana/Vevay | America/Indiana/Vincennes | America/Indiana/Winamac | America/Indianapolis |
| America/Inuvik | America/Iqaluit | America/Jamaica | America/Jujuy | America/Juneau |
| America/Kentucky/Louisville | America/Kentucky/Monticello | America/Knox_IN | America/Kralendijk | America/La_Paz |
| America/Lima | America/Los_Angeles | America/Louisville | America/Lower_Princes | America/Maceio |
| America/Managua | America/Manaus | America/Marigot | America/Martinique | America/Matamoros |
| America/Mazatlan | America/Mendoza | America/Menominee | America/Merida | America/Metlakatla |
| America/Mexico_City | America/Miquelon | America/Moncton | America/Monterrey | America/Montevideo |
| America/Montreal | America/Montserrat | America/Nassau | America/New_York | America/Nipigon |
| America/Nome | America/Noronha | America/North_Dakota/Beulah | America/North_Dakota/Center | America/North_Dakota/New_Salem |
| America/Ojinaga | America/Panama | America/Pangnirtung | America/Paramaribo | America/Phoenix |
| America/Port-au-Prince | America/Port_of_Spain | America/Porto_Acre | America/Porto_Velho | America/Puerto_Rico |
| America/Rainy_River | America/Rankin_Inlet | America/Recife | America/Regina | America/Resolute |
| America/Rio_Branco | America/Rosario | America/Santa_Isabel | America/Santarem | America/Santiago |
| America/Santo_Domingo | America/Sao_Paulo | America/Scoresbysund | America/Shiprock | America/Sitka |
| America/St_Barthelemy | America/St_Johns | America/St_Kitts | America/St_Lucia | America/St_Thomas |
| America/St_Vincent | America/Swift_Current | America/Tegucigalpa | America/Thule | America/Thunder_Bay |
| America/Tijuana | America/Toronto | America/Tortola | America/Vancouver | America/Virgin |
| America/Whitehorse | America/Winnipeg | America/Yakutat | America/Yellowknife |
Antarktyda
| Antarctica/Casey | Antarctica/Davis | Antarctica/DumontDUrville | Antarctica/Macquarie | Antarctica/Mawson |
| Antarctica/McMurdo | Antarctica/Palmer | Antarctica/Rothera | Antarctica/South_Pole | Antarctica/Syowa |
| Antarctica/Vostok |
Arktyka
| Arctic/Longyearbyen |
Azja
| Asia/Aden | Asia/Almaty | Asia/Amman | Asia/Anadyr | Asia/Aqtau |
| Asia/Aqtobe | Asia/Ashgabat | Asia/Ashkhabad | Asia/Baghdad | Asia/Bahrain |
| Asia/Baku | Asia/Bangkok | Asia/Beirut | Asia/Bishkek | Asia/Brunei |
| Asia/Calcutta | Asia/Choibalsan | Asia/Chongqing | Asia/Chungking | Asia/Colombo |
| Asia/Dacca | Asia/Damascus | Asia/Dhaka | Asia/Dili | Asia/Dubai |
| Asia/Dushanbe | Asia/Gaza | Asia/Harbin | Asia/Hebron | Asia/Ho_Chi_Minh |
| Asia/Hong_Kong | Asia/Hovd | Asia/Irkutsk | Asia/Istanbul | Asia/Jakarta |
| Asia/Jayapura | Asia/Jerusalem | Asia/Kabul | Asia/Kamchatka | Asia/Karachi |
| Asia/Kashgar | Asia/Kathmandu | Asia/Katmandu | Asia/Kolkata | Asia/Krasnoyarsk |
| Asia/Kuala_Lumpur | Asia/Kuching | Asia/Kuwait | Asia/Macao | Asia/Macau |
| Asia/Magadan | Asia/Makassar | Asia/Manila | Asia/Muscat | Asia/Nicosia |
| Asia/Novokuznetsk | Asia/Novosibirsk | Asia/Omsk | Asia/Oral | Asia/Phnom_Penh |
| Asia/Pontianak | Asia/Pyongyang | Asia/Qatar | Asia/Qyzylorda | Asia/Rangoon |
| Asia/Riyadh | Asia/Saigon | Asia/Sakhalin | Asia/Samarkand | Asia/Seoul |
| Asia/Shanghai | Asia/Singapore | Asia/Taipei | Asia/Tashkent | Asia/Tbilisi |
| Asia/Tehran | Asia/Tel_Aviv | Asia/Thimbu | Asia/Thimphu | Asia/Tokyo |
| Asia/Ujung_Pandang | Asia/Ulaanbaatar | Asia/Ulan_Bator | Asia/Urumqi | Asia/Vientiane |
| Asia/Vladivostok | Asia/Yakutsk | Asia/Yekaterinburg | Asia/Yerevan |
Ocean Atlantycki
| Atlantic/Azores | Atlantic/Bermuda | Atlantic/Canary | Atlantic/Cape_Verde | Atlantic/Faeroe |
| Atlantic/Faroe | Atlantic/Jan_Mayen | Atlantic/Madeira | Atlantic/Reykjavik | Atlantic/South_Georgia |
| Atlantic/St_Helena | Atlantic/Stanley |
Australia
| Australia/ACT | Australia/Adelaide | Australia/Brisbane | Australia/Broken_Hill | Australia/Canberra |
| Australia/Currie | Australia/Darwin | Australia/Eucla | Australia/Hobart | Australia/LHI |
| Australia/Lindeman | Australia/Lord_Howe | Australia/Melbourne | Australia/North | Australia/NSW |
| Australia/Perth | Australia/Queensland | Australia/South | Australia/Sydney | Australia/Tasmania |
| Australia/Victoria | Australia/West | Australia/Yancowinna |
Europa
| Europe/Amsterdam | Europe/Andorra | Europe/Athens | Europe/Belfast | Europe/Belgrade |
| Europe/Berlin | Europe/Bratislava | Europe/Brussels | Europe/Bucharest | Europe/Budapest |
| Europe/Chisinau | Europe/Copenhagen | Europe/Dublin | Europe/Gibraltar | Europe/Guernsey |
| Europe/Helsinki | Europe/Isle_of_Man | Europe/Istanbul | Europe/Jersey | Europe/Kaliningrad |
| Europe/Kiev | Europe/Lisbon | Europe/Ljubljana | Europe/London | Europe/Luxembourg |
| Europe/Madrid | Europe/Malta | Europe/Mariehamn | Europe/Minsk | Europe/Monaco |
| Europe/Moscow | Europe/Nicosia | Europe/Oslo | Europe/Paris | Europe/Podgorica |
| Europe/Prague | Europe/Riga | Europe/Rome | Europe/Samara | Europe/San_Marino |
| Europe/Sarajevo | Europe/Simferopol | Europe/Skopje | Europe/Sofia | Europe/Stockholm |
| Europe/Tallinn | Europe/Tirane | Europe/Tiraspol | Europe/Uzhgorod | Europe/Vaduz |
| Europe/Vatican | Europe/Vienna | Europe/Vilnius | Europe/Volgograd | Europe/Warsaw |
| Europe/Zagreb | Europe/Zaporozhye | Europe/Zurich |
Ocean Indyjski
| Indian/Antananarivo | Indian/Chagos | Indian/Christmas | Indian/Cocos | Indian/Comoro |
| Indian/Kerguelen | Indian/Mahe | Indian/Maldives | Indian/Mauritius | Indian/Mayotte |
| Indian/Reunion |
Ocean Spokojny
| Pacific/Apia | Pacific/Auckland | Pacific/Chatham | Pacific/Chuuk | Pacific/Easter |
| Pacific/Efate | Pacific/Enderbury | Pacific/Fakaofo | Pacific/Fiji | Pacific/Funafuti |
| Pacific/Galapagos | Pacific/Gambier | Pacific/Guadalcanal | Pacific/Guam | Pacific/Honolulu |
| Pacific/Johnston | Pacific/Kiritimati | Pacific/Kosrae | Pacific/Kwajalein | Pacific/Majuro |
| Pacific/Marquesas | Pacific/Midway | Pacific/Nauru | Pacific/Niue | Pacific/Norfolk |
| Pacific/Noumea | Pacific/Pago_Pago | Pacific/Palau | Pacific/Pitcairn | Pacific/Pohnpei |
| Pacific/Ponape | Pacific/Port_Moresby | Pacific/Rarotonga | Pacific/Saipan | Pacific/Samoa |
| Pacific/Tahiti | Pacific/Tarawa | Pacific/Tongatapu | Pacific/Truk | Pacific/Wake |
| Pacific/Wallis | Pacific/Yap |
Inne
| Brazil/Acre | Brazil/DeNoronha | Brazil/East | Brazil/West | Canada/Atlantic |
| Canada/Central | Canada/East-Saskatchewan | Canada/Eastern | Canada/Mountain | Canada/Newfoundland |
| Canada/Pacific | Canada/Saskatchewan | Canada/Yukon | CET | Chile/Continental |
| Chile/EasterIsland | CST6CDT | Cuba | EET | Egypt |
| Eire | EST | EST5EDT | Etc/GMT | Etc/GMT+0 |
| Etc/GMT+1 | Etc/GMT+10 | Etc/GMT+11 | Etc/GMT+12 | Etc/GMT+2 |
| Etc/GMT+3 | Etc/GMT+4 | Etc/GMT+5 | Etc/GMT+6 | Etc/GMT+7 |
| Etc/GMT+8 | Etc/GMT+9 | Etc/GMT-0 | Etc/GMT-1 | Etc/GMT-10 |
| Etc/GMT-11 | Etc/GMT-12 | Etc/GMT-13 | Etc/GMT-14 | Etc/GMT-2 |
| Etc/GMT-3 | Etc/GMT-4 | Etc/GMT-5 | Etc/GMT-6 | Etc/GMT-7 |
| Etc/GMT-8 | Etc/GMT-9 | Etc/GMT0 | Etc/Greenwich | Etc/UCT |
| Etc/Universal | Etc/UTC | Etc/Zulu | Factory | GB |
| GB-Eire | GMT | GMT+0 | GMT-0 | GMT0 |
| Greenwich | Hongkong | HST | Iceland | Iran |
| Israel | Jamaica | Japan | Kwajalein | Libya |
| MET | Mexico/BajaNorte | Mexico/BajaSur | Mexico/General | MST |
| MST7MDT | Navajo | NZ | NZ-CHAT | Poland |
| Portugal | PRC | PST8PDT | ROC | ROK |
| Singapore | Turkey | UCT | Universal | US/Alaska |
| US/Aleutian | US/Arizona | US/Central | US/East-Indiana | US/Eastern |
| US/Hawaii | US/Indiana-Starke | US/Michigan | US/Mountain | US/Pacific |
| US/Pacific-New | US/Samoa | UTC | W-SU | WET |
| Zulu |
Proszę nie używać żadnej ze stref czasowych podanych tutaj (za wyjątkiem UTC), istnieją one wyłącznie z powodu wstecznej kompatybilności.
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- DateTime — The DateTime class
- DateTime::add — Adds an amount of days, months, years, hours, minutes and seconds to a DateTime object
- DateTime::__construct — Returns new DateTime object
- DateTime::createFromFormat — Returns new DateTime object formatted according to the specified format
- DateTime::diff — Returns the difference between two DateTime objects
- DateTime::format — Returns date formatted according to given format
- DateTime::getLastErrors — Returns the warnings and errors
- DateTime::getOffset — Returns the timezone offset
- DateTime::getTimestamp — Gets the Unix timestamp
- DateTime::getTimezone — Return time zone relative to given DateTime
- DateTime::modify — Alters the timestamp
- DateTime::__set_state — The __set_state handler
- DateTime::setDate — Sets the date
- DateTime::setISODate — Sets the ISO date
- DateTime::setTime — Sets the time
- DateTime::setTimestamp — Sets the date and time based on an Unix timestamp
- DateTime::setTimezone — Sets the time zone for the DateTime object
- DateTime::sub — Subtracts an amount of days, months, years, hours, minutes and seconds from a DateTime object
- DateTime::__wakeup — The __wakeup handler
- DateTimeZone — The DateTimeZone class
- DateTimeZone::__construct — Creates new DateTimeZone object
- DateTimeZone::getLocation — Returns location information for a timezone
- DateTimeZone::getName — Returns the name of the timezone
- DateTimeZone::getOffset — Returns the timezone offset from GMT
- DateTimeZone::getTransitions — Returns all transitions for the timezone
- DateTimeZone::listAbbreviations — Returns associative array containing dst, offset and the timezone name
- DateTimeZone::listIdentifiers — Returns numerically index array with all timezone identifiers
- DateInterval — The DateInterval class
- DateInterval::__construct — Creates new DateInterval object
- DateInterval::createFromDateString — Sets up a DateInterval from the relative parts of the string
- DateInterval::format — Formats the interval
- DatePeriod — The DatePeriod class
- DatePeriod::__construct — Creates new DatePeriod object
- Funkcje daty i czasu
- checkdate — Waliduje datę gregoriańską
- date_add — Alias dla DateTime::add
- date_create_from_format — Alias dla DateTime::createFromFormat
- date_create — Alias dla DateTime::__construct
- date_date_set — Alias dla DateTime::setDate
- date_default_timezone_get — Gets the default timezone used by all date/time functions in a script
- date_default_timezone_set — Sets the default timezone used by all date/time functions in a script
- date_diff — Alias dla DateTime::diff
- date_format — Alias dla DateTime::format
- date_get_last_errors — Alias dla DateTime::getLastErrors
- date_interval_create_from_date_string — Alias dla DateInterval::createFromDateString
- date_interval_format — Alias dla DateInterval::format
- date_isodate_set — Alias dla DateTime::setISODate
- date_modify — Alias dla DateTime::modify
- date_offset_get — Alias dla DateTime::getOffset
- date_parse_from_format — Get info about given date formatted according to the specified format
- date_parse — Returns associative array with detailed info about given date
- date_sub — Alias dla DateTime::sub
- date_sun_info — Returns an array with information about sunset/sunrise and twilight begin/end
- date_sunrise — Returns time of sunrise for a given day and location
- date_sunset — Returns time of sunset for a given day and location
- date_time_set — Alias dla DateTime::setTime
- date_timestamp_get — Alias dla DateTime::getTimestamp
- date_timestamp_set — Alias dla DateTime::setTimestamp
- date_timezone_get — Alias dla DateTime::getTimezone
- date_timezone_set — Alias dla DateTime::setTimezone
- date — Formatuje lokalny czas/datę
- getdate — Pobiera informację o dacie/czasie
- gettimeofday — Pobiera aktualny czas
- gmdate — Formatuje datę/czas dla strefy GMT/UTC
- gmmktime — Ustala uniksowy znacznik czasu dla daty ze strefy GMT
- gmstrftime — Formatuje czas/datę ze strefy GMT/UTC zgodnie z lokalizacją
- idate — Format a local time/date as integer
- localtime — Pobiera czas lokalny
- microtime — Zwraca aktualny uniksowy znacznik czasu z mikrosekundami
- mktime — Oblicza uniksowy znacznik czasu dla podanej daty
- strftime — Formatuje lokalną datę/czas zgodnie z lokalizacją
- strptime — Parse a time/date generated with strftime
- strtotime — Parsuje większość angielskich tekstowych opisów daty i czasu do uniksowego znacznika czasu
- time — Zwraca aktualny uniksowy znacznik czasu
- timezone_abbreviations_list — Alias dla DateTimeZone::listAbbreviations
- timezone_identifiers_list — Alias dla DateTimeZone::listIdentifiers
- timezone_location_get — Alias dla DateTimeZone::getLocation
- timezone_name_from_abbr — Returns the timezone name from abbreviation
- timezone_name_get — Alias dla DateTimeZone::getName
- timezone_offset_get — Alias dla DateTimeZone::getOffset
- timezone_open — Alias dla DateTimeZone::__construct
- timezone_transitions_get — Alias dla DateTimeZone::getTransitions
- timezone_version_get — Gets the version of the timezonedb
- Supported Date and Time Formats
- Lista obsługiwanych stref czasowych
- Calendar
- data/czas — Data i Czas
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- DateTime — The DateTime class
- DateTimeZone — The DateTimeZone class
- DateInterval — The DateInterval class
- DatePeriod — The DatePeriod class
- Funkcje daty i czasu
- Supported Date and Time Formats
- Lista obsługiwanych stref czasowych
Rozszerzenia wiersza poleceń
Ncurses Terminal Screen Control
Wstęp
ncurses (new curses) is a free software emulation of curses in System V Rel 4.0 (and above). It uses terminfo format, supports pads, colors, multiple highlights, form characters and function key mapping. Because of the interactive nature of this library, it will be of little use for writing Web applications, but may be useful when writing scripts meant using PHP from the command line.
The features available, such as colors, depend on the terminal that you are using. Use functions such as ncurses_has_colors(), ncurses_can_change_color(), and ncurses_has_ic() to check for individual capabilities.
Informacja:
To rozszerzenie zostało przeniesione do repozytorium » PECL i nie jest rozprowadzane z PHP od wersji 5.3.0.
ncurses is available for the following platforms:
- AIX
- BeOS
- BSD variants (FreeBSD, NetBSD, OpenBSD)
- Cygwin
- Digital Unix (aka OSF1)
- GNU/Linux
- HPUX
- IRIX64
- Mac OS X
- OS/2
- QNX
- SCO OpenServer
- Solaris
- Tru64
Instalacja/Konfiguracja
Spis treści
Wymagania
You need the ncurses libraries and headerfiles. Download the latest version from the » ftp://ftp.gnu.org/pub/gnu/ncurses/ or from an other GNU-Mirror.
Instalacja
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/ncurses.
Wide character CRT screen handling (ncursesw) support was added in version 1.0.1 of this PECL extension.
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
This extension defines window, panel and pad resources.
Stałe predefiniowane
Spis treści
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
Error codes
On error ncurses functions return -1. Some functions return 0 on success. See the relevant pages in the documentation for actual return values.
Colors
| constant | meaning |
|---|---|
NCURSES_COLOR_BLACK |
no color (black) |
NCURSES_COLOR_WHITE |
white |
NCURSES_COLOR_RED |
red - supported when terminal is in color mode |
NCURSES_COLOR_GREEN |
green - supported when terminal is in color mode |
NCURSES_COLOR_YELLOW |
yellow - supported when terminal is in color mode |
NCURSES_COLOR_BLUE |
blue - supported when terminal is in color mode |
NCURSES_COLOR_CYAN |
cyan - supported when terminal is in color mode |
NCURSES_COLOR_MAGENTA |
magenta - supported when terminal is in color mode |
Keys
| constant | meaning |
|---|---|
NCURSES_KEY_F0 - NCURSES_KEY_F64 |
function keys F1 - F64 |
NCURSES_KEY_DOWN |
down arrow |
NCURSES_KEY_UP |
up arrow |
NCURSES_KEY_LEFT |
left arrow |
NCURSES_KEY_RIGHT |
right arrow |
NCURSES_KEY_HOME |
home key (upward+left arrow) |
NCURSES_KEY_BACKSPACE |
backspace |
NCURSES_KEY_DL |
delete line |
NCURSES_KEY_IL |
insert line |
NCURSES_KEY_DC |
delete character |
NCURSES_KEY_IC |
insert char or enter insert mode |
NCURSES_KEY_EIC |
exit insert char mode |
NCURSES_KEY_CLEAR |
clear screen |
NCURSES_KEY_EOS |
clear to end of screen |
NCURSES_KEY_EOL |
clear to end of line |
NCURSES_KEY_SF |
scroll one line forward |
NCURSES_KEY_SR |
scroll one line backward |
NCURSES_KEY_NPAGE |
next page |
NCURSES_KEY_PPAGE |
previous page |
NCURSES_KEY_STAB |
set tab |
NCURSES_KEY_CTAB |
clear tab |
NCURSES_KEY_CATAB |
clear all tabs |
NCURSES_KEY_SRESET |
soft (partial) reset |
NCURSES_KEY_RESET |
reset or hard reset |
NCURSES_KEY_PRINT |
|
NCURSES_KEY_LL |
lower left |
NCURSES_KEY_A1 |
upper left of keypad |
NCURSES_KEY_A3 |
upper right of keypad |
NCURSES_KEY_B2 |
center of keypad |
NCURSES_KEY_C1 |
lower left of keypad |
NCURSES_KEY_C3 |
lower right of keypad |
NCURSES_KEY_BTAB |
back tab |
NCURSES_KEY_BEG |
beginning |
NCURSES_KEY_CANCEL |
cancel |
NCURSES_KEY_CLOSE |
close |
NCURSES_KEY_COMMAND |
cmd (command) |
NCURSES_KEY_COPY |
copy |
NCURSES_KEY_CREATE |
create |
NCURSES_KEY_END |
end |
NCURSES_KEY_EXIT |
exit |
NCURSES_KEY_FIND |
find |
NCURSES_KEY_HELP |
help |
NCURSES_KEY_MARK |
mark |
NCURSES_KEY_MESSAGE |
message |
NCURSES_KEY_MOVE |
move |
NCURSES_KEY_NEXT |
next |
NCURSES_KEY_OPEN |
open |
NCURSES_KEY_OPTIONS |
options |
NCURSES_KEY_PREVIOUS |
previous |
NCURSES_KEY_REDO |
redo |
NCURSES_KEY_REFERENCE |
ref (reference) |
NCURSES_KEY_REFRESH |
refresh |
NCURSES_KEY_REPLACE |
replace |
NCURSES_KEY_RESTART |
restart |
NCURSES_KEY_RESUME |
resume |
NCURSES_KEY_SAVE |
save |
NCURSES_KEY_SBEG |
shiftet beg (beginning) |
NCURSES_KEY_SCANCEL |
shifted cancel |
NCURSES_KEY_SCOMMAND |
shifted command |
NCURSES_KEY_SCOPY |
shifted copy |
NCURSES_KEY_SCREATE |
shifted create |
NCURSES_KEY_SDC |
shifted delete char |
NCURSES_KEY_SDL |
shifted delete line |
NCURSES_KEY_SELECT |
select |
NCURSES_KEY_SEND |
shifted end |
NCURSES_KEY_SEOL |
shifted end of line |
NCURSES_KEY_SEXIT |
shifted exit |
NCURSES_KEY_SFIND |
shifted find |
NCURSES_KEY_SHELP |
shifted help |
NCURSES_KEY_SHOME |
shifted home |
NCURSES_KEY_SIC |
shifted input |
NCURSES_KEY_SLEFT |
shifted left arrow |
NCURSES_KEY_SMESSAGE |
shifted message |
NCURSES_KEY_SMOVE |
shifted move |
NCURSES_KEY_SNEXT |
shifted next |
NCURSES_KEY_SOPTIONS |
shifted options |
NCURSES_KEY_SPREVIOUS |
shifted previous |
NCURSES_KEY_SPRINT |
shifted print |
NCURSES_KEY_SREDO |
shifted redo |
NCURSES_KEY_SREPLACE |
shifted replace |
NCURSES_KEY_SRIGHT |
shifted right arrow |
NCURSES_KEY_SRSUME |
shifted resume |
NCURSES_KEY_SSAVE |
shifted save |
NCURSES_KEY_SSUSPEND |
shifted suspend |
NCURSES_KEY_UNDO |
undo |
NCURSES_KEY_MOUSE |
mouse event has occurred |
NCURSES_KEY_MAX |
maximum key value |
Mouse
| Constant | meaning |
|---|---|
NCURSES_BUTTON1_RELEASED - NCURSES_BUTTON4_RELEASED |
button (1-4) released |
NCURSES_BUTTON1_PRESSED - NCURSES_BUTTON4_PRESSED |
button (1-4) pressed |
NCURSES_BUTTON1_CLICKED - NCURSES_BUTTON4_CLICKED |
button (1-4) clicked |
NCURSES_BUTTON1_DOUBLE_CLICKED -
NCURSES_BUTTON4_DOUBLE_CLICKED |
button (1-4) double clicked |
NCURSES_BUTTON1_TRIPLE_CLICKED -
NCURSES_BUTTON4_TRIPLE_CLICKED |
button (1-4) triple clicked |
NCURSES_BUTTON_CTRL |
ctrl pressed during click |
NCURSES_BUTTON_SHIFT |
shift pressed during click |
NCURSES_BUTTON_ALT |
alt pressed during click |
NCURSES_ALL_MOUSE_EVENTS |
report all mouse events |
NCURSES_REPORT_MOUSE_POSITION |
report mouse position |
Ncurses Funkcje
ncurses_addch
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_addch — Add character at current position and advance cursor
Opis
$ch
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
ch -
ncurses_addchnstr
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_addchnstr — Add attributed string with specified length at current position
Opis
$s
, int $n
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
s -
-
n -
ncurses_addchstr
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_addchstr — Add attributed string at current position
Opis
$s
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
s -
ncurses_addnstr
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_addnstr — Add string with specified length at current position
Opis
$s
, int $n
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
s -
-
n -
ncurses_addstr
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_addstr — Output text at current position
Opis
$text
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
text -
ncurses_assume_default_colors
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_assume_default_colors — Define default colors for color 0
Opis
$fg
, int $bg
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
fg -
-
bg -
ncurses_attroff
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_attroff — Turn off the given attributes
Opis
$attributes
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
attributes -
ncurses_attron
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_attron — Turn on the given attributes
Opis
$attributes
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
attributes -
ncurses_attrset
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_attrset — Set given attributes
Opis
$attributes
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
attributes -
ncurses_baudrate
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_baudrate — Returns baudrate of terminal
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
ncurses_beep
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_beep — Let the terminal beep
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
ncurses_beep() sends an audible alert (bell) and if its not possible flashes the screen.
ncurses_bkgd
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_bkgd — Set background property for terminal screen
Opis
$attrchar
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
attrchar -
ncurses_bkgdset
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_bkgdset — Control screen background
Opis
$attrchar
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
attrchar -
ncurses_border
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_border — Draw a border around the screen using attributed characters
Opis
$left
, int $right
, int $top
, int $bottom
, int $tl_corner
, int $tr_corner
, int $bl_corner
, int $br_corner
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Draws the specified lines and corners around the main window.
Use ncurses_wborder() for borders around subwindows!
Parametry
Every parameter expects 0 to draw a line or 1 to skip it.
-
left -
-
right -
-
top -
-
bottom -
-
tl_corner -
Top left corner
-
tr_corner -
Top right corner
-
bl_corner -
Bottom left corner
-
br_corner -
Bottom right corner
ncurses_bottom_panel
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_bottom_panel — Moves a visible panel to the bottom of the stack
Opis
$panel
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
panel -
ncurses_can_change_color
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_can_change_color — Checks if terminal color definitions can be changed
Opis
Checks whether the terminal has color capabilities and whether the programmer can change color definitions using ncurses_init_color(). ncurses must be initialized using ncurses_init() before calling this function.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Return TRUE if the programmer can change color definitions,
FALSE otherwise.
Zobacz też:
- ncurses_has_colors() - Checks if terminal has color capabilities
- ncurses_init_color() - Define a terminal color
- ncurses_start_color() - Initializes color functionality
ncurses_cbreak
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_cbreak — Switch of input buffering
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Disables line buffering and character processing (interrupt and flow control characters are unaffected), making characters typed by the user immediately available to the program.
Zwracane wartości
Returns TRUE or NCURSES_ERR if any error occurred.
ncurses_clear
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_clear — Clear screen
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Clears the screen completely without setting blanks.
Note: ncurses_clear() clears the screen without setting blanks, which have the current background rendition. To clear screen with blanks, use ncurses_erase().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
ncurses_clrtobot
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_clrtobot — Clear screen from current position to bottom
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Erases all lines from cursor to end of screen and creates blanks. Blanks created by ncurses_clrtobot() have the current background rendition.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- ncurses_clear() - Clear screen
- ncurses_clrtoeol() - Clear screen from current position to end of line
ncurses_clrtoeol
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_clrtoeol — Clear screen from current position to end of line
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Erases the current line from cursor position to the end. Blanks created by ncurses_clrtoeol() have the current background rendition.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- ncurses_clear() - Clear screen
- ncurses_clrtobot() - Clear screen from current position to bottom
ncurses_color_content
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_color_content — Retrieves RGB components of a color
Opis
$color
, int &$r
, int &$g
, int &$b
)Retrieves the red, green, and blue components for the given color definition. Terminal color capabilities must be initialized with ncurses_start_color() prior to calling this function.
Parametry
-
color -
The number of the color to retrieve information for. May be one of the pre-defined color constants.
-
r -
A reference to which to return the red component of the color. The value returned to the reference will be between 0 and 1000.
-
g -
A reference to which to return the green component of the color. The value returned to the reference will be between 0 and 1000.
-
b -
A reference to which to return the blue component of the color. The value returned to the reference will be between 0 and 1000.
Zwracane wartości
Returns -1 if the function was successful, and 0 if ncurses or terminal color capabilities have not been initialized.
Zobacz też:
- ncurses_init_color() - Define a terminal color
- ncurses_start_color() - Initializes color functionality
ncurses_color_set
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_color_set — Set active foreground and background colors
Opis
$pair
)Sets the active foreground and background colors. Any characters written after this function is invoked will have these colors. This function requires terminal colors to be supported and initialized using ncurses_start_color() beforehand.
ncurses uses color pairs to specify both foreground and background colors. Use ncurses_init_pair() to define a color pair.
Parametry
-
pair -
The color pair from which to get the foreground and background colors to set as the active colors.
Zwracane wartości
Returns -1 on success, and 0 on failure.
Przykłady
Przykład #1 Writing a string with a specified color to the screen
<?php
ncurses_init();
// If the terminal supports colors, initialize and set active color
if (ncurses_has_colors()) {
ncurses_start_color();
ncurses_init_pair(1, NCURSES_COLOR_YELLOW, NCURSES_COLOR_BLUE);
ncurses_color_set(1);
}
// Write a string at specified location
ncurses_mvaddstr(10, 10, "Hello world! Yellow on blue text!");
// Flush output to screen
ncurses_refresh();
ncurses_end();
?>
Zobacz też:
- ncurses_init_pair() - Define a color pair
- ncurses_start_color() - Initializes color functionality
ncurses_curs_set
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_curs_set — Set cursor state
Opis
$visibility
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
visibility -
ncurses_def_prog_mode
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_def_prog_mode — Saves terminals (program) mode
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Saves the current terminal modes for program (in curses) for use by ncurses_reset_prog_mode().
Zwracane wartości
Returns FALSE on success, otherwise TRUE.
ncurses_def_shell_mode
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_def_shell_mode — Saves terminals (shell) mode
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Saves the current terminal modes for shell (not in curses) for use by ncurses_reset_shell_mode().
Zwracane wartości
Returns FALSE on success, TRUE otherwise.
ncurses_define_key
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_define_key — Define a keycode
Opis
$definition
, int $keycode
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
definition -
-
keycode -
ncurses_del_panel
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_del_panel — Remove panel from the stack and delete it (but not the associated window)
Opis
$panel
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
panel -
ncurses_delay_output
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_delay_output — Delay output on terminal using padding characters
Opis
$milliseconds
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
milliseconds -
ncurses_delch
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_delch — Delete character at current position, move rest of line left
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Deletes the character under the cursor. All characters to the right of the cursor on the same line are moved to the left one position and the last character on the line is filled with a blank. The cursor position does not change.
Zwracane wartości
Returns FALSE on success, TRUE otherwise.
ncurses_deleteln
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_deleteln — Delete line at current position, move rest of screen up
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Deletes the current line under cursorposition. All lines below the current line are moved up one line. The bottom line of window is cleared. Cursor position does not change.
Zwracane wartości
Returns FALSE on success, otherwise TRUE.
ncurses_delwin
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_delwin — Delete a ncurses window
Opis
$window
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
window -
ncurses_doupdate
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_doupdate — Write all prepared refreshes to terminal
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Compares the virtual screen to the physical screen and updates the physical screen. This way is more effective than using multiple refresh calls.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
ncurses_echo
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_echo — Activate keyboard input echo
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Enables echo mode. All characters typed by user are echoed by ncurses_getch().
Zwracane wartości
Returns FALSE on success, TRUE if any error occurred.
ncurses_echochar
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_echochar — Single character output including refresh
Opis
$character
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
character -
ncurses_end
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_end — Stop using ncurses, clean up the screen
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
ncurses_erase
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_erase — Erase terminal screen
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Fills the terminal screen with blanks.
Created blanks have the current background rendition, set by ncurses_bkgd().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- ncurses_bkgd() - Set background property for terminal screen
- ncurses_clear() - Clear screen
ncurses_erasechar
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_erasechar — Returns current erase character
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Returns the current erase character.
Zwracane wartości
The current erase char, as a string.
ncurses_filter
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_filter — Set LINES for iniscr() and newterm() to 1
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
ncurses_flash
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_flash — Flash terminal screen (visual bell)
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Flashes the screen, and if its not possible, sends an audible alert (bell).
Zwracane wartości
Returns FALSE on success, otherwise TRUE.
ncurses_flushinp
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_flushinp — Flush keyboard input buffer
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Throws away any typeahead that has been typed and has not yet been read by your program.
Zwracane wartości
Returns FALSE on success, otherwise TRUE.
ncurses_getch
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_getch — Read a character from keyboard
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
ncurses_getmaxyx
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_getmaxyx — Returns the size of a window
Opis
$window
, int &$y
, int &$x
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Gets the horizontal and vertical size of the given
window into the given variables.
Variables must be passed as reference, so they are updated when the user changes the terminal size.
Parametry
-
window -
The measured window
-
y -
This will be set to the window height
-
x -
This will be set to the window width
Zwracane wartości
Nie jest zwracana żadna wartość.
ncurses_getmouse
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_getmouse — Reads mouse event
Opis
&$mevent
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
ncurses_getmouse() reads mouse event out of queue.
Parametry
-
mevent -
Event options will be delivered in this parameter which has to be an array, passed by reference (see example below).
On success an associative array with following keys will be delivered:
-
"id" : Id to distinguish multiple devices
-
"x" : screen relative x-position in character cells
-
"y" : screen relative y-position in character cells
-
"z" : currently not supported
-
"mmask" : Mouse action
-
Zwracane wartości
Returns FALSE if a mouse event is actually visible in the given window,
otherwise returns TRUE.
Przykłady
Przykład #1 ncurses_getmouse() example
<?php
switch (ncurses_getch()){
case NCURSES_KEY_MOUSE:
if (!ncurses_getmouse($mevent)){
if ($mevent["mmask"] & NCURSES_MOUSE_BUTTON1_PRESSED){
$mouse_x = $mevent["x"]; // Save mouse position
$mouse_y = $mevent["y"];
}
}
break;
default:
/* .... */
}
?>
ncurses_getyx
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_getyx — Returns the current cursor position for a window
Opis
$window
, int &$y
, int &$x
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
window -
-
y -
-
x -
ncurses_halfdelay
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_halfdelay — Put terminal into halfdelay mode
Opis
$tenth
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
tenth -
ncurses_has_colors
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_has_colors — Checks if terminal has color capabilities
Opis
Checks whether the terminal has color capabilities. This function can be used to write terminal-independent programs. ncurses must be initialized using ncurses_init() before calling this function.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Return TRUE if the terminal has color capabilities, FALSE otherwise.
Przykłady
Przykład #1 Writing a string with a specified color to the screen
<?php
ncurses_init();
// If the terminal supports colors, initialize and set active color
if (ncurses_has_colors()) {
ncurses_start_color();
ncurses_init_pair(1, NCURSES_COLOR_YELLOW, NCURSES_COLOR_BLUE);
ncurses_color_set(1);
}
// Write a string at specified location
ncurses_mvaddstr(10, 10, "Hello world! Yellow on blue text!");
// Flush output to screen
ncurses_refresh();
ncurses_end();
?>
Zobacz też:
- ncurses_can_change_color() - Checks if terminal color definitions can be changed
- ncurses_start_color() - Initializes color functionality
ncurses_has_ic
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_has_ic — Check for insert- and delete-capabilities
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Checks whether the terminal has insert and delete capabilities.
Zwracane wartości
Returns TRUE if the terminal has insert/delete-capabilities, FALSE
otherwise.
ncurses_has_il
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_has_il — Check for line insert- and delete-capabilities
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Checks whether the terminal has insert- and delete-line-capabilities.
Zwracane wartości
Returns TRUE if the terminal has insert/delete-line capabilities,
FALSE otherwise.
ncurses_has_key
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_has_key — Check for presence of a function key on terminal keyboard
Opis
$keycode
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
keycode -
ncurses_hide_panel
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_hide_panel — Remove panel from the stack, making it invisible
Opis
$panel
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
panel -
ncurses_hline
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_hline — Draw a horizontal line at current position using an attributed character and max. n characters long
Opis
$charattr
, int $n
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
charattr -
-
n -
ncurses_inch
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_inch — Get character and attribute at current position
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Returns the character from the current position.
Zwracane wartości
Returns the character, as a string.
ncurses_init_color
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_init_color — Define a terminal color
Opis
$color
, int $r
, int $g
, int $b
)Defines or redefines the given color. When this function is called, all occurrences of the given color on the screen, if any, immediately change to the new definition.
Color capabilities must be supported by the terminal and initialized using ncurses_start_color() prior to calling this function. In addition, the terminal must have color changing capabilities; use ncurses_can_change_color() to check for this.
Parametry
-
color -
The identification number of the color to redefine. It may be one of the default color constants.
-
r -
A color value, between 0 and 1000, for the red component.
-
g -
A color value, between 0 and 1000, for the green component.
-
b -
A color value, between 0 and 1000, for the blue component.
Zwracane wartości
Returns -1 if the function was successful, and 0 if ncurses or terminal color capabilities have not been initialized or the terminal does not have color changing capabilities.
Zobacz też:
- ncurses_color_content() - Retrieves RGB components of a color
- ncurses_start_color() - Initializes color functionality
ncurses_init_pair
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_init_pair — Define a color pair
Opis
$pair
, int $fg
, int $bg
)Defines or redefines the given color pair to have the given foreground and background colors. If the color pair was previously initialized, the screen is refreshed and all occurrences of it are changed to reflect the new definition.
Color capabilities must be initialized using ncurses_start_color() before calling this function. The first color pair (color pair 0) is assumed to be white on black by default, but can be changed using ncurses_assume_default_colors().
Parametry
-
pair -
The number of the color pair to define.
-
fg -
The foreground color for the color pair. May be one of the pre-defined colors or one defined by ncurses_init_color() if the terminal has color changing capabilities.
-
bg -
The background color for the color pair. May be one of the pre-defined colors or one defined by ncurses_init_color() if the terminal has color changing capabilities.
Zwracane wartości
Returns -1 if the function was successful, and 0 if ncurses or color support were not initialized.
Notatki
Note that color changing capabilities are not required for defining color pairs of pre-existing colors, but only for changing definitions (red, green, and blue components) of colors themselves per ncurses_init_color().
Przykłady
Przykład #1 Writing a string with a specified color to the screen
<?php
ncurses_init();
// If the terminal supports colors, initialize and set active color
if (ncurses_has_colors()) {
ncurses_start_color();
ncurses_init_pair(1, NCURSES_COLOR_YELLOW, NCURSES_COLOR_BLUE);
ncurses_color_set(1);
}
// Write a string at specified location
ncurses_mvaddstr(10, 10, "Hello world! Yellow on blue text!");
// Flush output to screen
ncurses_refresh();
ncurses_end();
?>
Zobacz też:
- ncurses_pair_content() - Retrieves foreground and background colors of a color pair
- ncurses_start_color() - Initializes color functionality
ncurses_init
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_init — Initialize ncurses
Opis
Initializes the ncurses interface. This function must be used before any other ncurses function call.
Note that ncurses_end() must be called before exiting from the program, or the terminal will not be restored to its proper non-visual mode.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Nie jest zwracana żadna wartość.
ncurses_insch
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_insch — Insert character moving rest of line including character at current position
Opis
$character
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
character -
ncurses_insdelln
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_insdelln — Insert lines before current line scrolling down (negative numbers delete and scroll up)
Opis
$count
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
count -
ncurses_insertln
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_insertln — Insert a line, move rest of screen down
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Inserts a new line above the current line. The bottom line will be lost.
ncurses_insstr
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_insstr — Insert string at current position, moving rest of line right
Opis
$text
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
text -
ncurses_instr
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_instr — Reads string from terminal screen
Opis
&$buffer
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Reads a string from the terminal screen and returns the number of characters read from the current character position until end of line.
Parametry
-
buffer -
The characters. Attributes will be stripped.
Zwracane wartości
Returns the number of characters.
ncurses_isendwin
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_isendwin — Ncurses is in endwin mode, normal screen output may be performed
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Checks if ncurses is in endwin mode.
Zwracane wartości
Returns TRUE, if ncurses_end() has been called
without any subsequent calls to ncurses_wrefresh(),
FALSE otherwise.
Zobacz też:
- ncurses_end() - Stop using ncurses, clean up the screen
- ncurses_wrefresh() - Refresh window on terminal screen
ncurses_keyok
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_keyok — Enable or disable a keycode
Opis
$keycode
, bool $enable
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
keycode -
-
enable -
ncurses_keypad
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_keypad — Turns keypad on or off
Opis
$window
, bool $bf
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
window -
-
bf -
ncurses_killchar
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_killchar — Returns current line kill character
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Returns the current line kill character.
Zwracane wartości
Returns the kill character, as a string.
ncurses_longname
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_longname — Returns terminals description
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Returns a verbose description of the terminal.
Zwracane wartości
Returns the description, as a string truncated to 128 characters.
On errors, returns NULL.
ncurses_meta
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_meta — Enables/Disable 8-bit meta key information
Opis
$window
, bool $8bit
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
window -
-
8bit -
ncurses_mouse_trafo
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mouse_trafo — Transforms coordinates
Opis
&$y
, int &$x
, bool $toscreen
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
y -
-
x -
-
toscreen -
ncurses_mouseinterval
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mouseinterval — Set timeout for mouse button clicks
Opis
$milliseconds
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
milliseconds -
ncurses_mousemask
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mousemask — Sets mouse options
Opis
$newmask
, int &$oldmask
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Sets mouse events to be reported. By default no mouse events will be reported.
Mouse events are represented by NCURSES_KEY_MOUSE in the
ncurses_wgetch() input stream. To read the event data
and pop the event of queue, call ncurses_getmouse().
Parametry
-
newmask -
Mouse mask options can be set with the following predefined constants:
NCURSES_BUTTON1_PRESSED
NCURSES_BUTTON1_RELEASED
NCURSES_BUTTON1_CLICKED
NCURSES_BUTTON1_DOUBLE_CLICKED
NCURSES_BUTTON1_TRIPLE_CLICKED
NCURSES_BUTTON2_PRESSED
NCURSES_BUTTON2_RELEASED
NCURSES_BUTTON2_CLICKED
NCURSES_BUTTON2_DOUBLE_CLICKED
NCURSES_BUTTON2_TRIPLE_CLICKED
NCURSES_BUTTON3_PRESSED
NCURSES_BUTTON3_RELEASED
NCURSES_BUTTON3_CLICKED
NCURSES_BUTTON3_DOUBLE_CLICKED
NCURSES_BUTTON3_TRIPLE_CLICKED
NCURSES_BUTTON4_PRESSED
NCURSES_BUTTON4_RELEASED
NCURSES_BUTTON4_CLICKED
NCURSES_BUTTON4_DOUBLE_CLICKED
NCURSES_BUTTON4_TRIPLE_CLICKED
NCURSES_BUTTON_SHIFT>
NCURSES_BUTTON_CTRL
NCURSES_BUTTON_ALT
NCURSES_ALL_MOUSE_EVENTS
NCURSES_REPORT_MOUSE_POSITION
As a side effect, setting a zero mousemask in
newmaskturns off the mouse pointer. Setting a non zero value turns mouse pointer on. -
oldmask -
This will be set to the previous value of the mouse event mask.
Zwracane wartości
Returns a mask to indicated which of the in parameter
newmask specified mouse events can be reported. On
complete failure, it returns 0.
Przykłady
Przykład #1 ncurses_mousemask() example
<?php
$newmask = NCURSES_BUTTON1_CLICKED + NCURSES_BUTTON1_RELEASED;
$mask = ncurses_mousemask($newmask, $oldmask);
if ($mask & $newmask){
printf("All specified mouse options will be supported\n");
}
?>
Zobacz też:
- ncurses_getch() - Read a character from keyboard
- ncurses_getmouse() - Reads mouse event
- ncurses_ungetmouse() - Pushes mouse event to queue
ncurses_move_panel
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_move_panel — Moves a panel so that its upper-left corner is at [startx, starty]
Opis
$panel
, int $startx
, int $starty
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
panel -
-
startx -
-
starty -
ncurses_move
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_move — Move output position
Opis
$y
, int $x
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
y -
-
x -
ncurses_mvaddch
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mvaddch — Move current position and add character
Opis
$y
, int $x
, int $c
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
y -
-
x -
-
c -
ncurses_mvaddchnstr
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mvaddchnstr — Move position and add attributed string with specified length
Opis
$y
, int $x
, string $s
, int $n
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
y -
-
x -
-
s -
-
n -
ncurses_mvaddchstr
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mvaddchstr — Move position and add attributed string
Opis
$y
, int $x
, string $s
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
y -
-
x -
-
s -
ncurses_mvaddnstr
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mvaddnstr — Move position and add string with specified length
Opis
$y
, int $x
, string $s
, int $n
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
y -
-
x -
-
s -
-
n -
ncurses_mvaddstr
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mvaddstr — Move position and add string
Opis
$y
, int $x
, string $s
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
y -
-
x -
-
s -
ncurses_mvcur
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mvcur — Move cursor immediately
Opis
$old_y
, int $old_x
, int $new_y
, int $new_x
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
old_y -
-
old_x -
-
new_y -
-
new_x -
ncurses_mvdelch
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mvdelch — Move position and delete character, shift rest of line left
Opis
$y
, int $x
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
y -
-
x -
ncurses_mvgetch
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mvgetch — Move position and get character at new position
Opis
$y
, int $x
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
y -
-
x -
ncurses_mvhline
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mvhline — Set new position and draw a horizontal line using an attributed character and max. n characters long
Opis
$y
, int $x
, int $attrchar
, int $n
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
y -
-
x -
-
attrchar -
-
n -
ncurses_mvinch
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mvinch — Move position and get attributed character at new position
Opis
$y
, int $x
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
y -
-
x -
ncurses_mvvline
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mvvline — Set new position and draw a vertical line using an attributed character and max. n characters long
Opis
$y
, int $x
, int $attrchar
, int $n
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
y -
-
x -
-
attrchar -
-
n -
ncurses_mvwaddstr
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mvwaddstr — Add string at new position in window
Opis
$window
, int $y
, int $x
, string $text
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
window -
-
y -
-
x -
-
text -
ncurses_napms
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_napms — Sleep
Opis
$milliseconds
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
milliseconds -
ncurses_new_panel
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_new_panel — Create a new panel and associate it with window
Opis
$window
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
window -
ncurses_newpad
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_newpad — Creates a new pad (window)
Opis
$rows
, int $cols
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
rows -
-
cols -
ncurses_newwin
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_newwin — Create a new window
Opis
$rows
, int $cols
, int $y
, int $x
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Creates a new window to draw elements in.
When creating additional windows, remember to use ncurses_getmaxyx() to check for available space, as terminal size is individual and may vary.
Parametry
-
rows -
Number of rows
-
cols -
Number of columns
-
y -
y-coordinate of the origin
-
x -
x-coordinate of the origin
Zwracane wartości
Returns a resource ID for the new window.
ncurses_nl
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_nl — Translate newline and carriage return / line feed
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
ncurses_nocbreak
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_nocbreak — Switch terminal to cooked mode
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Returns terminal to normal (cooked) mode. Initially the terminal may or may not in cbreak mode as the mode is inherited. Therefore a program should call ncurses_cbreak() and ncurses_nocbreak() explicitly.
Zwracane wartości
Returns TRUE if any error occurred, otherwise FALSE.
ncurses_noecho
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_noecho — Switch off keyboard input echo
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Prevents echoing of user typed characters.
Zwracane wartości
Returns TRUE if any error occurred, FALSE otherwise.
Zobacz też:
- ncurses_echo() - Activate keyboard input echo
- ncurses_getch() - Read a character from keyboard
ncurses_nonl
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_nonl — Do not translate newline and carriage return / line feed
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
ncurses_noqiflush
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_noqiflush — Do not flush on signal characters
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
ncurses_noraw
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_noraw — Switch terminal out of raw mode
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Switches the terminal out of raw mode. Raw mode is similar to cbreak mode, in that characters typed are immediately passed through to the user program. The differences that are that in raw mode, the interrupt, quit, suspend and flow control characters are all passed through uninterpreted, instead of generating a signal.
Zwracane wartości
Returns TRUE if any error occurred, otherwise FALSE.
Zobacz też:
- ncurses_raw() - Switch terminal into raw mode
- ncurses_cbreak() - Switch of input buffering
- ncurses_nocbreak() - Switch terminal to cooked mode
ncurses_pair_content
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_pair_content — Retrieves foreground and background colors of a color pair
Opis
$pair
, int &$f
, int &$b
)Retrieves the foreground and background colors that constitute the given color pair. Terminal color capabilities must be initialized with ncurses_start_color() prior to calling this function.
Parametry
-
pair -
The number of the color pair to retrieve information for.
-
f -
A reference to which to return the foreground color of the color pair. The information returned will be a color number referring to one of the pre-defined colors or a color defined previously by ncurses_init_color() if the terminal supports color changing.
-
b -
A reference to which to return the background color of the color pair. The information returned will be a color number referring to one of the pre-defined colors or a color defined previously by ncurses_init_color() if the terminal supports color changing.
Zwracane wartości
Returns -1 if the function was successful, and 0 if ncurses or terminal color capabilities have not been initialized.
Zobacz też:
- ncurses_init_pair() - Define a color pair
- ncurses_start_color() - Initializes color functionality
ncurses_panel_above
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_panel_above — Returns the panel above panel
Opis
$panel
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
panel -
Zwracane wartości
If panel is null, returns the bottom panel in the stack.
ncurses_panel_below
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_panel_below — Returns the panel below panel
Opis
$panel
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
panel -
Parametry
If panel is null, returns the top panel in the stack.
ncurses_panel_window
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_panel_window — Returns the window associated with panel
Opis
$panel
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
panel -
ncurses_pnoutrefresh
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_pnoutrefresh — Copies a region from a pad into the virtual screen
Opis
$pad
, int $pminrow
, int $pmincol
, int $sminrow
, int $smincol
, int $smaxrow
, int $smaxcol
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
pad -
-
pminrow -
-
pmincol -
-
sminrow -
-
smincol -
-
smaxrow -
-
smaxcol -
ncurses_prefresh
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_prefresh — Copies a region from a pad into the virtual screen
Opis
$pad
, int $pminrow
, int $pmincol
, int $sminrow
, int $smincol
, int $smaxrow
, int $smaxcol
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
pad -
-
pminrow -
-
pmincol -
-
sminrow -
-
smincol -
-
smaxrow -
-
smaxcol -
ncurses_putp
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_putp — Apply padding information to the string and output it
Opis
$text
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
text -
ncurses_qiflush
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_qiflush — Flush on signal characters
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
ncurses_raw
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_raw — Switch terminal into raw mode
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Places the terminal in raw mode. Raw mode is similar to cbreak mode, in that characters typed are immediately passed through to the user program. The differences that are that in raw mode, the interrupt, quit, suspend and flow control characters are all passed through uninterpreted, instead of generating a signal.
Zwracane wartości
Returns TRUE if any error occurred, otherwise FALSE.
Zobacz też:
- ncurses_noraw() - Switch terminal out of raw mode
- ncurses_cbreak() - Switch of input buffering
- ncurses_nocbreak() - Switch terminal to cooked mode
ncurses_refresh
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_refresh — Refresh screen
Opis
$ch
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
ch -
ncurses_replace_panel
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_replace_panel — Replaces the window associated with panel
Opis
$panel
, resource $window
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
panel -
-
window -
ncurses_reset_prog_mode
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_reset_prog_mode — Resets the prog mode saved by def_prog_mode
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
ncurses_reset_shell_mode
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_reset_shell_mode — Resets the shell mode saved by def_shell_mode
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
ncurses_resetty
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_resetty — Restores saved terminal state
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Restores the terminal state, which was previously saved by calling ncurses_savetty().
Zwracane wartości
Always returns FALSE.
ncurses_savetty
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_savetty — Saves terminal state
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Saves the current terminal state. The saved terminal state can be restored with ncurses_resetty().
Zwracane wartości
Always returns FALSE.
ncurses_scr_dump
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_scr_dump — Dump screen content to file
Opis
$filename
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
filename -
ncurses_scr_init
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_scr_init — Initialize screen from file dump
Opis
$filename
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
filename -
ncurses_scr_restore
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_scr_restore — Restore screen from file dump
Opis
$filename
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
filename -
ncurses_scr_set
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_scr_set — Inherit screen from file dump
Opis
$filename
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
filename -
ncurses_scrl
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_scrl — Scroll window content up or down without changing current position
Opis
$count
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
count -
ncurses_show_panel
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_show_panel — Places an invisible panel on top of the stack, making it visible
Opis
$panel
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
panel -
ncurses_slk_attr
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_slk_attr — Returns current soft label key attribute
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Returns the current soft label key attribute.
Zwracane wartości
The attribute, as an integer.
ncurses_slk_attroff
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_slk_attroff — Turn off the given attributes for soft function-key labels
Opis
$intarg
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
intarg -
ncurses_slk_attron
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_slk_attron — Turn on the given attributes for soft function-key labels
Opis
$intarg
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
intarg -
ncurses_slk_attrset
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_slk_attrset — Set given attributes for soft function-key labels
Opis
$intarg
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
intarg -
ncurses_slk_clear
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_slk_clear — Clears soft labels from screen
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
The function ncurses_slk_clear() clears soft label keys from screen.
Zwracane wartości
Returns TRUE on errors, FALSE otherwise.
ncurses_slk_color
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_slk_color — Sets color for soft label keys
Opis
$intarg
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
intarg -
ncurses_slk_init
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_slk_init — Initializes soft label key functions
Opis
$format
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Initializes soft label key functions
This function must be called before ncurses_init() or ncurses_newwin() is called.
Parametry
-
format -
If ncurses_init() eventually uses a line from stdscr to emulate the soft labels, then this parameter determines how the labels are arranged of the screen.
0 indicates a 3-2-3 arrangement of the labels, 1 indicates a 4-4 arrangement and 2 indicates the PC like 4-4-4 mode, but in addition an index line will be created.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
ncurses_slk_noutrefresh
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_slk_noutrefresh — Copies soft label keys to virtual screen
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
ncurses_slk_refresh
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_slk_refresh — Copies soft label keys to screen
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Copies soft label keys from virtual screen to physical screen.
ncurses_slk_restore
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_slk_restore — Restores soft label keys
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Restores the soft label keys after ncurses_slk_clear() has been performed.
ncurses_slk_set
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_slk_set — Sets function key labels
Opis
$labelnr
, string $label
, int $format
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
labelnr -
-
label -
-
format -
ncurses_slk_touch
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_slk_touch — Forces output when ncurses_slk_noutrefresh is performed
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Forces all the soft labels to be output the next time a ncurses_slk_noutrefresh() is performed.
ncurses_standend
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_standend — Stop using 'standout' attribute
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
ncurses_standout
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_standout — Start using 'standout' attribute
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
ncurses_start_color
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_start_color — Initializes color functionality
Opis
Initializes color functionality in ncurses. This function must be called before any color manipulation functions are called and after ncurses_init() is called. It is good practice to call this function right after ncurses_init().
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns 0 on success, or -1 if the color table could not be allocated or ncurses was not initialized.
Przykłady
Przykład #1 Writing a string with a specified color to the screen
<?php
ncurses_init();
// If the terminal supports colors, initialize and set active color
if (ncurses_has_colors()) {
ncurses_start_color();
ncurses_init_pair(1, NCURSES_COLOR_YELLOW, NCURSES_COLOR_BLUE);
ncurses_color_set(1);
}
// Write a string at specified location
ncurses_mvaddstr(10, 10, "Hello world! Yellow on blue text!");
// Flush output to screen
ncurses_refresh();
ncurses_end();
?>
Zobacz też:
- ncurses_can_change_color() - Checks if terminal color definitions can be changed
- ncurses_has_colors() - Checks if terminal has color capabilities
ncurses_termattrs
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_termattrs — Returns a logical OR of all attribute flags supported by terminal
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
ncurses_termname
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_termname — Returns terminals (short)-name
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Returns terminals shortname.
Zwracane wartości
Returns the shortname of the terminal, truncated to 14 characters.
On errors, returns NULL.
ncurses_timeout
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_timeout — Set timeout for special key sequences
Opis
$millisec
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
millisec -
ncurses_top_panel
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_top_panel — Moves a visible panel to the top of the stack
Opis
$panel
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
panel -
ncurses_typeahead
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_typeahead — Specify different filedescriptor for typeahead checking
Opis
$fd
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
fd -
ncurses_ungetch
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_ungetch — Put a character back into the input stream
Opis
$keycode
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
keycode -
ncurses_ungetmouse
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_ungetmouse — Pushes mouse event to queue
Opis
$mevent
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Pushes a KEY_MOUSE event onto the unput queue and associates with this
event the given state sata and screen-relative character cell coordinates,
specified in mevent.
Parametry
-
mevent -
An associative array specifying the event options:
-
"id" : Id to distinguish multiple devices
-
"x" : screen relative x-position in character cells
-
"y" : screen relative y-position in character cells
-
"z" : currently not supported
-
"mmask" : Mouse action
-
Zwracane wartości
Returns FALSE on success, TRUE otherwise.
ncurses_update_panels
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_update_panels — Refreshes the virtual screen to reflect the relations between panels in the stack
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
ncurses_use_default_colors
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_use_default_colors — Assign terminal default colors to color id -1
Opis
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
ncurses_use_env
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_use_env — Control use of environment information about terminal size
Opis
$flag
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
flag -
ncurses_use_extended_names
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_use_extended_names — Control use of extended names in terminfo descriptions
Opis
$flag
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
flag -
ncurses_vidattr
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_vidattr — Display the string on the terminal in the video attribute mode
Opis
$intarg
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
intarg -
ncurses_vline
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_vline — Draw a vertical line at current position using an attributed character and max. n characters long
Opis
$charattr
, int $n
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
charattr -
-
n -
ncurses_waddch
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_waddch — Adds character at current position in a window and advance cursor
Opis
$window
, int $ch
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
window -
-
ch -
ncurses_waddstr
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_waddstr — Outputs text at current postion in window
Opis
$window
, string $str
[, int $n
] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
window -
-
str -
-
n -
ncurses_wattroff
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_wattroff — Turns off attributes for a window
Opis
$window
, int $attrs
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
window -
-
attrs -
ncurses_wattron
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_wattron — Turns on attributes for a window
Opis
$window
, int $attrs
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
window -
-
attrs -
ncurses_wattrset
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_wattrset — Set the attributes for a window
Opis
$window
, int $attrs
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
window -
-
attrs -
ncurses_wborder
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_wborder — Draws a border around the window using attributed characters
Opis
$window
, int $left
, int $right
, int $top
, int $bottom
, int $tl_corner
, int $tr_corner
, int $bl_corner
, int $br_corner
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Draws the specified lines and corners around the passed
window.
Use ncurses_border() for borders around the main window.
Parametry
Each parameter expects 0 to draw a line and 1 to skip it.
-
window -
The window on which we operate
-
left -
-
right -
-
top -
-
bottom -
-
tl_corner -
Top left corner
-
tr_corner -
Top right corner
-
bl_corner -
Bottom left corner
-
br_corner -
Bottom right corner
ncurses_wclear
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_wclear — Clears window
Opis
$window
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
window -
ncurses_wcolor_set
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_wcolor_set — Sets windows color pairings
Opis
$window
, int $color_pair
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
window -
-
color_pair -
ncurses_werase
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_werase — Erase window contents
Opis
$window
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
window -
ncurses_wgetch
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_wgetch — Reads a character from keyboard (window)
Opis
$window
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
window -
ncurses_whline
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_whline — Draws a horizontal line in a window at current position using an attributed character and max. n characters long
Opis
$window
, int $charattr
, int $n
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
window -
-
charattr -
-
n -
ncurses_wmouse_trafo
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_wmouse_trafo — Transforms window/stdscr coordinates
Opis
$window
, int &$y
, int &$x
, bool $toscreen
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
window -
-
x -
-
y -
-
toscreen -
ncurses_wmove
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_wmove — Moves windows output position
Opis
$window
, int $y
, int $x
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
window -
-
y -
-
x -
ncurses_wnoutrefresh
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_wnoutrefresh — Copies window to virtual screen
Opis
$window
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
window -
ncurses_wrefresh
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_wrefresh — Refresh window on terminal screen
Opis
$window
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
window -
ncurses_wstandend
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_wstandend — End standout mode for a window
Opis
$window
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
window -
ncurses_wstandout
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_wstandout — Enter standout mode for a window
Opis
$window
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
window -
ncurses_wvline
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_wvline — Draws a vertical line in a window at current position using an attributed character and max. n characters long
Opis
$window
, int $charattr
, int $n
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
window -
-
charattr -
-
n -
Spis treści
- ncurses_addch — Add character at current position and advance cursor
- ncurses_addchnstr — Add attributed string with specified length at current position
- ncurses_addchstr — Add attributed string at current position
- ncurses_addnstr — Add string with specified length at current position
- ncurses_addstr — Output text at current position
- ncurses_assume_default_colors — Define default colors for color 0
- ncurses_attroff — Turn off the given attributes
- ncurses_attron — Turn on the given attributes
- ncurses_attrset — Set given attributes
- ncurses_baudrate — Returns baudrate of terminal
- ncurses_beep — Let the terminal beep
- ncurses_bkgd — Set background property for terminal screen
- ncurses_bkgdset — Control screen background
- ncurses_border — Draw a border around the screen using attributed characters
- ncurses_bottom_panel — Moves a visible panel to the bottom of the stack
- ncurses_can_change_color — Checks if terminal color definitions can be changed
- ncurses_cbreak — Switch of input buffering
- ncurses_clear — Clear screen
- ncurses_clrtobot — Clear screen from current position to bottom
- ncurses_clrtoeol — Clear screen from current position to end of line
- ncurses_color_content — Retrieves RGB components of a color
- ncurses_color_set — Set active foreground and background colors
- ncurses_curs_set — Set cursor state
- ncurses_def_prog_mode — Saves terminals (program) mode
- ncurses_def_shell_mode — Saves terminals (shell) mode
- ncurses_define_key — Define a keycode
- ncurses_del_panel — Remove panel from the stack and delete it (but not the associated window)
- ncurses_delay_output — Delay output on terminal using padding characters
- ncurses_delch — Delete character at current position, move rest of line left
- ncurses_deleteln — Delete line at current position, move rest of screen up
- ncurses_delwin — Delete a ncurses window
- ncurses_doupdate — Write all prepared refreshes to terminal
- ncurses_echo — Activate keyboard input echo
- ncurses_echochar — Single character output including refresh
- ncurses_end — Stop using ncurses, clean up the screen
- ncurses_erase — Erase terminal screen
- ncurses_erasechar — Returns current erase character
- ncurses_filter — Set LINES for iniscr() and newterm() to 1
- ncurses_flash — Flash terminal screen (visual bell)
- ncurses_flushinp — Flush keyboard input buffer
- ncurses_getch — Read a character from keyboard
- ncurses_getmaxyx — Returns the size of a window
- ncurses_getmouse — Reads mouse event
- ncurses_getyx — Returns the current cursor position for a window
- ncurses_halfdelay — Put terminal into halfdelay mode
- ncurses_has_colors — Checks if terminal has color capabilities
- ncurses_has_ic — Check for insert- and delete-capabilities
- ncurses_has_il — Check for line insert- and delete-capabilities
- ncurses_has_key — Check for presence of a function key on terminal keyboard
- ncurses_hide_panel — Remove panel from the stack, making it invisible
- ncurses_hline — Draw a horizontal line at current position using an attributed character and max. n characters long
- ncurses_inch — Get character and attribute at current position
- ncurses_init_color — Define a terminal color
- ncurses_init_pair — Define a color pair
- ncurses_init — Initialize ncurses
- ncurses_insch — Insert character moving rest of line including character at current position
- ncurses_insdelln — Insert lines before current line scrolling down (negative numbers delete and scroll up)
- ncurses_insertln — Insert a line, move rest of screen down
- ncurses_insstr — Insert string at current position, moving rest of line right
- ncurses_instr — Reads string from terminal screen
- ncurses_isendwin — Ncurses is in endwin mode, normal screen output may be performed
- ncurses_keyok — Enable or disable a keycode
- ncurses_keypad — Turns keypad on or off
- ncurses_killchar — Returns current line kill character
- ncurses_longname — Returns terminals description
- ncurses_meta — Enables/Disable 8-bit meta key information
- ncurses_mouse_trafo — Transforms coordinates
- ncurses_mouseinterval — Set timeout for mouse button clicks
- ncurses_mousemask — Sets mouse options
- ncurses_move_panel — Moves a panel so that its upper-left corner is at [startx, starty]
- ncurses_move — Move output position
- ncurses_mvaddch — Move current position and add character
- ncurses_mvaddchnstr — Move position and add attributed string with specified length
- ncurses_mvaddchstr — Move position and add attributed string
- ncurses_mvaddnstr — Move position and add string with specified length
- ncurses_mvaddstr — Move position and add string
- ncurses_mvcur — Move cursor immediately
- ncurses_mvdelch — Move position and delete character, shift rest of line left
- ncurses_mvgetch — Move position and get character at new position
- ncurses_mvhline — Set new position and draw a horizontal line using an attributed character and max. n characters long
- ncurses_mvinch — Move position and get attributed character at new position
- ncurses_mvvline — Set new position and draw a vertical line using an attributed character and max. n characters long
- ncurses_mvwaddstr — Add string at new position in window
- ncurses_napms — Sleep
- ncurses_new_panel — Create a new panel and associate it with window
- ncurses_newpad — Creates a new pad (window)
- ncurses_newwin — Create a new window
- ncurses_nl — Translate newline and carriage return / line feed
- ncurses_nocbreak — Switch terminal to cooked mode
- ncurses_noecho — Switch off keyboard input echo
- ncurses_nonl — Do not translate newline and carriage return / line feed
- ncurses_noqiflush — Do not flush on signal characters
- ncurses_noraw — Switch terminal out of raw mode
- ncurses_pair_content — Retrieves foreground and background colors of a color pair
- ncurses_panel_above — Returns the panel above panel
- ncurses_panel_below — Returns the panel below panel
- ncurses_panel_window — Returns the window associated with panel
- ncurses_pnoutrefresh — Copies a region from a pad into the virtual screen
- ncurses_prefresh — Copies a region from a pad into the virtual screen
- ncurses_putp — Apply padding information to the string and output it
- ncurses_qiflush — Flush on signal characters
- ncurses_raw — Switch terminal into raw mode
- ncurses_refresh — Refresh screen
- ncurses_replace_panel — Replaces the window associated with panel
- ncurses_reset_prog_mode — Resets the prog mode saved by def_prog_mode
- ncurses_reset_shell_mode — Resets the shell mode saved by def_shell_mode
- ncurses_resetty — Restores saved terminal state
- ncurses_savetty — Saves terminal state
- ncurses_scr_dump — Dump screen content to file
- ncurses_scr_init — Initialize screen from file dump
- ncurses_scr_restore — Restore screen from file dump
- ncurses_scr_set — Inherit screen from file dump
- ncurses_scrl — Scroll window content up or down without changing current position
- ncurses_show_panel — Places an invisible panel on top of the stack, making it visible
- ncurses_slk_attr — Returns current soft label key attribute
- ncurses_slk_attroff — Turn off the given attributes for soft function-key labels
- ncurses_slk_attron — Turn on the given attributes for soft function-key labels
- ncurses_slk_attrset — Set given attributes for soft function-key labels
- ncurses_slk_clear — Clears soft labels from screen
- ncurses_slk_color — Sets color for soft label keys
- ncurses_slk_init — Initializes soft label key functions
- ncurses_slk_noutrefresh — Copies soft label keys to virtual screen
- ncurses_slk_refresh — Copies soft label keys to screen
- ncurses_slk_restore — Restores soft label keys
- ncurses_slk_set — Sets function key labels
- ncurses_slk_touch — Forces output when ncurses_slk_noutrefresh is performed
- ncurses_standend — Stop using 'standout' attribute
- ncurses_standout — Start using 'standout' attribute
- ncurses_start_color — Initializes color functionality
- ncurses_termattrs — Returns a logical OR of all attribute flags supported by terminal
- ncurses_termname — Returns terminals (short)-name
- ncurses_timeout — Set timeout for special key sequences
- ncurses_top_panel — Moves a visible panel to the top of the stack
- ncurses_typeahead — Specify different filedescriptor for typeahead checking
- ncurses_ungetch — Put a character back into the input stream
- ncurses_ungetmouse — Pushes mouse event to queue
- ncurses_update_panels — Refreshes the virtual screen to reflect the relations between panels in the stack
- ncurses_use_default_colors — Assign terminal default colors to color id -1
- ncurses_use_env — Control use of environment information about terminal size
- ncurses_use_extended_names — Control use of extended names in terminfo descriptions
- ncurses_vidattr — Display the string on the terminal in the video attribute mode
- ncurses_vline — Draw a vertical line at current position using an attributed character and max. n characters long
- ncurses_waddch — Adds character at current position in a window and advance cursor
- ncurses_waddstr — Outputs text at current postion in window
- ncurses_wattroff — Turns off attributes for a window
- ncurses_wattron — Turns on attributes for a window
- ncurses_wattrset — Set the attributes for a window
- ncurses_wborder — Draws a border around the window using attributed characters
- ncurses_wclear — Clears window
- ncurses_wcolor_set — Sets windows color pairings
- ncurses_werase — Erase window contents
- ncurses_wgetch — Reads a character from keyboard (window)
- ncurses_whline — Draws a horizontal line in a window at current position using an attributed character and max. n characters long
- ncurses_wmouse_trafo — Transforms window/stdscr coordinates
- ncurses_wmove — Moves windows output position
- ncurses_wnoutrefresh — Copies window to virtual screen
- ncurses_wrefresh — Refresh window on terminal screen
- ncurses_wstandend — End standout mode for a window
- ncurses_wstandout — Enter standout mode for a window
- ncurses_wvline — Draws a vertical line in a window at current position using an attributed character and max. n characters long
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Ncurses Funkcje
- ncurses_addch — Add character at current position and advance cursor
- ncurses_addchnstr — Add attributed string with specified length at current position
- ncurses_addchstr — Add attributed string at current position
- ncurses_addnstr — Add string with specified length at current position
- ncurses_addstr — Output text at current position
- ncurses_assume_default_colors — Define default colors for color 0
- ncurses_attroff — Turn off the given attributes
- ncurses_attron — Turn on the given attributes
- ncurses_attrset — Set given attributes
- ncurses_baudrate — Returns baudrate of terminal
- ncurses_beep — Let the terminal beep
- ncurses_bkgd — Set background property for terminal screen
- ncurses_bkgdset — Control screen background
- ncurses_border — Draw a border around the screen using attributed characters
- ncurses_bottom_panel — Moves a visible panel to the bottom of the stack
- ncurses_can_change_color — Checks if terminal color definitions can be changed
- ncurses_cbreak — Switch of input buffering
- ncurses_clear — Clear screen
- ncurses_clrtobot — Clear screen from current position to bottom
- ncurses_clrtoeol — Clear screen from current position to end of line
- ncurses_color_content — Retrieves RGB components of a color
- ncurses_color_set — Set active foreground and background colors
- ncurses_curs_set — Set cursor state
- ncurses_def_prog_mode — Saves terminals (program) mode
- ncurses_def_shell_mode — Saves terminals (shell) mode
- ncurses_define_key — Define a keycode
- ncurses_del_panel — Remove panel from the stack and delete it (but not the associated window)
- ncurses_delay_output — Delay output on terminal using padding characters
- ncurses_delch — Delete character at current position, move rest of line left
- ncurses_deleteln — Delete line at current position, move rest of screen up
- ncurses_delwin — Delete a ncurses window
- ncurses_doupdate — Write all prepared refreshes to terminal
- ncurses_echo — Activate keyboard input echo
- ncurses_echochar — Single character output including refresh
- ncurses_end — Stop using ncurses, clean up the screen
- ncurses_erase — Erase terminal screen
- ncurses_erasechar — Returns current erase character
- ncurses_filter — Set LINES for iniscr() and newterm() to 1
- ncurses_flash — Flash terminal screen (visual bell)
- ncurses_flushinp — Flush keyboard input buffer
- ncurses_getch — Read a character from keyboard
- ncurses_getmaxyx — Returns the size of a window
- ncurses_getmouse — Reads mouse event
- ncurses_getyx — Returns the current cursor position for a window
- ncurses_halfdelay — Put terminal into halfdelay mode
- ncurses_has_colors — Checks if terminal has color capabilities
- ncurses_has_ic — Check for insert- and delete-capabilities
- ncurses_has_il — Check for line insert- and delete-capabilities
- ncurses_has_key — Check for presence of a function key on terminal keyboard
- ncurses_hide_panel — Remove panel from the stack, making it invisible
- ncurses_hline — Draw a horizontal line at current position using an attributed character and max. n characters long
- ncurses_inch — Get character and attribute at current position
- ncurses_init_color — Define a terminal color
- ncurses_init_pair — Define a color pair
- ncurses_init — Initialize ncurses
- ncurses_insch — Insert character moving rest of line including character at current position
- ncurses_insdelln — Insert lines before current line scrolling down (negative numbers delete and scroll up)
- ncurses_insertln — Insert a line, move rest of screen down
- ncurses_insstr — Insert string at current position, moving rest of line right
- ncurses_instr — Reads string from terminal screen
- ncurses_isendwin — Ncurses is in endwin mode, normal screen output may be performed
- ncurses_keyok — Enable or disable a keycode
- ncurses_keypad — Turns keypad on or off
- ncurses_killchar — Returns current line kill character
- ncurses_longname — Returns terminals description
- ncurses_meta — Enables/Disable 8-bit meta key information
- ncurses_mouse_trafo — Transforms coordinates
- ncurses_mouseinterval — Set timeout for mouse button clicks
- ncurses_mousemask — Sets mouse options
- ncurses_move_panel — Moves a panel so that its upper-left corner is at [startx, starty]
- ncurses_move — Move output position
- ncurses_mvaddch — Move current position and add character
- ncurses_mvaddchnstr — Move position and add attributed string with specified length
- ncurses_mvaddchstr — Move position and add attributed string
- ncurses_mvaddnstr — Move position and add string with specified length
- ncurses_mvaddstr — Move position and add string
- ncurses_mvcur — Move cursor immediately
- ncurses_mvdelch — Move position and delete character, shift rest of line left
- ncurses_mvgetch — Move position and get character at new position
- ncurses_mvhline — Set new position and draw a horizontal line using an attributed character and max. n characters long
- ncurses_mvinch — Move position and get attributed character at new position
- ncurses_mvvline — Set new position and draw a vertical line using an attributed character and max. n characters long
- ncurses_mvwaddstr — Add string at new position in window
- ncurses_napms — Sleep
- ncurses_new_panel — Create a new panel and associate it with window
- ncurses_newpad — Creates a new pad (window)
- ncurses_newwin — Create a new window
- ncurses_nl — Translate newline and carriage return / line feed
- ncurses_nocbreak — Switch terminal to cooked mode
- ncurses_noecho — Switch off keyboard input echo
- ncurses_nonl — Do not translate newline and carriage return / line feed
- ncurses_noqiflush — Do not flush on signal characters
- ncurses_noraw — Switch terminal out of raw mode
- ncurses_pair_content — Retrieves foreground and background colors of a color pair
- ncurses_panel_above — Returns the panel above panel
- ncurses_panel_below — Returns the panel below panel
- ncurses_panel_window — Returns the window associated with panel
- ncurses_pnoutrefresh — Copies a region from a pad into the virtual screen
- ncurses_prefresh — Copies a region from a pad into the virtual screen
- ncurses_putp — Apply padding information to the string and output it
- ncurses_qiflush — Flush on signal characters
- ncurses_raw — Switch terminal into raw mode
- ncurses_refresh — Refresh screen
- ncurses_replace_panel — Replaces the window associated with panel
- ncurses_reset_prog_mode — Resets the prog mode saved by def_prog_mode
- ncurses_reset_shell_mode — Resets the shell mode saved by def_shell_mode
- ncurses_resetty — Restores saved terminal state
- ncurses_savetty — Saves terminal state
- ncurses_scr_dump — Dump screen content to file
- ncurses_scr_init — Initialize screen from file dump
- ncurses_scr_restore — Restore screen from file dump
- ncurses_scr_set — Inherit screen from file dump
- ncurses_scrl — Scroll window content up or down without changing current position
- ncurses_show_panel — Places an invisible panel on top of the stack, making it visible
- ncurses_slk_attr — Returns current soft label key attribute
- ncurses_slk_attroff — Turn off the given attributes for soft function-key labels
- ncurses_slk_attron — Turn on the given attributes for soft function-key labels
- ncurses_slk_attrset — Set given attributes for soft function-key labels
- ncurses_slk_clear — Clears soft labels from screen
- ncurses_slk_color — Sets color for soft label keys
- ncurses_slk_init — Initializes soft label key functions
- ncurses_slk_noutrefresh — Copies soft label keys to virtual screen
- ncurses_slk_refresh — Copies soft label keys to screen
- ncurses_slk_restore — Restores soft label keys
- ncurses_slk_set — Sets function key labels
- ncurses_slk_touch — Forces output when ncurses_slk_noutrefresh is performed
- ncurses_standend — Stop using 'standout' attribute
- ncurses_standout — Start using 'standout' attribute
- ncurses_start_color — Initializes color functionality
- ncurses_termattrs — Returns a logical OR of all attribute flags supported by terminal
- ncurses_termname — Returns terminals (short)-name
- ncurses_timeout — Set timeout for special key sequences
- ncurses_top_panel — Moves a visible panel to the top of the stack
- ncurses_typeahead — Specify different filedescriptor for typeahead checking
- ncurses_ungetch — Put a character back into the input stream
- ncurses_ungetmouse — Pushes mouse event to queue
- ncurses_update_panels — Refreshes the virtual screen to reflect the relations between panels in the stack
- ncurses_use_default_colors — Assign terminal default colors to color id -1
- ncurses_use_env — Control use of environment information about terminal size
- ncurses_use_extended_names — Control use of extended names in terminfo descriptions
- ncurses_vidattr — Display the string on the terminal in the video attribute mode
- ncurses_vline — Draw a vertical line at current position using an attributed character and max. n characters long
- ncurses_waddch — Adds character at current position in a window and advance cursor
- ncurses_waddstr — Outputs text at current postion in window
- ncurses_wattroff — Turns off attributes for a window
- ncurses_wattron — Turns on attributes for a window
- ncurses_wattrset — Set the attributes for a window
- ncurses_wborder — Draws a border around the window using attributed characters
- ncurses_wclear — Clears window
- ncurses_wcolor_set — Sets windows color pairings
- ncurses_werase — Erase window contents
- ncurses_wgetch — Reads a character from keyboard (window)
- ncurses_whline — Draws a horizontal line in a window at current position using an attributed character and max. n characters long
- ncurses_wmouse_trafo — Transforms window/stdscr coordinates
- ncurses_wmove — Moves windows output position
- ncurses_wnoutrefresh — Copies window to virtual screen
- ncurses_wrefresh — Refresh window on terminal screen
- ncurses_wstandend — End standout mode for a window
- ncurses_wstandout — Enter standout mode for a window
- ncurses_wvline — Draws a vertical line in a window at current position using an attributed character and max. n characters long
Newt
Wstęp
This is a PHP language extension for RedHat Newt library, a terminal-based window and widget library for writing applications with user friendly interface. Once this extension is enabled in PHP it will provide the use of Newt widgets, such as windows, buttons, checkboxes, radiobuttons, labels, editboxes, scrolls, textareas, scales, etc. Use of this extension if very similar to the original Newt API of C programming language.
Instalacja/Konfiguracja
Spis treści
Wymagania
This module uses the functions of the RedHat Newt library. You need libnewt version >= 0.51.0.
Instalacja
To rozszerzenie » PECL nie jest dołączane do PHP. Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/newt.
W PHP 4 to rozszerzenie PECL można znaleźć w podkatalogu ext/ źródeł PHP lub pod znajdującym się wyżej odnośnikiem PECL. In order to use these functions you must compile CGI or CLI PHP with newt support by using the --with-newt[=DIR] configure option.
Informacja:
This extension is not available for Windows platform.
You may need also curses and slang libraries, in order to compile this extension. To specify locations of these libraries, use the following configuration options: --with-curses-dir=/path/to/libcurses --with-slang-dir=/path/to/libslang
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
This extension uses two resource types: "newt component" and "newt grid".
Resource type "newt component" is returned by functions, which create common newt widgets (for example: newt_button())
Resource type "newt grid" is a special link identifier for components, returned by newt grid factory functions (for example: newt_create_grid())
Stałe predefiniowane
Spis treści
- Newt form exit reasons
- Newt colorsets
- Newt argument flags
- Newt Flags Sense
- Newt Components Flags
- File Descriptor Flags
- Checkbox Tree Flags
- Entry Flags
- Listbox Flags
- Textbox Flags
- Form Flags
- Newt Keys
- Newt Anchors
- Grid Flags
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
Newt form exit reasons
| constant | meaning |
|---|---|
NEWT_EXIT_HOTKEY |
hotkey defined by newt_form_add_hot_key() was pressed |
NEWT_EXIT_COMPONENT |
some component has caused form to exit |
NEWT_EXIT_FDREADY |
file descriptor specified in newt_form_watch_fd() is ready to be read or written to |
NEWT_EXIT_TIMER |
time specified in newt_form_set_timer() has elapsed |
Newt colorsets
| constant | meaning |
|---|---|
NEWT_COLORSET_ROOT |
|
NEWT_COLORSET_BORDER |
|
NEWT_COLORSET_WINDOW |
|
NEWT_COLORSET_SHADOW |
|
NEWT_COLORSET_TITLE |
|
NEWT_COLORSET_BUTTON |
|
NEWT_COLORSET_ACTBUTTON |
|
NEWT_COLORSET_CHECKBOX |
|
NEWT_COLORSET_ACTCHECKBOX |
|
NEWT_COLORSET_ENTRY |
|
NEWT_COLORSET_LABEL |
|
NEWT_COLORSET_LISTBOX |
|
NEWT_COLORSET_ACTLISTBOX |
|
NEWT_COLORSET_TEXTBOX |
|
NEWT_COLORSET_ACTTEXTBOX |
|
NEWT_COLORSET_HELPLINE |
|
NEWT_COLORSET_ROOTTEXT |
|
NEWT_COLORSET_EMPTYSCALE |
|
NEWT_COLORSET_FULLSCALE |
|
NEWT_COLORSET_DISENTRY |
|
NEWT_COLORSET_COMPACTBUTTON |
|
NEWT_COLORSET_ACTSELLISTBOX |
|
NEWT_COLORSET_SELLISTBOX |
Newt argument flags
| constant | meaning |
|---|---|
NEWT_ARG_LAST |
|
NEWT_ARG_APPEND |
Newt Flags Sense
| constant | meaning |
|---|---|
NEWT_FLAGS_SET |
|
NEWT_FLAGS_RESET |
|
NEWT_FLAGS_TOGGLE |
Newt Components Flags
| constant | meaning |
|---|---|
NEWT_FLAG_RETURNEXIT |
Exit form, when component is activated |
NEWT_FLAG_SCROLL |
Component is scrollable |
NEWT_FLAG_DISABLED |
Component is disabled |
NEWT_FLAG_BORDER |
|
NEWT_FLAG_WRAP |
Wrap text |
NEWT_FLAG_NOF12 |
Don't exit form on pressing F12 |
NEWT_FLAG_MULTIPLE |
|
NEWT_FLAG_SELECTED |
Component is selected |
NEWT_FLAG_CHECKBOX |
Component is checkbox |
NEWT_FLAG_PASSWORD |
Entry component is password entry |
NEWT_FLAG_SHOWCURSOR |
Show cursor |
File Descriptor Flags
| constant | meaning |
|---|---|
NEWT_FD_READ |
|
NEWT_FD_WRITE |
|
NEWT_FD_EXCEPT |
Checkbox Tree Flags
| constant | meaning |
|---|---|
NEWT_CHECKBOXTREE_UNSELECTABLE |
|
NEWT_CHECKBOXTREE_HIDE_BOX |
|
NEWT_CHECKBOXTREE_COLLAPSED |
|
NEWT_CHECKBOXTREE_EXPANDED |
|
NEWT_CHECKBOXTREE_UNSELECTED |
|
NEWT_CHECKBOXTREE_SELECTED |
Entry Flags
| constant | meaning |
|---|---|
NEWT_ENTRY_SCROLL |
|
NEWT_ENTRY_RETURNEXIT |
|
NEWT_ENTRY_DISABLED |
Listbox Flags
| constant | meaning |
|---|---|
NEWT_LISTBOX_RETURNEXIT |
Textbox Flags
| constant | meaning |
|---|---|
NEWT_TEXTBOX_WRAP |
Wrap text in the textbox |
NEWT_TEXTBOX_SCROLL |
Scroll text in the textbox |
Form Flags
| constant | meaning |
|---|---|
NEWT_FORM_NOF12 |
Don't exit form on F12 press |
Newt Keys
| constant | meaning |
|---|---|
NEWT_KEY_TAB |
|
NEWT_KEY_ENTER |
|
NEWT_KEY_SUSPEND |
|
NEWT_KEY_ESCAPE |
|
NEWT_KEY_RETURN |
|
NEWT_KEY_EXTRA_BASE |
|
NEWT_KEY_UP |
|
NEWT_KEY_DOWN |
|
NEWT_KEY_LEFT |
|
NEWT_KEY_RIGHT |
|
NEWT_KEY_BKSPC |
|
NEWT_KEY_DELETE |
|
NEWT_KEY_HOME |
|
NEWT_KEY_END |
|
NEWT_KEY_UNTAB |
|
NEWT_KEY_PGUP |
|
NEWT_KEY_PGDN |
|
NEWT_KEY_INSERT |
|
NEWT_KEY_F1 |
|
NEWT_KEY_F2 |
|
NEWT_KEY_F3 |
|
NEWT_KEY_F4 |
|
NEWT_KEY_F5 |
|
NEWT_KEY_F6 |
|
NEWT_KEY_F7 |
|
NEWT_KEY_F8 |
|
NEWT_KEY_F9 |
|
NEWT_KEY_F10 |
|
NEWT_KEY_F11 |
|
NEWT_KEY_F12 |
|
NEWT_KEY_RESIZE |
Newt Anchors
| constant | meaning |
|---|---|
NEWT_ANCHOR_LEFT |
|
NEWT_ANCHOR_RIGHT |
|
NEWT_ANCHOR_TOP |
|
NEWT_ANCHOR_BOTTOM |
Grid Flags
| constant | meaning |
|---|---|
NEWT_GRID_FLAG_GROWX |
|
NEWT_GRID_FLAG_GROWY |
|
NEWT_GRID_EMPTY |
|
NEWT_GRID_COMPONENT |
|
NEWT_GRID_SUBGRID |
Przykłady
Spis treści
Basic usage
This example is a PHP port of RedHat 'setup' utility dialog, executed in text mode.
Przykład #1 Newt Usage Example
<?php
newt_init ();
newt_cls ();
newt_draw_root_text (0, 0, "Test Mode Setup Utility 1.12");
newt_push_help_line (null);
newt_draw_root_text (-30, 0, "(c) 1999-2002 RedHat, Inc");
newt_get_screen_size ($rows, $cols);
newt_open_window ($rows/2-17, $cols/2-10, 34, 17, "Choose a Tool");
$form = newt_form ();
$list = newt_listbox (3, 2, 10);
foreach (array (
"Authentication configuration",
"Firewall configuration",
"Mouse configuration",
"Network configuration",
"Printer configuration",
"System services") as $l_item)
{
newt_listbox_add_entry ($list, $l_item, $l_item);
}
$b1 = newt_button (5, 12, "Run Tool");
$b2 = newt_button (21, 12, "Quit");
newt_form_add_component ($form, $list);
newt_form_add_components ($form, array($b1, $b2));
newt_refresh ();
newt_run_form ($form);
newt_pop_window ();
newt_pop_help_line ();
newt_finished ();
newt_form_destroy ($form);
?>
Newt Funkcje
newt_bell
(PECL newt >= 0.1)
newt_bell — Send a beep to the terminal
Opis
This function sends a beep to the terminal.
Informacja:
Depending on the terminal's settings, this beep may or may not be audible.
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_centered_window
(PECL newt >= 0.1)
newt_centered_window — Open a centered window of the specified size
Opis
$width
, int $height
[, string $title
] )Open a centered window of the specified size.
Parametry
-
width -
Window width
-
height -
Window height
-
title -
Window title
Zwracane wartości
Undefined value.
Zobacz też:
- newt_pop_window() - Removes the top window from the display
- newt_open_window() - Open a window of the specified size and position
newt_checkbox_get_value
(PECL newt >= 0.1)
newt_checkbox_get_value — Retreives value of checkox resource
Opis
$checkbox
)This function returns the character in the sequence which indicates the current value of the checkbox.
Parametry
-
checkbox -
Zwracane wartości
Returns character indicating the value of the checkbox.
newt_checkbox_set_flags
(PECL newt >= 0.1)
newt_checkbox_set_flags — Configures checkbox resource
Opis
$checkbox
, int $flags
, int $sense
)This function allows to set various flags on checkbox resource.
Parametry
-
checkbox -
-
flags -
-
sense -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_checkbox_set_value
(PECL newt >= 0.1)
newt_checkbox_set_value — Sets the value of the checkbox
Opis
$checkbox
, string $value
)This function allows to set the current value of the checkbox resource.
Parametry
-
checkbox -
-
value -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_checkbox_tree_add_item
(PECL newt >= 0.1)
newt_checkbox_tree_add_item — Adds new item to the checkbox tree
Opis
$checkboxtree
, string $text
, mixed $data
, int $flags
, int $index
[, int $...
] )This function allows to add new item to the checkbox tree.
Parametry
-
checkboxtree -
-
text -
-
data -
-
flags -
-
index -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_checkbox_tree_find_item
(PECL newt >= 0.1)
newt_checkbox_tree_find_item — Finds an item in the checkbox tree
Opis
Finds an item in the checkbox tree by item's data.
Parametry
-
checkboxtree -
-
data -
Zwracane wartości
Returns checkbox tree item resource, or NULL if it wasn't found.
newt_checkbox_tree_get_current
(PECL newt >= 0.1)
newt_checkbox_tree_get_current — Returns checkbox tree selected item
Opis
This method returns checkbox tree selected tem.
Parametry
-
checkboxtree -
Zwracane wartości
Returns current (selected) checkbox tree item.
newt_checkbox_tree_get_entry_value
(PECL newt >= 0.1)
newt_checkbox_tree_get_entry_value —
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
checkboxtree -
-
data -
Zwracane wartości
newt_checkbox_tree_get_multi_selection
(PECL newt >= 0.1)
newt_checkbox_tree_get_multi_selection —
Opis
$checkboxtree
, string $seqnum
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
checkboxtree -
-
seqnum -
Zwracane wartości
newt_checkbox_tree_get_selection
(PECL newt >= 0.1)
newt_checkbox_tree_get_selection —
Opis
$checkboxtree
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
checkboxtree -
Zwracane wartości
newt_checkbox_tree_multi
(PECL newt >= 0.1)
newt_checkbox_tree_multi —
Opis
$left
, int $top
, int $height
, string $seq
[, int $flags
] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
left -
-
top -
-
height -
-
seq -
-
flags -
Zwracane wartości
newt_checkbox_tree_set_current
(PECL newt >= 0.1)
newt_checkbox_tree_set_current —
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
checkboxtree -
-
data -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_checkbox_tree_set_entry_value
(PECL newt >= 0.1)
newt_checkbox_tree_set_entry_value —
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
checkboxtree -
-
data -
-
value -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_checkbox_tree_set_entry
(PECL newt >= 0.1)
newt_checkbox_tree_set_entry —
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
checkboxtree -
-
data -
-
text -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_checkbox_tree_set_width
(PECL newt >= 0.1)
newt_checkbox_tree_set_width —
Opis
$checkbox_tree
, int $width
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
checkbox_tree -
-
width -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_checkbox_tree
(PECL newt >= 0.1)
newt_checkbox_tree —
Opis
$left
, int $top
, int $height
[, int $flags
] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
left -
-
top -
-
height -
-
flags -
Zwracane wartości
newt_checkbox
(PECL newt >= 0.1)
newt_checkbox —
Opis
$left
, int $top
, string $text
, string $def_value
[, string $seq
] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
left -
-
top -
-
text -
-
def_value -
-
seq -
Zwracane wartości
newt_clear_key_buffer
(PECL newt >= 0.1)
newt_clear_key_buffer — Discards the contents of the terminal's input buffer without waiting for additional input
Opis
Discards the contents of the terminal's input buffer without waiting for additional input.
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_cls
(PECL newt >= 0.1)
newt_cls —
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_component_add_callback
(PECL newt >= 0.1)
newt_component_add_callback —
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
component -
-
func_name -
-
data -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_component_takes_focus
(PECL newt >= 0.1)
newt_component_takes_focus —
Opis
$component
, bool $takes_focus
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
component -
-
takes_focus -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_create_grid
(PECL newt >= 0.1)
newt_create_grid —
Opis
$cols
, int $rows
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
cols -
-
rows -
Zwracane wartości
newt_cursor_off
(PECL newt >= 0.1)
newt_cursor_off —
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_cursor_on
(PECL newt >= 0.1)
newt_cursor_on —
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_delay
(PECL newt >= 0.1)
newt_delay —
Opis
$microseconds
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
microseconds -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_draw_form
(PECL newt >= 0.1)
newt_draw_form —
Opis
$form
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
form -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_draw_root_text
(PECL newt >= 0.1)
newt_draw_root_text — Displays the string text at the position indicated
Opis
$left
, int $top
, string $text
)Displays the string text at the position indicated.
Parametry
-
left -
Column number
Informacja:
If left is negative, the position is measured from the opposite side of the screen.
-
top -
Line number
Informacja:
If top is negative, the position is measured from the opposite side of the screen.
-
text -
Text to display.
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 A newt_draw_root_text() example
This code demonstrates drawing of titles in the both corners of the screen.
<?php
newt_init();
newt_cls();
newt_draw_root_text (2, 0, "Some root text");
newt_refresh();
sleep(1);
newt_draw_root_text (-30, 0, "Root text in the other corner");
newt_refresh();
sleep(1);
newt_finished();
?>
Zobacz też:
- newt_push_help_line() - Saves the current help line on a stack, and displays the new line
- newt_pop_help_line() - Replaces the current help line with the one from the stack
newt_entry_get_value
(PECL newt >= 0.1)
newt_entry_get_value —
Opis
$entry
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
entry -
Zwracane wartości
newt_entry_set_filter
(PECL newt >= 0.1)
newt_entry_set_filter —
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
entry -
-
filter -
-
data -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_entry_set_flags
(PECL newt >= 0.1)
newt_entry_set_flags —
Opis
$entry
, int $flags
, int $sense
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
entry -
-
flags -
-
sense -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_entry_set
(PECL newt >= 0.1)
newt_entry_set —
Opis
$entry
, string $value
[, bool $cursor_at_end
] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
entry -
-
value -
-
cursor_at_end -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_entry
(PECL newt >= 0.1)
newt_entry —
Opis
$left
, int $top
, int $width
[, string $init_value
[, int $flags
]] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
left -
-
top -
-
width -
-
init_value -
-
flags -
Zwracane wartości
newt_finished
(PECL newt >= 0.1)
newt_finished — Uninitializes newt interface
Opis
Uninitializes newt interface. This function be called, when program is ready to exit.
Zwracane wartości
Returns 1 on success, 0 on failure.
newt_form_add_component
(PECL newt >= 0.1)
newt_form_add_component — Adds a single component to the form
Opis
$form
, resource $component
)
Adds a single component to the form.
Parametry
-
form -
Form to which component will be added
-
component -
Component to add to the form
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 A newt_form_add_component() example
<?php
$form = newt_form();
$options = array("Authentication configuration", "Firewall configuration",
"Mouse configuration", "Network configuration", "Printer configuration",
"System services");
$list = newt_listbox(3, 2, 10);
foreach ($options as $l_item) {
newt_listbox_add_entry($list, $l_item, $l_item);
}
newt_form_add_component($form, $list);
?>
newt_form_add_components
(PECL newt >= 0.1)
newt_form_add_components — Add several components to the form
Opis
$form
, array $components
)
Adds several components to the form.
Parametry
-
form -
Form to which components will be added
-
components -
Array of components to add to the form
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 A newt_form_add_components() example
<?php
$form = newt_form();
$b1 = newt_button(5, 12, "Run Tool");
$b2 = newt_button(21, 12, "Quit");
newt_form_add_components($form, array($b1, $b2));
?>
newt_form_add_hot_key
(PECL newt >= 0.1)
newt_form_add_hot_key —
Opis
$form
, int $key
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
form -
-
key -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_form_destroy
(PECL newt >= 0.1)
newt_form_destroy — Destroys a form
Opis
$form
)This function frees the memory resources used by the form and all of the components which have been added to the form (including those components which are on subforms). Once a form has been destroyed, none of the form's components can be used.
Parametry
-
form -
Form component, which is going to be destroyed
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_form_get_current
(PECL newt >= 0.1)
newt_form_get_current —
Opis
$form
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
form -
Zwracane wartości
newt_form_run
(PECL newt >= 0.1)
newt_form_run — Runs a form
Opis
$form
, array &$exit_struct
)This function runs the form passed to it.
Parametry
-
form -
Form component
-
exit_struct -
Array, used for returning information after running the form component. Keys and values are described in the following table:
Form Exit Structure Index Key Value Type Description reason integer The reason, why the form has been exited. Possible values are defined here. watch resource Resource link, specified in newt_form_watch_fd() key integer Hotkey component resource Component, which caused the form to exit
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_form_set_background
(PECL newt >= 0.1)
newt_form_set_background —
Opis
$from
, int $background
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
from -
-
background -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_form_set_height
(PECL newt >= 0.1)
newt_form_set_height —
Opis
$form
, int $height
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
form -
-
height -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_form_set_size
(PECL newt >= 0.1)
newt_form_set_size —
Opis
$form
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
form -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_form_set_timer
(PECL newt >= 0.1)
newt_form_set_timer —
Opis
$form
, int $milliseconds
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
form -
-
milliseconds -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_form_set_width
(PECL newt >= 0.1)
newt_form_set_width —
Opis
$form
, int $width
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
form -
-
width -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_form_watch_fd
(PECL newt >= 0.1)
newt_form_watch_fd —
Opis
$form
, resource $stream
[, int $flags
] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
form -
-
stream -
-
flags -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_form
(PECL newt >= 0.1)
newt_form — Create a form
Opis
$vert_bar
[, string $help
[, int $flags
]]] )Create a new form.
Parametry
-
vert_bar -
Vertical scrollbar which should be associated with the form
-
help -
Help text string
-
flags -
Various flags
Zwracane wartości
Returns a resource link to the created form component, or FALSE on
error.
Przykłady
Przykład #1 A newt_form() example
Displays a single button "Quit", which closes the application once it's pressed.
<?php
newt_init();
newt_cls();
$myform = newt_form();
$button = newt_button (5, 12, "Quit");
newt_form_add_component ($myform, $button);
newt_refresh ();
newt_run_form ($myform);
newt_finished ();
newt_form_destroy ($myform);
?>
Zobacz też:
- newt_form_run() - Runs a form
- newt_run_form() - Runs a form
- newt_form_add_component() - Adds a single component to the form
- newt_form_add_components() - Add several components to the form
- newt_form_destroy() - Destroys a form
newt_get_screen_size
(PECL newt >= 0.1)
newt_get_screen_size — Fills in the passed references with the current size of the terminal
Opis
&$cols
, int &$rows
)Fills in the passed references with the current size of the terminal.
Parametry
-
cols -
Number of columns in the terminal
-
rows -
Number of rows in the terminal
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 A newt_get_screen_size() example
This code prints out the screen size of your terminal.
<?php
newt_init();
newt_get_screen_size (&$cols, &$rows);
newt_finished();
print "Your terminal size is: {$cols}x{$rows}\n";
?>
Powyższy przykład wyświetli:
Your terminal size is: 138x47
newt_grid_add_components_to_form
(PECL newt >= 0.1)
newt_grid_add_components_to_form —
Opis
$grid
, resource $form
, bool $recurse
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
grid -
-
form -
-
recurse -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_grid_basic_window
(PECL newt >= 0.1)
newt_grid_basic_window —
Opis
$text
, resource $middle
, resource $buttons
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
text -
-
middle -
-
buttons -
Zwracane wartości
newt_grid_free
(PECL newt >= 0.1)
newt_grid_free —
Opis
$grid
, bool $recurse
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
grid -
-
recurse -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_grid_get_size
(PECL newt >= 0.1)
newt_grid_get_size —
Opis
$grid
, int &$width
, int &$height
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
grid -
-
width -
-
height -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_grid_h_close_stacked
(PECL newt >= 0.1)
newt_grid_h_close_stacked —
Opis
$element1_type
, resource $element1
[, int $...
[, resource $...
]] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
element1_type -
-
element1 -
Zwracane wartości
newt_grid_h_stacked
(PECL newt >= 0.1)
newt_grid_h_stacked —
Opis
$element1_type
, resource $element1
[, int $...
[, resource $...
]] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
element1_type -
-
element1 -
Zwracane wartości
newt_grid_place
(PECL newt >= 0.1)
newt_grid_place —
Opis
$grid
, int $left
, int $top
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
grid -
-
left -
-
top -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_grid_set_field
(PECL newt >= 0.1)
newt_grid_set_field —
Opis
$grid
, int $col
, int $row
, int $type
, resource $val
, int $pad_left
, int $pad_top
, int $pad_right
, int $pad_bottom
, int $anchor
[, int $flags
] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
grid -
-
col -
-
row -
-
type -
-
val -
-
pad_left -
-
pad_top -
-
pad_right -
-
pad_bottom -
-
anchor -
-
flags -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_grid_simple_window
(PECL newt >= 0.1)
newt_grid_simple_window —
Opis
$text
, resource $middle
, resource $buttons
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
text -
-
middle -
-
buttons -
Zwracane wartości
newt_grid_v_close_stacked
(PECL newt >= 0.1)
newt_grid_v_close_stacked —
Opis
$element1_type
, resource $element1
[, int $...
[, resource $...
]] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
element1_type -
-
element1 -
Zwracane wartości
newt_grid_v_stacked
(PECL newt >= 0.1)
newt_grid_v_stacked —
Opis
$element1_type
, resource $element1
[, int $...
[, resource $...
]] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
element1_type -
-
element1 -
Zwracane wartości
newt_grid_wrapped_window_at
(PECL newt >= 0.1)
newt_grid_wrapped_window_at —
Opis
$grid
, string $title
, int $left
, int $top
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
grid -
-
title -
-
left -
-
top -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_grid_wrapped_window
(PECL newt >= 0.1)
newt_grid_wrapped_window —
Opis
$grid
, string $title
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
grid -
-
title -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_init
(PECL newt >= 0.1)
newt_init — Initialize newt
Opis
Initializes the newt interface. This function must be called before any other newt function.
Zwracane wartości
Returns 1 on success, 0 on failure.
newt_label_set_text
(PECL newt >= 0.1)
newt_label_set_text —
Opis
$label
, string $text
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
label -
-
text -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_label
(PECL newt >= 0.1)
newt_label —
Opis
$left
, int $top
, string $text
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
left -
-
top -
-
text -
Zwracane wartości
newt_listbox_append_entry
(PECL newt >= 0.1)
newt_listbox_append_entry —
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
listbox -
-
text -
-
data -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_listbox_clear_selection
(PECL newt >= 0.1)
newt_listbox_clear_selection —
Opis
$listbox
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
listbox -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_listbox_clear
(PECL newt >= 0.1)
newt_listbox_clear —
Opis
$listobx
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
listobx -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_listbox_delete_entry
(PECL newt >= 0.1)
newt_listbox_delete_entry —
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
listbox -
-
key -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_listbox_get_current
(PECL newt >= 0.1)
newt_listbox_get_current —
Opis
$listbox
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
listbox -
Zwracane wartości
newt_listbox_get_selection
(PECL newt >= 0.1)
newt_listbox_get_selection —
Opis
$listbox
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
listbox -
Zwracane wartości
newt_listbox_insert_entry
(PECL newt >= 0.1)
newt_listbox_insert_entry —
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
listbox -
-
text -
-
data -
-
key -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_listbox_item_count
(PECL newt >= 0.1)
newt_listbox_item_count —
Opis
$listbox
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
listbox -
Zwracane wartości
newt_listbox_select_item
(PECL newt >= 0.1)
newt_listbox_select_item —
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
listbox -
-
key -
-
sense -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_listbox_set_current_by_key
(PECL newt >= 0.1)
newt_listbox_set_current_by_key —
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
listbox -
-
key -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_listbox_set_current
(PECL newt >= 0.1)
newt_listbox_set_current —
Opis
$listbox
, int $num
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
listbox -
-
num -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_listbox_set_data
(PECL newt >= 0.1)
newt_listbox_set_data —
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
listbox -
-
num -
-
data -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_listbox_set_entry
(PECL newt >= 0.1)
newt_listbox_set_entry —
Opis
$listbox
, int $num
, string $text
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
listbox -
-
num -
-
text -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_listbox_set_width
(PECL newt >= 0.1)
newt_listbox_set_width —
Opis
$listbox
, int $width
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
listbox -
-
width -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_listbox
(PECL newt >= 0.1)
newt_listbox —
Opis
$left
, int $top
, int $height
[, int $flags
] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
left -
-
top -
-
height -
-
flags -
Zwracane wartości
newt_listitem_get_data
(PECL newt >= 0.1)
newt_listitem_get_data —
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
item -
Zwracane wartości
newt_listitem_set
(PECL newt >= 0.1)
newt_listitem_set —
Opis
$item
, string $text
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
item -
-
text -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_listitem
(PECL newt >= 0.1)
newt_listitem —
Opis
$left
, int $top
, string $text
, bool $is_default
, resouce $prev_item
, mixed $data
[, int $flags
] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
left -
-
top -
-
text -
-
is_default -
-
prev_item -
-
data -
-
flags -
Zwracane wartości
newt_open_window
(PECL newt >= 0.1)
newt_open_window — Open a window of the specified size and position
Opis
$left
, int $top
, int $width
, int $height
[, string $title
] )Open a window of the specified size and position.
Parametry
-
left -
Location of the upper left-hand corner of the window (column number)
-
top -
Location of the upper left-hand corner of the window (row number)
-
width -
Window width
-
height -
Window height
-
title -
Window title
Zwracane wartości
Returns 1 on success, 0 on failure.
Zobacz też:
- newt_pop_window() - Removes the top window from the display
- newt_centered_window() - Open a centered window of the specified size
newt_pop_help_line
(PECL newt >= 0.1)
newt_pop_help_line — Replaces the current help line with the one from the stack
Opis
Replaces the current help line with the one from the stack.
Informacja:
It's important not to call to newt_pop_help_line() more than newt_push_help_line().
Zwracane wartości
Nie jest zwracana żadna wartość.
Zobacz też:
- newt_push_help_line() - Saves the current help line on a stack, and displays the new line
newt_pop_window
(PECL newt >= 0.1)
newt_pop_window — Removes the top window from the display
Opis
Removes the top window from the display, and redraws the display areas which the window overwrote.
Zwracane wartości
Nie jest zwracana żadna wartość.
Zobacz też:
- newt_open_window() - Open a window of the specified size and position
- newt_centered_window() - Open a centered window of the specified size
newt_push_help_line
(PECL newt >= 0.1)
newt_push_help_line — Saves the current help line on a stack, and displays the new line
Opis
$text
] )Saves the current help line on a stack, and displays the new line.
Parametry
-
text -
New help text message
Informacja:
If not specified, the help line is cleared.
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_radio_get_current
(PECL newt >= 0.1)
newt_radio_get_current —
Opis
$set_member
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
set_member -
Zwracane wartości
newt_redraw_help_line
(PECL newt >= 0.1)
newt_redraw_help_line —
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_reflow_text
(PECL newt >= 0.1)
newt_reflow_text —
Opis
$text
, int $width
, int $flex_down
, int $flex_up
, int &$actual_width
, int &$actual_height
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
text -
-
width -
-
flex_down -
-
flex_up -
-
actual_width -
-
actual_height -
Zwracane wartości
newt_refresh
(PECL newt >= 0.1)
newt_refresh — Updates modified portions of the screen
Opis
To increase performance, newt only updates the display when it needs to, not when the program tells it to write to the terminal. Applications can force newt to immediately update modified portions of the screen by calling this function.
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_resize_screen
(PECL newt >= 0.1)
newt_resize_screen —
Opis
$redraw
] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
redraw -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_resume
(PECL newt >= 0.1)
newt_resume — Resume using the newt interface after calling newt_suspend()
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_run_form
(PECL newt >= 0.1)
newt_run_form — Runs a form
Opis
$form
)This function runs the form passed to it.
Parametry
-
form -
Form component
Zwracane wartości
The component which caused the form to stop running.
Informacja:
Notice that this function doesn't fit in with newt's normal naming convention. It is an older interface which will not work for all forms. It was left in newt only for legacy applications. It is a simpler interface than the new newt_form_run() though, and is still used quite often as a result. When an application is done with a form, it destroys the form and all of the components the form contains.
newt_scale_set
(PECL newt >= 0.1)
newt_scale_set —
Opis
$scale
, int $amount
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
scale -
-
amount -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_scale
(PECL newt >= 0.1)
newt_scale —
Opis
$left
, int $top
, int $width
, int $full_value
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
left -
-
top -
-
width -
-
full_value -
Zwracane wartości
newt_scrollbar_set
(PECL newt >= 0.1)
newt_scrollbar_set —
Opis
$scrollbar
, int $where
, int $total
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
scrollbar -
-
where -
-
total -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_set_help_callback
(PECL newt >= 0.1)
newt_set_help_callback —
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
function -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_set_suspend_callback
(PECL newt >= 0.1)
newt_set_suspend_callback — Set a callback function which gets invoked when user presses the suspend key
Opis
Set a callback function which gets invoked when user presses the suspend key (normally ^Z). If no suspend callback is registered, the suspend keystroke is ignored.
Parametry
-
function -
A callback function, which accepts one argument: data
-
data -
This data is been passed to the callback function
Zwracane wartości
Nie jest zwracana żadna wartość.
Zobacz też:
- newt_suspend() - Tells newt to return the terminal to its initial state
- newt_resume() - Resume using the newt interface after calling newt_suspend
newt_suspend
(PECL newt >= 0.1)
newt_suspend — Tells newt to return the terminal to its initial state
Opis
Tells newt to return the terminal to its initial state. Once this is done, the application can suspend itself (by sending itself a SIGTSTP, fork a child program, or do whatever else it likes).
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_textbox_get_num_lines
(PECL newt >= 0.1)
newt_textbox_get_num_lines —
Opis
$textbox
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
textbox -
Zwracane wartości
newt_textbox_reflowed
(PECL newt >= 0.1)
newt_textbox_reflowed —
Opis
$left
, int $top
, char $*text
, int $width
, int $flex_down
, int $flex_up
[, int $flags
] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
left -
-
top -
-
*text -
-
width -
-
flex_down -
-
flex_up -
-
flags -
Zwracane wartości
newt_textbox_set_height
(PECL newt >= 0.1)
newt_textbox_set_height —
Opis
$textbox
, int $height
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
textbox -
-
height -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_textbox_set_text
(PECL newt >= 0.1)
newt_textbox_set_text —
Opis
$textbox
, string $text
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
textbox -
-
text -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_textbox
(PECL newt >= 0.1)
newt_textbox —
Opis
$left
, int $top
, int $width
, int $height
[, int $flags
] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
left -
-
top -
-
width -
-
height -
-
flags -
Zwracane wartości
newt_vertical_scrollbar
(PECL newt >= 0.1)
newt_vertical_scrollbar —
Opis
$left
, int $top
, int $height
[, int $normal_colorset
[, int $thumb_colorset
]] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
left -
-
top -
-
height -
-
normal_colorset -
-
thumb_colorset -
Zwracane wartości
newt_wait_for_key
(PECL newt >= 0.1)
newt_wait_for_key — Doesn't return until a key has been pressed
Opis
This function doesn't return until a key has been pressed. The keystroke is then ignored. If a key is already in the terminal's buffer, this function discards a keystroke and returns immediately.
Zwracane wartości
Nie jest zwracana żadna wartość.
Zobacz też:
- newt_clear_key_buffer() - Discards the contents of the terminal's input buffer without waiting for additional input
newt_win_choice
(PECL newt >= 0.1)
newt_win_choice —
Opis
$title
, string $button1_text
, string $button2_text
, string $format
[, mixed $args
[, mixed $...
]] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
title -
-
button1_text -
-
button2_text -
-
format -
-
args -
Zwracane wartości
newt_win_entries
(PECL newt >= 0.1)
newt_win_entries —
Opis
$title
, string $text
, int $suggested_width
, int $flex_down
, int $flex_up
, int $data_width
, array &$items
, string $button1
[, string $...
] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
title -
-
text -
-
suggested_width -
-
flex_down -
-
flex_up -
-
data_width -
-
items -
-
button1 -
-
button2 -
Zwracane wartości
Przykłady
Przykład #1 A newt_win_entries() example
<?php
newt_init();
newt_cls();
$entries[] = array('text' => 'First name:', 'value' => &$f_name);
$entries[] = array('text' => 'Last name:', 'value' => &$l_name);
$rc = newt_win_entries("User information", "Please enter your credentials:", 50, 7, 7, 30, $entries, "Ok", "Back");
newt_finished ();
if ($rc != 2) {
echo "Your name is: $f_name $l_name\n";
}
?>
newt_win_message
(PECL newt >= 0.1)
newt_win_message —
Opis
$title
, string $button_text
, string $format
[, mixed $args
[, mixed $...
]] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
title -
-
button_text -
-
format -
-
args -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_win_messagev
(PECL newt >= 0.1)
newt_win_messagev —
Opis
$title
, string $button_text
, string $format
, array $args
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
title -
-
button_text -
-
format -
-
args -
Zwracane wartości
Nie jest zwracana żadna wartość.
newt_win_ternary
(PECL newt >= 0.1)
newt_win_ternary —
Opis
$title
, string $button1_text
, string $button2_text
, string $button3_text
, string $format
[, mixed $args
[, mixed $...
]] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
title -
Its description
-
button1_text -
Its description
-
button2_text -
Its description
-
button3_text -
Its description
-
format -
Its description
-
args -
Its description
Zwracane wartości
What the function returns, first on success, then on failure. See also the &return.success; entity
Spis treści
- newt_bell — Send a beep to the terminal
- newt_button_bar — This function returns a grid containing the buttons created.
- newt_button — Create a new button
- newt_centered_window — Open a centered window of the specified size
- newt_checkbox_get_value — Retreives value of checkox resource
- newt_checkbox_set_flags — Configures checkbox resource
- newt_checkbox_set_value — Sets the value of the checkbox
- newt_checkbox_tree_add_item — Adds new item to the checkbox tree
- newt_checkbox_tree_find_item — Finds an item in the checkbox tree
- newt_checkbox_tree_get_current — Returns checkbox tree selected item
- newt_checkbox_tree_get_entry_value — Opis
- newt_checkbox_tree_get_multi_selection — Opis
- newt_checkbox_tree_get_selection — Opis
- newt_checkbox_tree_multi — Opis
- newt_checkbox_tree_set_current — Opis
- newt_checkbox_tree_set_entry_value — Opis
- newt_checkbox_tree_set_entry — Opis
- newt_checkbox_tree_set_width — Opis
- newt_checkbox_tree — Opis
- newt_checkbox — Opis
- newt_clear_key_buffer — Discards the contents of the terminal's input buffer without waiting for additional input
- newt_cls — Opis
- newt_compact_button — Opis
- newt_component_add_callback — Opis
- newt_component_takes_focus — Opis
- newt_create_grid — Opis
- newt_cursor_off — Opis
- newt_cursor_on — Opis
- newt_delay — Opis
- newt_draw_form — Opis
- newt_draw_root_text — Displays the string text at the position indicated
- newt_entry_get_value — Opis
- newt_entry_set_filter — Opis
- newt_entry_set_flags — Opis
- newt_entry_set — Opis
- newt_entry — Opis
- newt_finished — Uninitializes newt interface
- newt_form_add_component — Adds a single component to the form
- newt_form_add_components — Add several components to the form
- newt_form_add_hot_key — Opis
- newt_form_destroy — Destroys a form
- newt_form_get_current — Opis
- newt_form_run — Runs a form
- newt_form_set_background — Opis
- newt_form_set_height — Opis
- newt_form_set_size — Opis
- newt_form_set_timer — Opis
- newt_form_set_width — Opis
- newt_form_watch_fd — Opis
- newt_form — Create a form
- newt_get_screen_size — Fills in the passed references with the current size of the terminal
- newt_grid_add_components_to_form — Opis
- newt_grid_basic_window — Opis
- newt_grid_free — Opis
- newt_grid_get_size — Opis
- newt_grid_h_close_stacked — Opis
- newt_grid_h_stacked — Opis
- newt_grid_place — Opis
- newt_grid_set_field — Opis
- newt_grid_simple_window — Opis
- newt_grid_v_close_stacked — Opis
- newt_grid_v_stacked — Opis
- newt_grid_wrapped_window_at — Opis
- newt_grid_wrapped_window — Opis
- newt_init — Initialize newt
- newt_label_set_text — Opis
- newt_label — Opis
- newt_listbox_append_entry — Opis
- newt_listbox_clear_selection — Opis
- newt_listbox_clear — Opis
- newt_listbox_delete_entry — Opis
- newt_listbox_get_current — Opis
- newt_listbox_get_selection — Opis
- newt_listbox_insert_entry — Opis
- newt_listbox_item_count — Opis
- newt_listbox_select_item — Opis
- newt_listbox_set_current_by_key — Opis
- newt_listbox_set_current — Opis
- newt_listbox_set_data — Opis
- newt_listbox_set_entry — Opis
- newt_listbox_set_width — Opis
- newt_listbox — Opis
- newt_listitem_get_data — Opis
- newt_listitem_set — Opis
- newt_listitem — Opis
- newt_open_window — Open a window of the specified size and position
- newt_pop_help_line — Replaces the current help line with the one from the stack
- newt_pop_window — Removes the top window from the display
- newt_push_help_line — Saves the current help line on a stack, and displays the new line
- newt_radio_get_current — Opis
- newt_radiobutton — Opis
- newt_redraw_help_line — Opis
- newt_reflow_text — Opis
- newt_refresh — Updates modified portions of the screen
- newt_resize_screen — Opis
- newt_resume — Resume using the newt interface after calling newt_suspend
- newt_run_form — Runs a form
- newt_scale_set — Opis
- newt_scale — Opis
- newt_scrollbar_set — Opis
- newt_set_help_callback — Opis
- newt_set_suspend_callback — Set a callback function which gets invoked when user presses the suspend key
- newt_suspend — Tells newt to return the terminal to its initial state
- newt_textbox_get_num_lines — Opis
- newt_textbox_reflowed — Opis
- newt_textbox_set_height — Opis
- newt_textbox_set_text — Opis
- newt_textbox — Opis
- newt_vertical_scrollbar — Opis
- newt_wait_for_key — Doesn't return until a key has been pressed
- newt_win_choice — Opis
- newt_win_entries — Opis
- newt_win_menu — Opis
- newt_win_message — Opis
- newt_win_messagev — Opis
- newt_win_ternary — Opis
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Przykłady
- Newt Funkcje
- newt_bell — Send a beep to the terminal
- newt_button_bar — This function returns a grid containing the buttons created.
- newt_button — Create a new button
- newt_centered_window — Open a centered window of the specified size
- newt_checkbox_get_value — Retreives value of checkox resource
- newt_checkbox_set_flags — Configures checkbox resource
- newt_checkbox_set_value — Sets the value of the checkbox
- newt_checkbox_tree_add_item — Adds new item to the checkbox tree
- newt_checkbox_tree_find_item — Finds an item in the checkbox tree
- newt_checkbox_tree_get_current — Returns checkbox tree selected item
- newt_checkbox_tree_get_entry_value — Opis
- newt_checkbox_tree_get_multi_selection — Opis
- newt_checkbox_tree_get_selection — Opis
- newt_checkbox_tree_multi — Opis
- newt_checkbox_tree_set_current — Opis
- newt_checkbox_tree_set_entry_value — Opis
- newt_checkbox_tree_set_entry — Opis
- newt_checkbox_tree_set_width — Opis
- newt_checkbox_tree — Opis
- newt_checkbox — Opis
- newt_clear_key_buffer — Discards the contents of the terminal's input buffer without waiting for additional input
- newt_cls — Opis
- newt_compact_button — Opis
- newt_component_add_callback — Opis
- newt_component_takes_focus — Opis
- newt_create_grid — Opis
- newt_cursor_off — Opis
- newt_cursor_on — Opis
- newt_delay — Opis
- newt_draw_form — Opis
- newt_draw_root_text — Displays the string text at the position indicated
- newt_entry_get_value — Opis
- newt_entry_set_filter — Opis
- newt_entry_set_flags — Opis
- newt_entry_set — Opis
- newt_entry — Opis
- newt_finished — Uninitializes newt interface
- newt_form_add_component — Adds a single component to the form
- newt_form_add_components — Add several components to the form
- newt_form_add_hot_key — Opis
- newt_form_destroy — Destroys a form
- newt_form_get_current — Opis
- newt_form_run — Runs a form
- newt_form_set_background — Opis
- newt_form_set_height — Opis
- newt_form_set_size — Opis
- newt_form_set_timer — Opis
- newt_form_set_width — Opis
- newt_form_watch_fd — Opis
- newt_form — Create a form
- newt_get_screen_size — Fills in the passed references with the current size of the terminal
- newt_grid_add_components_to_form — Opis
- newt_grid_basic_window — Opis
- newt_grid_free — Opis
- newt_grid_get_size — Opis
- newt_grid_h_close_stacked — Opis
- newt_grid_h_stacked — Opis
- newt_grid_place — Opis
- newt_grid_set_field — Opis
- newt_grid_simple_window — Opis
- newt_grid_v_close_stacked — Opis
- newt_grid_v_stacked — Opis
- newt_grid_wrapped_window_at — Opis
- newt_grid_wrapped_window — Opis
- newt_init — Initialize newt
- newt_label_set_text — Opis
- newt_label — Opis
- newt_listbox_append_entry — Opis
- newt_listbox_clear_selection — Opis
- newt_listbox_clear — Opis
- newt_listbox_delete_entry — Opis
- newt_listbox_get_current — Opis
- newt_listbox_get_selection — Opis
- newt_listbox_insert_entry — Opis
- newt_listbox_item_count — Opis
- newt_listbox_select_item — Opis
- newt_listbox_set_current_by_key — Opis
- newt_listbox_set_current — Opis
- newt_listbox_set_data — Opis
- newt_listbox_set_entry — Opis
- newt_listbox_set_width — Opis
- newt_listbox — Opis
- newt_listitem_get_data — Opis
- newt_listitem_set — Opis
- newt_listitem — Opis
- newt_open_window — Open a window of the specified size and position
- newt_pop_help_line — Replaces the current help line with the one from the stack
- newt_pop_window — Removes the top window from the display
- newt_push_help_line — Saves the current help line on a stack, and displays the new line
- newt_radio_get_current — Opis
- newt_radiobutton — Opis
- newt_redraw_help_line — Opis
- newt_reflow_text — Opis
- newt_refresh — Updates modified portions of the screen
- newt_resize_screen — Opis
- newt_resume — Resume using the newt interface after calling newt_suspend
- newt_run_form — Runs a form
- newt_scale_set — Opis
- newt_scale — Opis
- newt_scrollbar_set — Opis
- newt_set_help_callback — Opis
- newt_set_suspend_callback — Set a callback function which gets invoked when user presses the suspend key
- newt_suspend — Tells newt to return the terminal to its initial state
- newt_textbox_get_num_lines — Opis
- newt_textbox_reflowed — Opis
- newt_textbox_set_height — Opis
- newt_textbox_set_text — Opis
- newt_textbox — Opis
- newt_vertical_scrollbar — Opis
- newt_wait_for_key — Doesn't return until a key has been pressed
- newt_win_choice — Opis
- newt_win_entries — Opis
- newt_win_menu — Opis
- newt_win_message — Opis
- newt_win_messagev — Opis
- newt_win_ternary — Opis
GNU Readline
Wstęp
Funkcje readline implementują interfejs do biblioteki GNU Readline. Pozwalają one na tworzenie edytowalnych wierszy poleceń. Jako przykład może posłużyć Bash, który pozwala na używanie klawiszy strzałek do poruszania się po wpisanej części polecenia lub przewijanie historii. Ze względu na interaktywność tej biblioteki, jest ona mało przydatna do pisania aplikacji sieciowych, lecz może być pomocna przy pisaniu skryptów przeznaczonych do używania PHP z wiersza poleceń.
Informacja: To rozszerzenie nie jest dostępne na platformie Windows.
Instalacja/Konfiguracja
Spis treści
Wymagania
Aby korzystać z funkcji readline niezbędne jest zainstalowanie biblioteki libreadline. Bibliotekę libreadline można znaleźć na witrynie projektu GNU Readline, » http://cnswww.cns.cwru.edu/~chet/readline/rltop.html Jest ona rozwijana przez Cheta Ramey'a, który jest także autorem Basha.
Z tych funkcji można skorzystać także przy użyciu biblioteki libedit, zamiennika biblioteki readline, wydanego na licencji innej niż GPL. Biblioteka libedit jest wydana na licencji BSD i można ją znaleźć pod adresem » http://www.thrysoee.dk/editline/.
Instalacja
Aby używać tych funkcji należy skompilować PHP w wersji CGI lub CLI z obsługą readline. Podczas konfiguracji PHP należy dodać opcję --with-readline[=DIR] . Aby używać odpowiednika readline - libedit, należy podczas konfiguracji PHP dodać opcję --with-libedit[=DIR] .
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| cli.pager | "" | PHP_INI_ALL | Available since PHP 5.4.0. |
| cli.prompt | "\\b \\> " | PHP_INI_ALL | Available since PHP 5.4.0. |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
cli.pagerstring -
External tool to display output from command line.
-
cli.promptstring -
Command line prompt.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
To rozszerzenie nie posiada żadnych stałych.
Funkcje Readline
readline_add_history
(PHP 4, PHP 5)
readline_add_history — Dodaje wiersz do historii
Opis
$wiersz
)Funkcja ta dodaje wiersz do historii wiersza poleceń.
Parametry
-
wiersz -
Wiersz, który zostanie dodany do historii.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
readline_callback_handler_install
(PHP 5 >= 5.1.0)
readline_callback_handler_install — Initializes the readline callback interface and terminal, prints the prompt and returns immediately
Opis
$prompt
, callable $callback
)
Sets up a readline callback interface then prints
prompt and immediately returns.
Calling this function twice without removing the previous
callback interface will automatically and conveniently overwrite the old
interface.
The callback feature is useful when combined with stream_select() as it allows interleaving of IO and user input, unlike readline().
Parametry
-
prompt -
The prompt message.
-
callback -
The
callbackfunction takes one parameter; the user input returned.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Readline Callback Interface Example
<?php
function rl_callback($ret)
{
global $c, $prompting;
echo "You entered: $ret\n";
$c++;
if ($c > 10) {
$prompting = false;
readline_callback_handler_remove();
} else {
readline_callback_handler_install("[$c] Enter something: ", 'rl_callback');
}
}
$c = 1;
$prompting = true;
readline_callback_handler_install("[$c] Enter something: ", 'rl_callback');
while ($prompting) {
$w = NULL;
$e = NULL;
$n = stream_select($r = array(STDIN), $w, $e, null);
if ($n && in_array(STDIN, $r)) {
// read a character, will call the callback when a newline is entered
readline_callback_read_char();
}
}
echo "Prompting disabled. All done.\n";
?>
Zobacz też:
- readline_callback_handler_remove() - Removes a previously installed callback handler and restores terminal settings
- readline_callback_read_char() - Reads a character and informs the readline callback interface when a line is received
- stream_select() - Runs the equivalent of the select() system call on the given arrays of streams with a timeout specified by tv_sec and tv_usec
readline_callback_handler_remove
(PHP 5 >= 5.1.0)
readline_callback_handler_remove — Removes a previously installed callback handler and restores terminal settings
Opis
Removes a previously installed callback handler and restores terminal settings.
Zwracane wartości
Returns TRUE if a previously installed callback handler was removed, or
FALSE if one could not be found.
Przykłady
See readline_callback_handler_install() for an example of how to use the readline callback interface.
Zobacz też:
- readline_callback_handler_install() - Initializes the readline callback interface and terminal, prints the prompt and returns immediately
- readline_callback_read_char() - Reads a character and informs the readline callback interface when a line is received
readline_callback_read_char
(PHP 5 >= 5.1.0)
readline_callback_read_char — Reads a character and informs the readline callback interface when a line is received
Opis
Reads a character of user input. When a line is received, this function informs the readline callback interface installed using readline_callback_handler_install() that a line is ready for input.
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
See readline_callback_handler_install() for an example of how to use the readline callback interface.
Zobacz też:
- readline_callback_handler_install() - Initializes the readline callback interface and terminal, prints the prompt and returns immediately
- readline_callback_handler_remove() - Removes a previously installed callback handler and restores terminal settings
readline_clear_history
(PHP 4, PHP 5)
readline_clear_history — Czyści historię
Opis
Funkcja ta czyści całą historię wiersza poleceń.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
readline_completion_function
(PHP 4, PHP 5)
readline_completion_function — Rejestruje funkcję dopełniania
Opis
Funkcja ta rejestruje funkcję dopełniania. Jest to efekt, który można zaobserwować wciskając klawisz TAB używając Basha.
Parametry
-
funkcja -
Musisz podać nazwę istniejącej funkcji, która przyjmuje jako parametr częściowo wypełniony wiersz, i zwraca tablicę możliwych dopełnień.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
readline_info
(PHP 4, PHP 5)
readline_info — Pobiera/ustawia różne wewnętrzne zmienne biblioteki readline
Opis
Pobiera lub ustawia różne wewnętrzne zmienne biblioteki readline.
Parametry
-
nazwa_zmiennej -
Nazwa zmiennej.
-
nowa_wartość -
Jeśli podana, to zostanie ustawiona nowa wartość.
Zwracane wartości
Jeśli funkcja zostanie wywołana bez parametrów, to zwrócona zostanie tablica z wartościami wszystkich ustawień biblioteki readline. Elementy tej tablicy będą miały takie indeksy: done, end, erase_empty_line, library_version, line_buffer, mark, pending_input, point, prompt, readline_name, i terminal_name.
Jeśli zostanie wywołana z jednym lub dwoma parametrami, zostanie zwrócona poprzenia wartość
readline_list_history
(PHP 4, PHP 5)
readline_list_history — Zwraca historię wiersza poleceń
Opis
Pobiera całą historię wiersza poleceń.
Zwracane wartości
Funkcja ta zwraca tablicę zawierającą całą historię wiersza poleceń. Elementy są indeksowane przez liczby całkowite poczynając od zera.
readline_on_new_line
(PHP 5 >= 5.1.0)
readline_on_new_line — Inform readline that the cursor has moved to a new line
Opis
Tells readline that the cursor has moved to a new line.
Zwracane wartości
Nie jest zwracana żadna wartość.
readline_read_history
(PHP 4, PHP 5)
readline_read_history — Czyta historię
Opis
$nazwa_pliku
] )Funkcja ta czyta historię poleceń z pliku.
Parametry
-
nazwa_pliku -
Ścieżka do pliku zawierającego historię poleceń.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
readline_redisplay
(PHP 5 >= 5.1.0)
readline_redisplay — Redraws the display
Opis
Redraws readline to redraw the display.
Zwracane wartości
Nie jest zwracana żadna wartość.
readline_write_history
(PHP 4, PHP 5)
readline_write_history — Zapisuje historię
Opis
$nazwa_pliku
] )Funkcja ta zapisuje historię poleceń do pliku.
Parametry
-
nazwa_pliku -
Ścieżka zapisywanego pliku.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
readline
(PHP 4, PHP 5)
readline — Czyta linię
Opis
$prompt
)Funkcja ta zwraca pojedyńczy string pobrany od użytkownika. Jako parametr funkcji można podać string zawierający prompt (znak zachęty) który będzie wyświetlony. Zwracany string ma usunięty z końca znak nowego wiersza. Musisz dodać do linię do historii ręcznie używając readline_add_history().
Przykład #1 readline()
<?php
// pobierz 3 komendy od użytkownika
for ($i=0; $i < 3; $i++) {
$line = readline("Komenda: ");
readline_add_history($line);
}
// zrzuć historię
print_r(readline_list_history());
// zrzuć zmienne
print_r(readline_info());
?>
Spis treści
- readline_add_history — Dodaje wiersz do historii
- readline_callback_handler_install — Initializes the readline callback interface and terminal, prints the prompt and returns immediately
- readline_callback_handler_remove — Removes a previously installed callback handler and restores terminal settings
- readline_callback_read_char — Reads a character and informs the readline callback interface when a line is received
- readline_clear_history — Czyści historię
- readline_completion_function — Rejestruje funkcję dopełniania
- readline_info — Pobiera/ustawia różne wewnętrzne zmienne biblioteki readline
- readline_list_history — Zwraca historię wiersza poleceń
- readline_on_new_line — Inform readline that the cursor has moved to a new line
- readline_read_history — Czyta historię
- readline_redisplay — Redraws the display
- readline_write_history — Zapisuje historię
- readline — Czyta linię
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Funkcje Readline
- readline_add_history — Dodaje wiersz do historii
- readline_callback_handler_install — Initializes the readline callback interface and terminal, prints the prompt and returns immediately
- readline_callback_handler_remove — Removes a previously installed callback handler and restores terminal settings
- readline_callback_read_char — Reads a character and informs the readline callback interface when a line is received
- readline_clear_history — Czyści historię
- readline_completion_function — Rejestruje funkcję dopełniania
- readline_info — Pobiera/ustawia różne wewnętrzne zmienne biblioteki readline
- readline_list_history — Zwraca historię wiersza poleceń
- readline_on_new_line — Inform readline that the cursor has moved to a new line
- readline_read_history — Czyta historię
- readline_redisplay — Redraws the display
- readline_write_history — Zapisuje historię
- readline — Czyta linię
Rozszerzenia kompresji i archiwizacji
Bzip2
Wstęp
Funkcje bzip2 są używane do odczytu i zapisu skompresowanych plików bzip2 (.bz2).
Instalacja/Konfiguracja
Spis treści
Wymagania
Ten moduł używa funkcji z biblioteki » bzip2 stworzonej przez Juliana Seward'a. Moduł wymaga bzip2/libbzip2 w wersji >= 1.0.x.
Instalacja
Obsługa Bzip2 nie jest domyślnie włączona w PHP. Aby ją aktywować, należy użyć opcji konfiguracyjnej --with-bz2[=DIR] podczas kompilacji PHP z kodu źródłowego.
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
To rozszeżenie definiuje jeden typ zasobów: wskaźnik pliku identyfikujący plik bz2, na którym pracuje.
Stałe predefiniowane
To rozszerzenie nie posiada żadnych stałych.
Przykłady
Ten przykład pokazuje otwiercie tymczasowego pliku i zapisu do niego łańcucha znaków. Następnie wyświetlana jest zawartość pliku.
Przykład #1 Przykład użycia bzip2
<?php
$filename = "/tmp/testfile.bz2";
$str = "To jest testowy lancuch znakow.\n";
// otwarcie pliku do zapisu
$bz = bzopen($filename, "w");
// zapisanie łańcucha znaków do pliku
bzwrite($bz, $str);
// zamknięcie pliku
bzclose($bz);
// otwarcie pliku do odczytu
$bz = bzopen($filename, "r");
// przeczytanie 10 znaków
echo bzread($bz, 10);
// wyświetlaj dopóki nie nastąpi koniec pliku (lub następne 1024 znaki) i zamknij go.
echo bzread($bz);
bzclose($bz);
?>
Funkcje Bzip2
bzclose
(PHP 4 >= 4.0.4, PHP 5)
bzclose — Zamyka otwarty plik bzip2
Opis
$bz
)Funkcja zamyka wybrany uchwyt pliku bzip2.
Parametry
-
bz -
Uchwyt do pliku musi być poprawny oraz musi wskazywać na plik otwarty za pomocą funkcji bzopen().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
bzcompress
(PHP 4 >= 4.0.4, PHP 5)
bzcompress — Compress a string into bzip2 encoded data
Opis
bzcompress() compresses the given string and returns it as bzip2 encoded data.
Parametry
-
source -
The string to compress.
-
blocksize -
Specifies the blocksize used during compression and should be a number from 1 to 9 with 9 giving the best compression, but using more resources to do so.
-
workfactor -
Controls how the compression phase behaves when presented with worst case, highly repetitive, input data. The value can be between 0 and 250 with 0 being a special case.
Regardless of the
workfactor, the generated output is the same.
Zwracane wartości
The compressed string, or an error number if an error occurred.
Przykłady
Przykład #1 Compressing data
<?php
$str = "sample data";
$bzstr = bzcompress($str, 9);
echo $bzstr;
?>
bzdecompress
(PHP 4 >= 4.0.4, PHP 5)
bzdecompress — Decompresses bzip2 encoded data
Opis
bzdecompress() decompresses the given string containing bzip2 encoded data.
Parametry
-
source -
The string to decompress.
-
small -
If
TRUE, an alternative decompression algorithm will be used which uses less memory (the maximum memory requirement drops to around 2300K) but works at roughly half the speed.See the » bzip2 documentation for more information about this feature.
Zwracane wartości
The decompressed string, or an error number if an error occurred.
Przykłady
Przykład #1 Decompressing a String
<?php
$start_str = "This is not an honest face?";
$bzstr = bzcompress($start_str);
echo "Compressed String: ";
echo $bzstr;
echo "\n<br />\n";
$str = bzdecompress($bzstr);
echo "Decompressed String: ";
echo $str;
echo "\n<br />\n";
?>
bzerrno
(PHP 4 >= 4.0.4, PHP 5)
bzerrno — Zwraca numer błędu biblioteki bzip2.
Opis
$bz
)Zwraca numer dowolnego błędu bzip2 zwróconego przez podany wskaźnik pliku.
Parametry
-
bz -
Uchwyt do pliku musi być poprawny oraz musi wskazywać na plik otwarty za pomocą funkcji bzopen().
Zwracane wartości
Zwraca numer błędu jako liczbę całkowitą.
Zobacz też:
- bzerror() - Zwraca numer błędu bzip2 oraz opis błędu w postaci tablicy.
- bzerrstr() - Zwraca opis błędu bzip2
bzerror
(PHP 4 >= 4.0.4, PHP 5)
bzerror — Zwraca numer błędu bzip2 oraz opis błędu w postaci tablicy.
Opis
$bz
)
Zwraca tablicę asocjacyjną zawierającą opis i numer błędu biblioteki bzip2,
który wystąpił podczas pracy z plikiem bz.
Parametry
-
bz -
Uchwyt do pliku musi być poprawny oraz musi wskazywać na plik otwarty za pomocą funkcji bzopen().
Zwracane wartości
Zwraca tablicę asocjacyjną zawierającą, z kodem błedu w indeksie errno, i treścią błedu w indeksie errstr.
Przykłady
Przykład #1 bzerror() przykład
<?php
$error = bzerror($bz);
echo $error["errno"];
echo $error["errstr"];
?>
bzerrstr
(PHP 4 >= 4.0.4, PHP 5)
bzerrstr — Zwraca opis błędu bzip2
Opis
$bz
)
Pobiera opis dowolnego błędu bzip2, który wystąpił podczas pracy z plikiem bz.
Parametry
-
bz -
Uchwyt do pliku musi być poprawny oraz musi wskazywać na plik otwarty za pomocą funkcji bzopen().
Zwracane wartości
Zwraca łańcuch znaków zawierający opis błędu.
bzflush
(PHP 4 >= 4.0.4, PHP 5)
bzflush — Wymusza zapisanie do pliku wszystkich danych z bufora
Opis
$bz
)
Wymusza zapisanie do pliku bz wszystkich danych
znajdujących się w buforze.
Parametry
-
bz -
Uchwyt do pliku musi być poprawny oraz musi wskazywać na plik otwarty za pomocą funkcji bzopen().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
bzopen
(PHP 4 >= 4.0.4, PHP 5)
bzopen — Otwiera skompresowany plik bzip2
Opis
$nazwa_pliku
, string $tryb
)bzopen() otwiera plik bzip2 (.bz2) do odczytu lub zapisu.
Parametry
-
nazwa_pliku -
Nazwa otwieranego pliku.
-
Tryb -
Podobnie do funkcji fopen() obsługiwane są tylko 'r' (odczyt) i 'w' (zapis). Wszystko inne spowoduje, że bzopen zwróci
FALSE.
Zwracane wartości
Jeśli otworzenie się nie powiedzie bzopen() zwróci FALSE, w przeciwnym wypadku
zostanie zwrócony uchwyt do nowootwartego pliku.
Przykłady
Przykład #1 bzopen() przykład
<?php
$file = "/tmp/foo.bz2";
$bz = bzopen($file, "r") or die("Nie mogę otworzyć do odczytu pliku: $file");
bzclose($bz);
?>
bzread
(PHP 4 >= 4.0.4, PHP 5)
bzread — Binarnie bezpieczny odczyt pliku bzip2
Opis
$bz
[, int $długość = 1024
] )bzread() odczytuje z podanego wskaźnika pliku.
Odczytywanie jest zatrzymywane, gdy przeczytano długość (nieskompresowanych) bajtów
lub osiągnięto EOF, cokolwiek wystąpi pierwsze.
Parametry
-
bz -
Uchwyt do pliku musi być poprawny oraz musi wskazywać na plik otwarty za pomocą funkcji bzopen().
-
długość -
Jeśli nie została określona bzread() zostaną odczytane 1024 (nieskompresowane) bajty. Maksymalnie może zostać odczytanych 8192 bajtów.
Zwracane wartości
Zwraca nieskompresowane dane lub FALSE w przypadku błędu.
Przykłady
Przykład #1 bzread() przykład
<?php
$file = "/tmp/foo.bz2";
$bz = bzopen($file, "r") or die("Nie mogę otworzyć $file");
$decompressed_file = '';
while (!feof($bz)) {
$decompressed_file .= bzread($bz, 4096);
}
bzclose($bz);
echo "Zawartość pliku $file to: <br />\n";
echo $decompressed_file;
?>
bzwrite
(PHP 4 >= 4.0.4, PHP 5)
bzwrite — Binarnie bezpieczny zapis plików bzip2
Opis
$bz
, string $dane
[, int $długość
] )bzwrite() zapisuje łaźcuch znaków do podanego strumienia pliku bzip2.
Parametry
-
bz -
Uchwyt do pliku musi być poprawny oraz musi wskazywać na plik otwarty za pomocą funkcji bzopen().
-
dane -
Zapisywane dane.
-
długość -
Jeśłi podano, zapisywanie zostanie zakończone po zapisaniu
długość(nieskompresowanych) bajtów lub po skończeniu siędanychcokolwiek nastąpi wcześniej.
Zwracane wartości
Zwraca liczbę zapisanych bajtów, lub FALSE w przypadku błędu.
Przykłady
Przykład #1 bzwrite() przykład
<?php
$str = "nieskompresowane dane";
$bz = bzopen("/tmp/foo.bz2", "w");
bzwrite($bz, $str, strlen($str));
bzclose($bz);
?>
Spis treści
- bzclose — Zamyka otwarty plik bzip2
- bzcompress — Compress a string into bzip2 encoded data
- bzdecompress — Decompresses bzip2 encoded data
- bzerrno — Zwraca numer błędu biblioteki bzip2.
- bzerror — Zwraca numer błędu bzip2 oraz opis błędu w postaci tablicy.
- bzerrstr — Zwraca opis błędu bzip2
- bzflush — Wymusza zapisanie do pliku wszystkich danych z bufora
- bzopen — Otwiera skompresowany plik bzip2
- bzread — Binarnie bezpieczny odczyt pliku bzip2
- bzwrite — Binarnie bezpieczny zapis plików bzip2
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Przykłady
- Funkcje Bzip2
- bzclose — Zamyka otwarty plik bzip2
- bzcompress — Compress a string into bzip2 encoded data
- bzdecompress — Decompresses bzip2 encoded data
- bzerrno — Zwraca numer błędu biblioteki bzip2.
- bzerror — Zwraca numer błędu bzip2 oraz opis błędu w postaci tablicy.
- bzerrstr — Zwraca opis błędu bzip2
- bzflush — Wymusza zapisanie do pliku wszystkich danych z bufora
- bzopen — Otwiera skompresowany plik bzip2
- bzread — Binarnie bezpieczny odczyt pliku bzip2
- bzwrite — Binarnie bezpieczny zapis plików bzip2
LZF
Wstęp
LZF is a very fast compression algorithm, ideal for saving space with only slight speed cost. It can be optimized for speed or space at the time of compilation. This extension is using » liblzf library by Marc Lehmann for its operations.
Instalacja/Konfiguracja
Spis treści
Wymagania
Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.
Instalacja
To rozszerzenie » PECL nie jest dołączane do PHP. Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/lzf.
In order to use these functions you must compile PHP with lzf support by using the --with-lzf[=DIR] configure option. You may also pass --enable-lzf-better-compression to optimize LZF for space rather than speed.
Windows users will enable php_lzf.dll inside of php.ini in order to use these functions. DLL z tym rozszerzeniem PECL można pobrać zarówno ze strony » PHP Downloads lub z » http://pecl4win.php.net/
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
To rozszerzenie nie posiada żadnych stałych.
LZF Funkcje
lzf_compress
(PECL lzf >= 0.1.0)
lzf_compress — LZF compression
Opis
$data
)
lzf_compress() compresses the given
data string using LZF encoding.
Parametry
-
data -
The string to compress.
Zwracane wartości
Returns the compressed data or FALSE if an error occurred.
lzf_decompress
(PECL lzf >= 0.1.0)
lzf_decompress — LZF decompression
Opis
$data
)
lzf_compress() decompresses the given
data string containing lzf encoded data.
Parametry
-
data -
The compressed string.
Zwracane wartości
Returns the decompressed data or FALSE if an error occurred.
lzf_optimized_for
(PECL lzf >= 1.0.0)
lzf_optimized_for — Determines what LZF extension was optimized for
Opis
Determines what was LZF extension optimized for during compilation.
Zwracane wartości
Returns 1 if LZF was optimized for speed, 0 for compression.
Spis treści
- lzf_compress — LZF compression
- lzf_decompress — LZF decompression
- lzf_optimized_for — Determines what LZF extension was optimized for
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- LZF Funkcje
- lzf_compress — LZF compression
- lzf_decompress — LZF decompression
- lzf_optimized_for — Determines what LZF extension was optimized for
Phar
Wstęp
The phar extension provides a way to put entire PHP applications into a single file called a "phar" (PHP Archive) for easy distribution and installation. In addition to providing this service, the phar extension also provides a file-format abstraction method for creating and manipulating tar and zip files through the PharData class, much as PDO provides a unified interface for accessing different databases. Unlike PDO, which cannot convert between different databases, Phar also can convert between tar, zip and phar file formats with a single line of code. see Phar::convertToExecutable() for one example.
What is phar? Phar archives are best characterized as a convenient way to group several files into a single file. As such, a phar archive provides a way to distribute a complete PHP application in a single file and run it from that file without the need to extract it to disk. Additionally, phar archives can be executed by PHP as easily as any other file, both on the commandline and from a web server. Phar is kind of like a thumb drive for PHP applications.
Phar implements this functionality through a Stream Wrapper. Normally, to use an external file within a PHP script, you would use include()
Przykład #1 Using an external file
<?php
include '/path/to/external/file.php';
?>
PHP can be thought of as actually translating /path/to/external/file.php into a stream wrapper as file:///path/to/external/file.php, and under the hood it does in fact use the plain file stream wrapper stream functions to access all local files.
To use a file named file.php contained with a phar archive /path/to/myphar.phar, the syntax is very similar to the file:// syntax above.
Przykład #2 Using a file within a phar archive
<?php
include 'phar:///path/to/myphar.phar/file.php';
?>
In fact, one can treat a phar archive exactly as if it were an external disk, using any of fopen()-related functions, opendir() and mkdir()-related functions to read, change, or create new files and directories within the phar archive. This allows complete PHP applications to be distributed in a single file and run directly from that file.
The most common usage for a phar archive is to distribute a complete application in a single file. For instance, the PEAR Installer that is bundled with PHP versions is distributed as a phar archive. To use a phar archive distributed in this way, the archive can be executed on the command-line or via a web server.
Phar archives can be distributed as tar archives, zip archives, or as the custom phar file format designed specifically for the phar extension. Each file format has advantages and disadvantages. The tar and zip file formats can be read or extracted by any third-party tool that can read the format, but require the phar extension in order to run with PHP. The phar file format is customized and unique to the phar extension, and can only be created by the phar extension or the PEAR package » PHP_Archive, but has the advantage that applications created in this format will run even if the phar extension is not enabled.
In other words, even with the phar extension disabled, one can execute or include a phar-based archive. Accessing individual files within a phar archive is only possible with the phar extension unless the phar archive was created by PHP_Archive.
The phar extension is also capable of converting a phar archive from tar to zip or to phar file format in a single command:
Przykład #3 Converting a phar archive from phar to tar file format
<?php
$phar = new Phar('myphar.phar');
$pgz = $phar->convertToExecutable(Phar::TAR, Phar::GZ); // makes myphar.phar.tar.gz
?>
Phar can compress individual files or an entire archive using gzip compression or bzip2 compression, and can verify archive integrity automatically through the use of md5(), sha1(), sha256(), or sha512() signatures.
Lastly, the Phar extension is security-conscious, and disables write access to executable phar archives by default, and requires system-level disabling of the phar.readonly php.ini setting in order to create or modify phar archives. Normal tar and zip archives without an executable stub can always be created or modified using the PharData class.
If you are creating applications for distribution, you will want to read How to create Phar Archives. If you want more information on the differences between the three file formats that phar supports, you should read Phar, Tar and Zip.
If you are using phar applications, there are helpful tips in How to use Phar Archives
The word phar is a contraction of PHP and Archive and is based loosely on the jar (Java Archive) familiar to Java developers.
The implementation for Phar archives is based on the PEAR package » PHP_Archive, and the implementation details are similar, although the Phar extension is much more powerful. In addition, the Phar extension allows most PHP applications to be run unmodified while PHP_Archive-based phar archives often require extensive modification in order to work.
Instalacja/Konfiguracja
Spis treści
Wymagania
Phar requires PHP 5.2.0 or newer. Additional features require the SPL extension in order to take advantage of iteration and array access to a Phar's file contents. The phar stream does not require any additional extensions to function.
You may optionally wish to enable the zlib and bzip2 extensions to take advantage of compressed phar support. In addition, to take advantage of OpenSSL signing, the OpenSSL extension must be enabled.
Note that a bug in the zlib.deflate stream filter fixed in PHP version 5.2.6 and newer may cause truncation of gzip and bzip2-compressed phar archives.
Instalacja
The Phar extension is built into PHP as of PHP version 5.3.0. Phar may be installed via the PECL extension with previous PHP versions, and the » Phar PECL page contains further information and history.
Windows users must include the php_phar.dll file within php.ini to use this extension.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| phar.readonly | "1" | PHP_INI_ALL | |
| phar.require_hash | "1" | PHP_INI_ALL | |
| phar.extract_list | "" | PHP_INI_ALL | Available from phar 1.1.0 to 1.2.3, removed in 2.0.0. |
| phar.cache_list | "" | PHP_INI_SYSTEM | Available from phar 2.0.0. |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
phar.readonlyboolean -
This option disables creation or modification of Phar archives using the phar stream or Phar object's write support. This setting should always be enabled on production machines, as the phar extension's convenient write support could allow straightforward creation of a php-based virus when coupled with other common security vulnerabilities.
Informacja:
This setting can only be unset in php.ini due to security reasons. If phar.readonly is disabled in php.ini, the user may enable phar.readonly in a script or disable it later. If phar.readonly is enabled in php.ini, a script may harmlessly "re-enable" the INI variable, but may not disable it.
-
phar.require_hashboolean -
This option will force all opened Phar archives to contain some kind of signature (currently MD5, SHA1, SHA256 and SHA512 are supported), and will refuse to process any Phar archive that does not contain a signature.
Informacja:
This setting can only be unset in php.ini due to security reasons. If phar.require_hash is disabled in php.ini, the user may enable phar.require_hash in a script or disable it later. If phar.require_hash is enabled in php.ini, a script may harmlessly "re-enable" the INI variable, but may not disable it.
This setting does not affect reading plain tar files with the PharData class.
-
phar.extract_liststring -
This INI setting has been removed as of phar 2.0.0
Allows mappings from a full path to a phar archive or its alias to the location of its extracted files. The format of the parameter is name=archive,name2=archive2. This allows extraction of phar files to disk, and allows phar to act as a kind of mapper to extracted disk files. This is often done for performance reasons, or to assist with debugging a phar.
Przykład #1 phar.extract_list usage example
in php.ini:
phar.extract_list = archive=/full/path/to/archive/,arch2=/full/path/to/arch2
<?php
include "phar://archive/content.php";
include "phar://arch2/foo.php";
?> -
phar.cache_liststring -
This INI setting was added in phar 2.0.0
Allows mapping phar archives to be pre-parsed at web server startup, providing a performance improvement that brings running files out of a phar archive very close to the speed of running those files from a traditional disk-based installation.
Przykład #2 phar.cache_list usage example
in php.ini (windows): phar.cache_list =C:\path\to\phar1.phar;C:\path\to\phar2.phar in php.ini (unix): phar.cache_list =/path/to/phar1.phar:/path/to/phar2.phar
Typy zasobów
The Phar extension provides the phar stream, which allows accessing files contained within a phar transparently. See also the description of the Phar file format.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
| Constant | Value | Description |
|---|---|---|
Phar::NONE
(integer)
|
0x00000000 | no compression |
Phar::COMPRESSED
(integer)
|
0x0000F000 | bitmask that can be used with file flags to determine if any compression is present |
Phar::GZ
(integer)
|
0x00001000 | zlib (gzip) compression |
Phar::BZ2
(integer)
|
0x00002000 | bzip2 compression |
| Constant | Value | Description |
|---|---|---|
Phar::SAME
(integer)
|
0 | retain the same file format |
Phar::PHAR
(integer)
|
1 | phar file format |
Phar::TAR
(integer)
|
2 | tar file format |
Phar::ZIP
(integer)
|
3 | zip file format |
| Constant | Value | Description |
|---|---|---|
Phar::MD5
(integer)
|
0x0001 | signature with md5 hash algorithm |
Phar::SHA1
(integer)
|
0x0002 | signature with sha1 hash algorithm |
Phar::SHA256
(integer)
|
0x0003 | signature with sha256 hash algorithm (requires hash extension) |
Phar::SHA512
(integer)
|
0x0004 | signature with sha512 hash algorithm (requires hash extension) |
Phar::OPENSSL
(integer)
|
0x0010 | signature with OpenSSL public/private key pair. This is a true, asymmetric key signature. |
| Constant | Value | Description |
|---|---|---|
Phar::PHP
(integer)
|
1 | used to instruct the mimeoverrides parameter of Phar::webPhar() that the extension should be parsed as a PHP file |
Phar::PHPS
(integer)
|
2 | used to instruct the mimeoverrides parameter of Phar::webPhar() that the extension should be parsed as a PHP source file through highlight_file() |
Using Phar Archives
Spis treści
- Using Phar Archives: Introduction
- Using Phar Archives: the phar stream wrapper
- Using Phar Archives: the Phar and PharData class
Using Phar Archives: Introduction
Phar archives are similar in concept to Java JAR archives, but are tailored to the needs and to the flexibility of PHP applications. A Phar archive is used to distribute a complete PHP application or library in a single file. A Phar archive application is used exactly like any other PHP application:
php coolapplication.phar
Using a Phar archive library is identical to using any other PHP library:
<?php
include 'coollibrary.phar';
?>
The phar stream wrapper provides the core of the phar extension, and is explained in detail here. The phar stream wrapper allows accessing the files within a phar archive using PHP's standard file functions fopen(), opendir(), and others that work on regular files. The phar stream wrapper supports all read/write operations on both files and directories.
<?php
include 'phar://coollibrary.phar/internal/file.php';
header('Content-type: image/jpeg');
// phars can be accessed by full path or by alias
echo file_get_contents('phar:///fullpath/to/coollibrary.phar/images/wow.jpg');
?>
The Phar class implements advanced functionality for accessing files and for creating phar archives. The Phar class is explained in detail here.
<?php
try {
// open an existing phar
$p = new Phar('coollibrary.phar', 0);
// Phar extends SPL's DirectoryIterator class
foreach (new RecursiveIteratorIterator($p) as $file) {
// $file is a PharFileInfo class, and inherits from SplFileInfo
echo $file->getFileName() . "\n";
echo file_get_contents($file->getPathName()) . "\n"; // display contents;
}
if (isset($p['internal/file.php'])) {
var_dump($p['internal/file.php']->getMetadata());
}
// create a new phar - phar.readonly must be 0 in php.ini
// phar.readonly is enabled by default for security reasons.
// On production servers, Phars need never be created,
// only executed.
if (Phar::canWrite()) {
$p = new Phar('newphar.tar.phar', 0, 'newphar.tar.phar');
// make this a tar-based phar archive, compressed with gzip compression (.tar.gz)
$p = $p->convertToExecutable(Phar::TAR, Phar::GZ);
// create transaction - nothing is written to newphar.phar
// until stopBuffering() is called, although temporary storage is needed
$p->startBuffering();
// add all files in /path/to/project, saving in the phar with the prefix "project"
$p->buildFromIterator(new RecursiveIteratorIterator(new DirectoryIterator('/path/to/project')), '/path/to/');
// add a new file via the array access API
$p['file1.txt'] = 'Information';
$fp = fopen('hugefile.dat', 'rb');
// copy all data from the stream
$p['data/hugefile.dat'] = $fp;
if (Phar::canCompress(Phar::GZ)) {
$p['data/hugefile.dat']->compress(Phar::GZ);
}
$p['images/wow.jpg'] = file_get_contents('images/wow.jpg');
// any value can be saved as file-specific meta-data
$p['images/wow.jpg']->setMetadata(array('mime-type' => 'image/jpeg'));
$p['index.php'] = file_get_contents('index.php');
$p->setMetadata(array('bootstrap' => 'index.php'));
// save the phar archive to disk
$p->stopBuffering();
}
} catch (Exception $e) {
echo 'Could not open Phar: ', $e;
}
?>
In addition, verification of phar file contents can be done using any of the supported symmetric hash algorithms (MD5, SHA1, SHA256 and SHA512 if ext/hash is enabled) and using asymmetric public/private key signing using OpenSSL (new in Phar 2.0.0). To take advantage of OpenSSL signing, you need to generate a public/private key pair, and use the private key to set the signature using Phar::setSignatureAlgorithm(). In addition, the public key as extracted using this code:
<?php
$public = openssl_get_publickey(file_get_contents('private.pem'));
$pkey = '';
openssl_pkey_export($public, $pkey);
?>
As of version 2.0.0, The Phar class also provides 3 static methods, Phar::webPhar(), Phar::mungServer() and Phar::interceptFileFuncs() that are crucial to packaging up PHP applications designed for usage on regular filesystems and for web-based applications. Phar::webPhar() implements a front controller that routes HTTP calls to the correct location within the phar archive. Phar::mungServer() is used to modify the values of the $_SERVER array to trick applications that process these values. Phar::interceptFileFuncs() instructs Phar to intercept calls to fopen(), file_get_contents(), opendir(), and all of the stat-based functions (file_exists(), is_readable() and so on) and route all relative paths to locations within the phar archive.
As an example, packaging up a release of the popular phpMyAdmin application for use as a phar archive requires only this simple script and then phpMyAdmin.phar.tar.php can be accessed as a regular file from your web server after modifying the user/password:
<?php
@unlink('phpMyAdmin.phar.tar.php');
copy('phpMyAdmin-2.11.3-english.tar.gz', 'phpMyAdmin.phar.tar.php');
$a = new Phar('phpMyAdmin.phar.tar.php');
$a->startBuffering();
$a["phpMyAdmin-2.11.3-english/config.inc.php"] = '<?php
/* Servers configuration */
$i = 0;
/* Server localhost (config:root) [1] */
$i++;
$cfg[\'Servers\'][$i][\'host\'] = \'localhost\';
$cfg[\'Servers\'][$i][\'extension\'] = \'mysqli\';
$cfg[\'Servers\'][$i][\'connect_type\'] = \'tcp\';
$cfg[\'Servers\'][$i][\'compress\'] = false;
$cfg[\'Servers\'][$i][\'auth_type\'] = \'config\';
$cfg[\'Servers\'][$i][\'user\'] = \'root\';
$cfg[\'Servers\'][$i][\'password\'] = \'\';
/* End of servers configuration */
if (strpos(PHP_OS, \'WIN\') !== false) {
$cfg[\'UploadDir\'] = getcwd();
} else {
$cfg[\'UploadDir\'] = \'/tmp/pharphpmyadmin\';
@mkdir(\'/tmp/pharphpmyadmin\');
@chmod(\'/tmp/pharphpmyadmin\', 0777);
}';
$a->setStub('<?php
Phar::interceptFileFuncs();
Phar::webPhar("phpMyAdmin.phar", "phpMyAdmin-2.11.3-english/index.php");
echo "phpMyAdmin is intended to be executed from a web browser\n";
exit -1;
__HALT_COMPILER();
');
$a->stopBuffering();
?>
Using Phar Archives: the phar stream wrapper
The Phar stream wrapper fully supports fopen() for read and write (not append), unlink(), stat(), fstat(), fseek(), rename() and directory stream operations opendir() and as of version 2.0.0, rmdir() and mkdir().
Individual file compression and per-file metadata can also be manipulated in a Phar archive using stream contexts:
<?php
$context = stream_context_create(array('phar' =>
array('compress' => Phar::GZ)),
array('metadata' => array('user' => 'cellog')));
file_put_contents('phar://my.phar/somefile.php', 0, $context);
?>
The phar stream wrapper does not operate on remote files, and cannot operate on remote files, and so is allowed even when the allow_url_fopen and allow_url_include INI options are disabled.
Although it is possible to create phar archives from scratch just using stream operations, it is best to use the functionality built into the Phar class. The stream wrapper is best used for read-only operations.
Using Phar Archives: the Phar and PharData class
The Phar class supports reading and manipulation of Phar archives, as well as iteration through inherited functionality of the RecursiveDirectoryIterator class. With support for the ArrayAccess interface, files inside a Phar archive can be accessed as if they were part of an associative array.
The PharData class extends the Phar, and allows creating and modifying non-executable (data) tar and zip archives even if phar.readonly=1 in php.ini. As such, PharData::setAlias() and PharData::setStub() are both disabled as the concept of alias and stub are unique to executable phar archives.
It is important to note that when creating a Phar archive, the full path should be passed to the Phar object constructor. Relative paths will fail to initialize.
Assuming that $p is a Phar object initialized as follows:
<?php
$p = new Phar('/path/to/myphar.phar', 0, 'myphar.phar');
?>
An empty Phar archive will be created at /path/to/myphar.phar, or if /path/to/myphar.phar already exists, it will be opened again. The literal myphar.phar demonstrates the concept of an alias that can be used to reference /path/to/myphar.phar in URLs as in:
<?php
// these two calls to file_get_contents() are equivalent if
// /path/to/myphar.phar has an explicit alias of "myphar.phar"
// in its manifest, or if the phar was initialized with the
// previous example's Phar object setup
$f = file_get_contents('phar:///path/to/myphar.phar/whatever.txt');
$f = file_get_contents('phar://myphar.phar/whatever.txt');
?>
With the newly created $p Phar object, the following is possible:
- $a = $p['file.php'] creates a PharFileInfo class that refers to the contents of phar://myphar.phar/file.php
- $p['file.php'] = $v creates a new file (phar://myphar.phar/file.php), or overwrites an existing file within myphar.phar. $v can be either a string or an open file pointer, in which case the entire contents of the file will be used to create the new file. Note that $p->addFromString('file.php', $v) is functionally equivalent to the above. Also possible is to add the contents of a file with $p->addFile('/path/to/file.php', 'file.php'). Lastly, an empty directory can be created with $p->addEmptyDir('empty').
- isset($p['file.php']) can be used to determine whether phar://myphar.phar/file.php exists within myphar.phar.
- unset($p['file.php']) erases phar://myphar.phar/file.php from myphar.phar.
In addition, the Phar object is the only way to access Phar-specific metadata, through Phar::getMetadata(), and the only way to set or retrieve a Phar archive's PHP loader stub through Phar::getStub() and Phar::setStub(). Additionally, compression for the entire Phar archive at once can only be manipulated using the Phar class.
The full list of Phar object functionality is documented below.
The PharFileInfo class extends the SplFileInfo class, and adds several methods for manipulating Phar-specific details of a file contained within a Phar, such as manipulating compression and metadata.
Creating Phar Archives
Spis treści
Creating Phar Archives: Introduction
To be written fully in the near future. Before reading this, be sure to read How to use Phar Archives.
A great place to start is by reading about Phar::buildFromIterator(), and the specifics of the file format choices available for archives. A healthy understanding of what a stub is and does is crucial to phar archive creation, and so Phar::setStub() and Phar::createDefaultStub() are good places to start as well. If you are distributing a web-based application, it is crucial to know about Phar::webPhar() and related method Phar::mungServer(). Any application that accesses its own files should also consider using Phar::interceptFileFuncs().
What makes a phar a phar and not a tar or a zip?
Spis treści
- Ingredients of all Phar archives, independent of file format
- Phar file stub
- Head-to-head comparison of Phar, Tar and Zip
- Tar-based phars
- Zip-based phars
- Phar File Format
- Global Phar bitmapped flags
- Phar manifest file entry definition
- Phar Signature format
Ingredients of all Phar archives, independent of file format
All Phar archives contain three to four sections:
-
a stub
-
a manifest describing the contents
-
the file contents
-
[optional] a signature for verifying Phar integrity (phar file format only)
Phar file stub
A Phar's stub is a simple PHP file. The smallest possible stub follows:
<?php __HALT_COMPILER();
A stub must contain as a minimum, the __HALT_COMPILER(); token at its conclusion. Typically, a stub will contain loader functionality like so:
<?php
Phar::mapPhar();
include 'phar://myphar.phar/index.php';
__HALT_COMPILER();
There are no restrictions on the contents of a Phar stub, except for the requirement
that it conclude with __HALT_COMPILER();. The closing PHP tag
?>
?>
In a tar or zip-based phar archive, the stub is stored in the .phar/stub.php file. The default stub for phar-based Phar archives contains approximately 7k of code to extract the contents of the phar and execute them. See Phar::createDefaultStub() for more detail.
The phar alias is stored in a tar or zip-based phar archive in the .phar/alias.txt file as plain text.
Head-to-head comparison of Phar, Tar and Zip
What are the good and the bad things about the three supported file formats in the phar extension? This table attempts to address that question.
| Feature | Phar | Tar | Zip |
|---|---|---|---|
| Standard File Format | No | Yes | Yes |
| Can be executed without the Phar Extension [1] | Yes | No | No |
| Per-file compression | Yes | No | Yes |
| Whole-archive compression | Yes | Yes | No |
| Whole-archive signature validation | Yes | Yes | Yes (PHP 5.3.1+) |
| Web-specific application support | Yes | Yes | Yes |
| Per-file Meta-data | Yes | Yes | Yes |
| Whole-Archive Meta-data | Yes | Yes | Yes |
| Archive creation/modification [2] | Yes | Yes | Yes |
| Full support for all stream wrapper functions | Yes | Yes | Yes |
| Can be created/modified even if phar.readonly=1 [3] | No | Yes | Yes |
[1] PHP can only directly access the contents of a Phar archive without the Phar extension if it is using a stub that extracts the contents of the phar archive. The stub created by Phar::createDefaultStub() extracts the phar archive and runs its contents from a temporary directory if no phar extension is found.
[2] All write access requires phar.readonly to be disabled in php.ini or on the command-line directly.
[3] Only tar and zip archives without .phar in their filename and without an executable stub .phar/stub.php can be created if phar.readonly=1.
Tar-based phars
Archives based on the tar file format follow the more modern USTAR file format. The design of the tar file header makes them more efficient to access than the zip file format, and almost as efficient as the phar file format. File names are limited to 255 bytes, including full path within the phar archive. There is no limit on the number of files within a tar-based phar archive. These archives can fully compressed in gzip or bzip2 format and still be executed by the Phar extension.
To compress an entire archive, use Phar::compress(). To decompress an entire archive, use Phar::decompress().
Zip-based phars
Archives based on the zip file format support several features built into the zip file format. Per-file and whole-archive metadata is stored in the zip file comment and zip archive comment as a serialized string. Pre-existing zip comments will be successfully read as a string. Per-file compression read/write is supported with zlib compression, and read access is supported with bzip2 compression. There is no limit on the number of files within a zip-based phar archive. Empty directories are stored in the zip archive as files with a trailing slash like my/directory/
Phar File Format
The phar file format is literally laid out as stub/manifest/contents/signature, and stores the crucial information of what is included in the phar archive in its manifest.
The Phar manifest is a highly optimized format that allows per-file specification of file compression, file permissions, and even user-defined meta-data such as file user or group. All values greater than 1 byte are stored in little-endian byte order, with the exception of the API version, which for historical reasons is stored as 3 nibbles in big-endian order.
All unused flags are reserved for future use, and must not be used to store custom information. Use the per-file meta-data facility to store customized information about particular files.
The basic file format of a Phar archive manifest is as follows:
| Size in bytes | Description |
|---|---|
| 4 bytes | Length of manifest in bytes (1 MB limit) |
| 4 bytes | Number of files in the Phar |
| 2 bytes | API version of the Phar manifest (currently 1.0.0) |
| 4 bytes | Global Phar bitmapped flags |
| 4 bytes | Length of Phar alias |
| ?? | Phar alias (length based on previous) |
| 4 bytes | Length of Phar metadata (0 for none) |
| ?? | Serialized Phar Meta-data, stored in serialize() format |
| at least 24 * number of entries bytes | entries for each file |
Global Phar bitmapped flags
Here are the bitmapped flags currently recognized by the Phar extension for the global Phar flat bitmap:
| Value | Description |
|---|---|
| 0x00010000 | If set, this Phar contains a verification signature |
| 0x00001000 | If set, this Phar contains at least 1 file that is compressed with zlib compression |
| 0x00002000 | If set, this Phar contains at least 1 file that is compressed with bzip compression |
Phar manifest file entry definition
Each file in the manifest contains the following information:
| Size in bytes | Description |
|---|---|
| 4 bytes | Filename length in bytes |
| ?? | Filename (length specified in previous) |
| 4 bytes | Un-compressed file size in bytes |
| 4 bytes | Unix timestamp of file |
| 4 bytes | Compressed file size in bytes |
| 4 bytes | CRC32 checksum of un-compressed file contents |
| 4 bytes | Bit-mapped File-specific flags |
| 4 bytes | Serialized File Meta-data length (0 for none) |
| ?? | Serialized File Meta-data, stored in serialize() format |
Note that as of API version 1.1.1, empty directories are stored as filenames with a trailing slash like my/directory/
The File-specific bitmap values recognized are:
| Value | Description |
|---|---|
| 0x000001FF | These bits are reserved for defining specific file permissions of a file. Permissions are used for fstat() and can be used to recreate desired permissions upon extraction. |
| 0x00001000 | If set, this file is compressed with zlib compression |
| 0x00002000 | If set, this file is compressed with bzip compression |
Phar Signature format
Phars containing a signature always have the signature appended to the end of the Phar archive after the loader, manifest, and file contents. The two signature formats supported at this time are MD5 and SHA1.
| Length in bytes | Description |
|---|---|
| 16 or 20 bytes | The actual signature, 20 bytes for an SHA1 signature, 16 bytes for an MD5 signature, 32 bytes for an SHA256 signature, and 64 bytes for an SHA512 signature. |
| 4 bytes | Signature flags. 0x0001 is used to define an MD5 signature, 0x0002 is used to define an SHA1 signature, 0x0004 is used to define an SHA256 signature, and 0x0008 is used to define an SHA512 signature. The SHA256 and SHA512 signature support was introduced with API version 1.1.0. |
| 4 bytes | Magic GBMB used to define the presence of a signature. |
The Phar class
(No version information available, might only be in SVN)
Wstęp
The Phar class provides a high-level interface to accessing and creating phar archives.
Krótki opis klasy
$format = 9021976
[, int $compression = 9021976
[, string $extension
]]] )$format = 9021976
[, int $compression = 9021976
[, string $extension
]]] )$alias
[, string $index = "index.php"
[, string $f404
[, array $mimetypes
[, array $rewrites
]]]]] )Phar::addEmptyDir
(Unknown)
Phar::addEmptyDir — Add an empty directory to the phar archive
Opis
$dirname
)Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
With this method, an empty directory is created with path dirname. This method is similar to ZipArchive::addEmptyDir().
Parametry
-
dirname -
The name of the empty directory to create in the phar archive
Zwracane wartości
no return value, exception is thrown on failure.
Przykłady
Przykład #1 A Phar::addEmptyDir() example
<?php
try {
$a = new Phar('/path/to/phar.phar');
$a->addEmptyDir('/full/path/to/file');
// demonstrates how this file is stored
$b = $a['full/path/to/file']->isDir();
} catch (Exception $e) {
// handle errors here
}
?>
Zobacz też:
- PharData::addEmptyDir() - Add an empty directory to the tar/zip archive
- Phar::addFile() - Add a file from the filesystem to the phar archive
- Phar::addFromString() - Add a file from the filesystem to the phar archive
Phar::addFile
(Unknown)
Phar::addFile — Add a file from the filesystem to the phar archive
Opis
$file
[, string $localname
] )Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
With this method, any file or URL can be added to the phar archive. If the optional second parameter localname is specified, the file will be stored in the archive with that name, otherwise the file parameter is used as the path to store within the archive. URLs must have a localname or an exception is thrown. This method is similar to ZipArchive::addFile().
Parametry
-
file -
Full or relative path to a file on disk to be added to the phar archive.
-
localname -
Path that the file will be stored in the archive.
Zwracane wartości
no return value, exception is thrown on failure.
Przykłady
Przykład #1 A Phar::addFile() example
<?php
try {
$a = new Phar('/path/to/phar.phar');
$a->addFile('/full/path/to/file');
// demonstrates how this file is stored
$b = $a['full/path/to/file']->getContent();
$a->addFile('/full/path/to/file', 'my/file.txt');
$c = $a['my/file.txt']->getContent();
// demonstrate URL usage
$a->addFile('http://www.example.com', 'example.html');
} catch (Exception $e) {
// handle errors here
}
?>
Zobacz też:
- Phar::offsetSet() - set the contents of an internal file to those of an external file
- PharData::addFile() - Add a file from the filesystem to the tar/zip archive
- Phar::addFromString() - Add a file from the filesystem to the phar archive
- Phar::addEmptyDir() - Add an empty directory to the phar archive
Phar::addFromString
(Unknown)
Phar::addFromString — Add a file from the filesystem to the phar archive
Opis
$localname
, string $contents
)Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
With this method, any string can be added to the phar archive. The file will be stored in the archive with localname as its path. This method is similar to ZipArchive::addFromString().
Parametry
-
localname -
Path that the file will be stored in the archive.
-
contents -
The file contents to store
Zwracane wartości
no return value, exception is thrown on failure.
Przykłady
Przykład #1 A Phar::addFromString() example
<?php
try {
$a = new Phar('/path/to/phar.phar');
$a->addFromString('path/to/file.txt', 'my simple file');
$b = $a['path/to/file.txt']->getContent();
// to add contents from a stream handle for large files, use offsetSet()
$c = fopen('/path/to/hugefile.bin');
$a['largefile.bin'] = $c;
fclose($c);
} catch (Exception $e) {
// handle errors here
}
?>
Zobacz też:
- Phar::offsetSet() - set the contents of an internal file to those of an external file
- PharData::addFromString() - Add a file from the filesystem to the tar/zip archive
- Phar::addFile() - Add a file from the filesystem to the phar archive
- Phar::addEmptyDir() - Add an empty directory to the phar archive
Phar::apiVersion
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::apiVersion — Returns the api version
Opis
Return the API version of the phar file format that will be used when creating phars. The Phar extension supports reading API version 1.0.0 or newer. API version 1.1.0 is required for SHA-256 and SHA-512 hash, and API version 1.1.1 is required to store empty directories.
Parametry
Zwracane wartości
The API version string as in "1.0.0".
Przykłady
Przykład #1 A Phar::apiVersion() example
<?php
echo Phar::apiVersion();
?>
Powyższy przykład wyświetli:
1.1.1
Phar::buildFromDirectory
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::buildFromDirectory — Construct a phar archive from the files within a directory.
Opis
$base_dir
[, string $regex
] )Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
Populate a phar archive from directory contents. The optional second parameter is a regular expression (pcre) that is used to exclude files. Any filename that matches the regular expression will be included, all others will be excluded. For more fine-grained control, use Phar::buildFromIterator().
Parametry
-
base_dir -
The full or relative path to the directory that contains all files to add to the archive.
-
regex -
An optional pcre regular expression that is used to filter the list of files. Only file paths matching the regular expression will be included in the archive.
Zwracane wartości
Phar::buildFromDirectory() returns an associative array mapping internal path of file to the full path of the file on the filesystem.
Błędy/Wyjątki
This method throws BadMethodCallException when unable to instantiate the internal directory iterators, or a PharException if there were errors saving the phar archive.
Przykłady
Przykład #1 A Phar::buildFromDirectory() example
<?php
// create with alias "project.phar"
$phar = new Phar('project.phar', 0, 'project.phar');
// add all files in the project
$phar->buildFromDirectory(dirname(__FILE__) . '/project');
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
$phar2 = new Phar('project2.phar', 0, 'project2.phar');
// add all files in the project, only include php files
$phar2->buildFromDirectory(dirname(__FILE__) . '/project', '/\.php$/');
$phar2->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
?>
Phar::buildFromIterator
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::buildFromIterator — Construct a phar archive from an iterator.
Opis
Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
Populate a phar archive from an iterator. Two styles of iterators are supported, iterators that map the filename within the phar to the name of a file on disk, and iterators like DirectoryIterator that return SplFileInfo objects. For iterators that return SplFileInfo objects, the second parameter is required.
Parametry
-
iter -
Any iterator that either associatively maps phar file to location or returns SplFileInfo objects
-
base_directory -
For iterators that return SplFileInfo objects, the portion of each file's full path to remove when adding to the phar archive
Zwracane wartości
Phar::buildFromIterator() returns an associative array mapping internal path of file to the full path of the file on the filesystem.
Przykłady
Przykład #1 A Phar::buildFromIterator() with SplFileInfo
For most phar archives, the archive will reflect an actual directory layout, and the second style is the most useful. For instance, to create a phar archive containing the files in this sample directory layout:
/path/to/project/
config/
dist.xml
debug.xml
lib/
file1.php
file2.php
src/
processthing.php
www/
index.php
cli/
index.php
This code could be used to add these files to the "project.phar" phar archive:
<?php
// create with alias "project.phar"
$phar = new Phar('project.phar', 0, 'project.phar');
$phar->buildFromIterator(
new RecursiveIteratorIterator(
new RecursiveDirectoryIterator('/path/to/project')),
'/path/to/project');
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
?>
The file project.phar can then be used immediately. Phar::buildFromIterator() does not set values such as compression, metadata, and this can be done after creating the phar archive.
As an interesting note, Phar::buildFromIterator() can also be used to copy the contents of an existing phar archive, as the Phar object descends from DirectoryIterator:
<?php
// create with alias "project.phar"
$phar = new Phar('project.phar', 0, 'project.phar');
$phar->buildFromIterator(
new RecursiveIteratorIterator(
new Phar('/path/to/anotherphar.phar')),
'phar:///path/to/anotherphar.phar/path/to/project');
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
?>
Przykład #2 A Phar::buildFromIterator() with other iterators
The second form of the iterator can be used with any iterator that returns a key => value mapping, such as an ArrayIterator:
<?php
// create with alias "project.phar"
$phar = new Phar('project.phar', 0, 'project.phar');
$phar->buildFromIterator(
new ArrayIterator(
array(
'internal/file.php' => dirname(__FILE__) . '/somefile.php',
'another/file.jpg' => fopen('/path/to/bigfile.jpg', 'rb'),
)));
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
?>
Błędy/Wyjątki
This method returns UnexpectedValueException when the
iterator returns incorrect values, such as an integer key instead of a
string, a BadMethodCallException when an
SplFileInfo-based iterator is passed without a base_directory
parameter, or a PharException if there were errors
saving the phar archive.
Zobacz też:
- Phar::buildFromDirectory() - Construct a phar archive from the files within a directory.
Phar::canCompress
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::canCompress — Returns whether phar extension supports compression using either zlib or bzip2
Opis
$type = 0
] )This should be used to test whether compression is possible prior to loading a phar archive containing compressed files.
Parametry
-
type -
Either Phar::GZ or Phar::BZ2 can be used to test whether compression is possible with a specific compression algorithm (zlib or bzip2).
Zwracane wartości
TRUE if compression/decompression is available, FALSE if not.
Przykłady
Przykład #1 A Phar::canCompress() example
<?php
if (Phar::canCompress()) {
echo file_get_contents('phar://compressedphar.phar/internal/file.txt');
} else {
echo 'no compression available';
}
?>
Zobacz też:
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressFiles() - Compresses all files in the current Phar archive
- Phar::decompressFiles() - Decompresses all files in the current Phar archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::convertToExecutable() - Convert a phar archive to another executable phar archive file format
- Phar::convertToData() - Convert a phar archive to a non-executable tar or zip file
Phar::canWrite
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::canWrite — Returns whether phar extension supports writing and creating phars
Opis
This static method determines whether write access has been disabled in the system php.ini via the phar.readonly ini variable.
Parametry
Zwracane wartości
TRUE if write access is enabled, FALSE if it is disabled.
Przykłady
Przykład #1 A Phar::canWrite() example
<?php
if (Phar::canWrite()) {
file_put_contents('phar://myphar.phar/file.txt', 'hi there');
}
?>
Phar::compress
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::compress — Compresses the entire Phar archive using Gzip or Bzip2 compression
Opis
$compression
[, string $extension
] )Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
For tar-based and phar-based phar archives, this method compresses the entire archive using gzip compression or bzip2 compression. The resulting file can be processed with the gunzip command/bunzip command, or accessed directly and transparently with the Phar extension.
For Zip-based phar archives, this method fails with an exception. The zlib extension must be enabled to compress with gzip compression, the bzip2 extension must be enabled in order to compress with bzip2 compression. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed.
In addition, this method automatically renames the archive, appending .gz, .bz2 or removing the extension if passed Phar::NONE to remove compression. Alternatively, a file extension may be specified with the second parameter.
Parametry
-
compression -
Compression must be one of Phar::GZ, Phar::BZ2 to add compression, or Phar::NONE to remove compression.
-
extension -
By default, the extension is .phar.gz or .phar.bz2 for compressing phar archives, and .phar.tar.gz or .phar.tar.bz2 for compressing tar archives. For decompressing, the default file extensions are .phar and .phar.tar.
Zwracane wartości
Returns a Phar object.
Błędy/Wyjątki
Throws BadMethodCallException if the phar.readonly INI variable is on, the zlib extension is not available, or the bzip2 extension is not enabled.
Przykłady
Przykład #1 A Phar::compress() example
<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p1 = $p->compress(Phar::GZ); // copies to /path/to/my.phar.gz
$p2 = $p->compress(Phar::BZ2); // copies to /path/to/my.phar.bz2
$p3 = $p2->compress(Phar::NONE); // exception: /path/to/my.phar already exists
?>
Zobacz też:
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- PharData::compress() - Compresses the entire tar/zip archive using Gzip or Bzip2 compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::decompress() - Decompresses the entire Phar archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::compressFiles() - Compresses all files in the current Phar archive
- Phar::decompressFiles() - Decompresses all files in the current Phar archive
Phar::compressAllFilesBZIP2
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::compressAllFilesBZIP2 — Compresses all files in the current Phar archive using Bzip2 compression
Opis
Informacja:
Ta metoda została usunięta z rozszerzenia phar w wersji 2.0.0. Dostępne są zastępcze implementacje: Phar::compress(), Phar::decompress(), Phar::compressFiles() i Phar::decompressFiles().
Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
This method compresses all files in the Phar archive using bzip2 compression. The bzip2 extension must be enabled to take advantage of this feature. In addition, if any files are already compressed using gzip compression, the zlib extension must be enabled in order to decompress the files prior to re-compressing with bzip2 compression. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Błędy/Wyjątki
Throws BadMethodCallException if the phar.readonly INI variable is on, the bzip2 extension is not available, or if any files are compressed using gzip compression and the zlib extension is not enabled.
Przykłady
Przykład #1 A Phar::compressAllFilesBZIP2() example
<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressedBZIP2());
var_dump($file->isCompressedGZ());
}
$p->compressAllFilesBZIP2();
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressedBZIP2());
var_dump($file->isCompressedGZ());
}
?>
Powyższy przykład wyświetli:
string(10) "myfile.txt" bool(false) bool(false) bool(false) string(11) "myfile2.txt" bool(false) bool(false) bool(false) string(10) "myfile.txt" bool(true) bool(true) bool(false) string(11) "myfile2.txt" bool(true) bool(true) bool(false)
Zobacz też:
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressedBZIP2() - Returns whether the entry is compressed using bzip2
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::isCompressedGZ() - Returns whether the entry is compressed using gz
- PharFileInfo::setCompressedBZIP2() - Compresses the current Phar entry within the phar using Bzip2 compression
- PharFileInfo::setUncompressed() - Uncompresses the current Phar entry within the phar, if it is compressed
- PharFileInfo::setCompressedGZ() - Compresses the current Phar entry within the phar using gz compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressAllFilesGZ() - Compresses all files in the current Phar archive using Gzip compression
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::uncompressAllFiles() - Uncompresses all files in the current Phar archive
Phar::compressAllFilesGZ
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::compressAllFilesGZ — Compresses all files in the current Phar archive using Gzip compression
Opis
Informacja:
Ta metoda została usunięta z rozszerzenia phar w wersji 2.0.0. Dostępne są zastępcze implementacje: Phar::compress(), Phar::decompress(), Phar::compressFiles() i Phar::decompressFiles().
Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
For tar-based phar archives, this method compresses the entire archive using gzip compression. The resulting file can be processed with the gunzip command, or accessed directly and transparently with the Phar extension.
For Zip-based and phar-based phar archives, this method compresses all files in the Phar archive using gzip compression. The zlib extension must be enabled to take advantage of this feature. In addition, if any files are already compressed using bzip2 compression, the bzip2 extension must be enabled in order to decompress the files prior to re-compressing with gzip compression. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Błędy/Wyjątki
Throws BadMethodCallException if the phar.readonly INI variable is on, the zlib extension is not available, or if any files are compressed using bzip2 compression and the bzip2 extension is not enabled.
Przykłady
Przykład #1 A Phar::compressAllFilesGZ() example
<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressedBZIP2());
var_dump($file->isCompressedGZ());
}
$p->compressAllFilesGZ();
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressedBZIP2());
var_dump($file->isCompressedGZ());
}
?>
Powyższy przykład wyświetli:
string(10) "myfile.txt" bool(false) bool(false) bool(false) string(11) "myfile2.txt" bool(false) bool(false) bool(false) string(10) "myfile.txt" bool(true) bool(false) bool(true) string(11) "myfile2.txt" bool(true) bool(false) bool(true)
Zobacz też:
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressedBZIP2() - Returns whether the entry is compressed using bzip2
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::isCompressedGZ() - Returns whether the entry is compressed using gz
- PharFileInfo::setCompressedBZIP2() - Compresses the current Phar entry within the phar using Bzip2 compression
- PharFileInfo::setUncompressed() - Uncompresses the current Phar entry within the phar, if it is compressed
- PharFileInfo::setCompressedGZ() - Compresses the current Phar entry within the phar using gz compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressAllFilesBZIP2() - Compresses all files in the current Phar archive using Bzip2 compression
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::uncompressAllFiles() - Uncompresses all files in the current Phar archive
Phar::compressFiles
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::compressFiles — Compresses all files in the current Phar archive
Opis
$compression
)Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
For tar-based phar archives, this method throws a BadMethodCallException, as compression of individual files within a tar archive is not supported by the file format. Use Phar::compress() to compress an entire tar-based phar archive.
For Zip-based and phar-based phar archives, this method compresses all files in the Phar archive using the specified compression. The zlib or bzip2 extensions must be enabled to take advantage of this feature. In addition, if any files are already compressed using bzip2/zlib compression, the respective extension must be enabled in order to decompress the files prior to re-compressing. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed.
Parametry
-
compression -
Compression must be one of Phar::GZ, Phar::BZ2 to add compression, or Phar::NONE to remove compression.
Zwracane wartości
Nie jest zwracana żadna wartość.
Błędy/Wyjątki
Throws BadMethodCallException if the phar.readonly INI variable is on, the zlib extension is not available, or if any files are compressed using bzip2 compression and the bzip2 extension is not enabled.
Przykłady
Przykład #1 A Phar::compressFiles() example
<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressed(Phar::BZ2));
var_dump($file->isCompressed(Phar::GZ));
}
$p->compressFiles(Phar::GZ);
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressed(Phar::BZ2));
var_dump($file->isCompressed(Phar::GZ));
}
?>
Powyższy przykład wyświetli:
string(10) "myfile.txt" bool(false) bool(false) bool(false) string(11) "myfile2.txt" bool(false) bool(false) bool(false) string(10) "myfile.txt" int(4096) bool(false) bool(true) string(11) "myfile2.txt" int(4096) bool(false) bool(true)
Zobacz też:
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::decompressFiles() - Decompresses all files in the current Phar archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::compress() - Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::decompress() - Decompresses the entire Phar archive
Phar::__construct
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::__construct — Construct a Phar archive object
Opis
$fname
[, int $flags
[, string $alias
]] )Parametry
-
fname -
Path to an existing Phar archive or to-be-created archive
-
flags -
Flags to pass to parent class RecursiveDirectoryIterator.
-
alias -
Alias with which this Phar archive should be referred to in calls to stream functionality.
Błędy/Wyjątki
Throws BadMethodCallException if called twice, UnexpectedValueException if the phar archive can't be opened.
Przykłady
Przykład #1 A Phar::__construct() example
<?php
try {
$p = new Phar('/path/to/my.phar', CURRENT_AS_FILEINFO | KEY_AS_FILENAME,
'my.phar');
} catch (UnexpectedValueException $e) {
die('Could not open my.phar');
} catch (BadMethodCallException $e) {
echo 'technically, this cannot happen';
}
// this works now
echo file_get_contents('phar://my.phar/example.txt');
// and works as if we had typed
echo file_get_contents('phar:///path/to/my.phar/example.txt');
?>
Phar::convertToData
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::convertToData — Convert a phar archive to a non-executable tar or zip file
Opis
$format = 9021976
[, int $compression = 9021976
[, string $extension
]]] )This method is used to convert an executable phar archive to either a tar or zip file. To make the tar or zip non-executable, the phar stub and phar alias files are removed from the newly created archive.
If no changes are specified, this method throws a BadMethodCallException if the archive is in phar file format. For archives in tar or zip file format, this method converts the archive to a non-executable archive.
If successful, the method creates a new archive on disk and returns a PharData object. The old archive is not removed from disk, and should be done manually after the process has finished.
Parametry
-
format -
This should be one of Phar::TAR or Phar::ZIP. If set to
NULL, the existing file format will be preserved. -
compression -
This should be one of Phar::NONE for no whole-archive compression, Phar::GZ for zlib-based compression, and Phar::BZ2 for bzip-based compression.
-
extension -
This parameter is used to override the default file extension for a converted archive. Note that .phar cannot be used anywhere in the filename for a non-executable tar or zip archive.
If converting to a tar-based phar archive, the default extensions are .tar, .tar.gz, and .tar.bz2 depending on specified compression. For zip-based archives, the default extension is .zip.
Zwracane wartości
The method returns a PharData object on success and throws an exception on failure.
Błędy/Wyjątki
This method throws BadMethodCallException when unable to compress, an unknown compression method has been specified, the requested archive is buffering with Phar::startBuffering() and has not concluded with Phar::stopBuffering(), and a PharException if any problems are encountered during the phar creation process.
Przykłady
Przykład #1 A Phar::convertToData() example
Using Phar::convertToData():
<?php
try {
$tarphar = new Phar('myphar.phar.tar');
// note that myphar.phar.tar is *not* unlinked
// convert it to the non-executable tar file format
// creates myphar.tar
$tar = $tarphar->convertToData();
// convert to non-executable zip format, creates myphar.zip
$zip = $tarphar->convertToData(Phar::ZIP);
// create myphar.tbz
$tgz = $tarphar->convertToData(Phar::TAR, Phar::BZ2, '.tbz');
// creates myphar.phar.tgz
$phar = $tarphar->convertToData(Phar::PHAR); // throws exception
} catch (Exception $e) {
// handle the error here
}
?>
Zobacz też:
- Phar::convertToExecutable() - Convert a phar archive to another executable phar archive file format
- PharData::convertToExecutable() - Convert a non-executable tar/zip archive to an executable phar archive
- PharData::convertToData() - Convert a phar archive to a non-executable tar or zip file
Phar::convertToExecutable
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::convertToExecutable — Convert a phar archive to another executable phar archive file format
Opis
$format = 9021976
[, int $compression = 9021976
[, string $extension
]]] )Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
This method is used to convert a phar archive to another file format. For instance, it can be used to create a tar-based executable phar archive from a zip-based executable phar archive, or from an executable phar archive in the phar file format. In addition, it can be used to apply whole-archive compression to a tar or phar-based archive.
If no changes are specified, this method throws a BadMethodCallException.
If successful, the method creates a new archive on disk and returns a Phar object. The old archive is not removed from disk, and should be done manually after the process has finished.
Parametry
-
format -
This should be one of Phar::PHAR, Phar::TAR, or Phar::ZIP. If set to
NULL, the existing file format will be preserved. -
compression -
This should be one of Phar::NONE for no whole-archive compression, Phar::GZ for zlib-based compression, and Phar::BZ2 for bzip-based compression.
-
extension -
This parameter is used to override the default file extension for a converted archive. Note that all zip- and tar-based phar archives must contain .phar in their file extension in order to be processed as a phar archive.
If converting to a phar-based archive, the default extensions are .phar, .phar.gz, or .phar.bz2 depending on the specified compression. For tar-based phar archives, the default extensions are .phar.tar, .phar.tar.gz, and .phar.tar.bz2. For zip-based phar archives, the default extension is .phar.zip.
Zwracane wartości
The method returns a Phar object on success and throws an exception on failure.
Błędy/Wyjątki
This method throws BadMethodCallException when unable to compress, an unknown compression method has been specified, the requested archive is buffering with Phar::startBuffering() and has not concluded with Phar::stopBuffering(), an UnexpectedValueException if write support is disabled, and a PharException if any problems are encountered during the phar creation process.
Przykłady
Przykład #1 A Phar::convertToExecutable() example
Using Phar::convertToExecutable():
<?php
try {
$tarphar = new Phar('myphar.phar.tar');
// convert it to the phar file format
// note that myphar.phar.tar is *not* unlinked
$phar = $tarphar->convertToExecutable(Phar::PHAR); // creates myphar.phar
$phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
// creates myphar.phar.tgz
$compressed = $phar->convertToExecutable(Phar::TAR, Phar::GZ, '.phar.tgz');
} catch (Exception $e) {
// handle the error here
}
?>
Zobacz też:
- Phar::convertToData() - Convert a phar archive to a non-executable tar or zip file
- PharData::convertToExecutable() - Convert a non-executable tar/zip archive to an executable phar archive
- PharData::convertToData() - Convert a phar archive to a non-executable tar or zip file
Phar::copy
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::copy — Copy a file internal to the phar archive to another new file within the phar
Opis
$oldfile
, string $newfile
)Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
Copy a file internal to the phar archive to another new file within the phar. This is an object-oriented alternative to using copy() with the phar stream wrapper.
Parametry
-
oldfile -
-
newfile -
Zwracane wartości
returns TRUE on success, but it is safer to encase method call in a
try/catch block and assume success if no exception is thrown.
Błędy/Wyjątki
throws UnexpectedValueException if the source file does not exist, the destination file already exists, write access is disabled, opening either file fails, reading the source file fails, or a PharException if writing the changes to the phar fails.
Przykłady
Przykład #1 A Phar::copy() example
This example shows using Phar::copy() and the equivalent stream wrapper performance of the same thing. The primary difference between the two approaches is error handling. All Phar methods throw exceptions, whereas the stream wrapper uses trigger_error().
<?php
try {
$phar = new Phar('myphar.phar');
$phar['a'] = 'hi';
$phar->copy('a', 'b');
echo $phar['b']; // outputs "hi"
} catch (Exception $e) {
// handle error
}
// the stream wrapper equivalent of the above code.
// E_WARNINGS are triggered on error rather than exceptions.
copy('phar://myphar.phar/a', 'phar//myphar.phar/c');
echo file_get_contents('phar://myphar.phar/c'); // outputs "hi"
?>
Phar::count
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::count — Returns the number of entries (files) in the Phar archive
Opis
Parametry
Zwracane wartości
The number of files contained within this phar, or 0 (the number zero) if none.
Przykłady
Przykład #1 A Phar::count() example
<?php
// make sure it doesn't exist
@unlink('brandnewphar.phar');
try {
$p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
} catch (Exception $e) {
echo 'Could not create phar:', $e;
}
echo 'The new phar has ' . $p->count() . " entries\n";
$p['file.txt'] = 'hi';
echo 'The new phar has ' . $p->count() . " entries\n";
?>
Powyższy przykład wyświetli:
The new phar has 0 entries The new phar has 1 entries
Phar::createDefaultStub
(Unknown)
Phar::createDefaultStub — Create a phar-file format specific stub
Opis
$indexfile
[, string $webindexfile
]] )This method is intended for creation of phar-file format-specific stubs, and is not intended for use with tar- or zip-based phar archives.
Phar archives contain a bootstrap loader, or stub written in PHP that is executed when the archive is executed in PHP either via include:
<?php
include 'myphar.phar';
?>
php myphar.phar
This method provides a simple and easy method to create a stub that will run a startup file from the phar archive. In addition, different files can be specified for running the phar archive from the command line versus through a web server. The loader stub also calls Phar::interceptFileFuncs() to allow easy bundling of a PHP application that accesses the file system. If the phar extension is not present, the loader stub will extract the phar archive to a temporary directory and then operate on the files. A shutdown function erases the temporary files on exit.
Zwracane wartości
Returns a string containing the contents of a customized bootstrap loader (stub) that allows the created Phar archive to work with or without the Phar extension enabled.
Błędy/Wyjątki
Throws UnexpectedValueException if either parameter is longer than 400 bytes.
Przykłady
Przykład #1 A Phar::createDefaultStub() example
<?php
try {
$phar = new Phar('myphar.phar');
$phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
} catch (Exception $e) {
// handle errors
}
?>
Zobacz też:
- Phar::setStub() - Used to set the PHP loader or bootstrap stub of a Phar archive
- Phar::getStub() - Return the PHP loader or bootstrap stub of a Phar archive
Phar::decompress
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::decompress — Decompresses the entire Phar archive
Opis
$extension
] )Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
For tar-based and phar-based phar archives, this method decompresses the entire archive.
For Zip-based phar archives, this method fails with an exception. The zlib extension must be enabled to decompress an archive compressed with gzip compression, and the bzip2 extension must be enabled in order to decompress an archive compressed with bzip2 compression. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed.
In addition, this method automatically changes the file extension of the archive, .phar by default for phar archives, or .phar.tar for tar-based phar archives. Alternatively, a file extension may be specified with the second parameter.
Parametry
-
extension -
For decompressing, the default file extensions are .phar and .phar.tar. Use this parameter to specify another file extension. Be aware that all executable phar archives must contain .phar in their filename.
Zwracane wartości
A Phar object is returned.
Błędy/Wyjątki
Throws BadMethodCallException if the phar.readonly INI variable is on, the zlib extension is not available, or the bzip2 extension is not enabled.
Przykłady
Przykład #1 A Phar::decompress() example
<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar.gz');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p3 = $p2->decompress(); // creates /path/to/my.phar
?>
Zobacz też:
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- PharData::compress() - Compresses the entire tar/zip archive using Gzip or Bzip2 compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compress() - Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::compressFiles() - Compresses all files in the current Phar archive
- Phar::decompressFiles() - Decompresses all files in the current Phar archive
Phar::decompressFiles
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::decompressFiles — Decompresses all files in the current Phar archive
Opis
Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
For tar-based phar archives, this method throws a BadMethodCallException, as compression of individual files within a tar archive is not supported by the file format. Use Phar::compress() to compress an entire tar-based phar archive.
For Zip-based and phar-based phar archives, this method decompresses all files in the Phar archive. The zlib or bzip2 extensions must be enabled to take advantage of this feature if any files are compressed using bzip2/zlib compression. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Błędy/Wyjątki
Throws BadMethodCallException if the phar.readonly INI variable is on, the zlib extension is not available, or if any files are compressed using bzip2 compression and the bzip2 extension is not enabled.
Przykłady
Przykład #1 A Phar::decompressFiles() example
<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p->compressFiles(Phar::GZ);
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressed(Phar::BZ2));
var_dump($file->isCompressed(Phar::GZ));
}
$p->decompressFiles();
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressed(Phar::BZ2));
var_dump($file->isCompressed(Phar::GZ));
}
?>
Powyższy przykład wyświetli:
string(10) "myfile.txt" int(4096) bool(false) bool(true) string(11) "myfile2.txt" int(4096) bool(false) bool(true) string(10) "myfile.txt" bool(false) bool(false) bool(false) string(11) "myfile2.txt" bool(false) bool(false) bool(false)
Zobacz też:
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressFiles() - Compresses all files in the current Phar archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::compress() - Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::decompress() - Decompresses the entire Phar archive
Phar::delMetadata
(PHP >= 5.3.0, PECL phar >= 1.2.0)
Phar::delMetadata — Deletes the global metadata of the phar
Opis
Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
Deletes the global metadata of the phar
Parametry
Zwracane wartości
returns TRUE on success, but it is better to check for thrown exception,
and assume success if none is thrown.
Błędy/Wyjątki
Throws PharException if errors occur while flushing changes to disk.
Przykłady
Przykład #1 A Phar::delMetaData() example
<?php
try {
$phar = new Phar('myphar.phar');
var_dump($phar->getMetadata());
$phar->setMetadata("hi there");
var_dump($phar->getMetadata());
$phar->delMetadata();
var_dump($phar->getMetadata());
} catch (Exception $e) {
// handle errors
}
?>
Powyższy przykład wyświetli:
NULL string(8) "hi there" NULL
Zobacz też:
- Phar::getMetadata() - Returns phar archive meta-data
- Phar::setMetadata() - Sets phar archive meta-data
- Phar::hasMetadata() - Returns whether phar has global meta-data
Phar::delete
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::delete — Delete a file within a phar archive
Opis
$entry
)Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
Delete a file within an archive. This is the functional equivalent of calling unlink() on the stream wrapper equivalent, as shown in the example below.
Parametry
-
entry -
Path within an archive to the file to delete.
Zwracane wartości
returns TRUE on success, but it is better to check for thrown exception,
and assume success if none is thrown.
Błędy/Wyjątki
Throws PharException if errors occur while flushing changes to disk.
Przykłady
Przykład #1 A Phar::delete() example
<?php
try {
$phar = new Phar('myphar.phar');
$phar->delete('unlink/me.php');
// this is equivalent to:
unlink('phar://myphar.phar/unlink/me.php');
} catch (Exception $e) {
// handle errors
}
?>
Zobacz też:
- PharData::delete() - Delete a file within a tar/zip archive
- Phar::unlinkArchive() - Completely remove a phar archive from disk and from memory
Phar::extractTo
(Unknown)
Phar::extractTo — Extract the contents of a phar archive to a directory
Opis
$pathto
[, string|array $files
[, bool $overwrite = false
]] )Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
Extract all files within a phar archive to disk. Extracted files and directories preserve permissions as stored in the archive. The optional parameters allow optional control over which files are extracted, and whether existing files on disk can be overwritten. The second parameter files can be either the name of a file or directory to extract, or an array of names of files and directories to extract. By default, this method will not overwrite existing files, the third parameter can be set to true to enable overwriting of files. This method is similar to ZipArchive::extractTo().
Parametry
-
pathto -
Path within an archive to the file to delete.
-
files -
The name of a file or directory to extract, or an array of files/directories to extract
-
overwrite -
Set to
TRUEto enable overwriting existing files
Zwracane wartości
returns TRUE on success, but it is better to check for thrown exception,
and assume success if none is thrown.
Błędy/Wyjątki
Throws PharException if errors occur while flushing changes to disk.
Przykłady
Przykład #1 A Phar::extractTo() example
<?php
try {
$phar = new Phar('myphar.phar');
$phar->extractTo('/full/path'); // extract all files
$phar->extractTo('/another/path', 'file.txt'); // extract only file.txt
$phar->extractTo('/this/path',
array('file1.txt', 'file2.txt')); // extract 2 files only
$phar->extractTo('/third/path', null, true); // extract all files, and overwrite
} catch (Exception $e) {
// handle errors
}
?>
Phar::getMetadata
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::getMetadata — Returns phar archive meta-data
Opis
Retrieve archive meta-data. Meta-data can be any PHP variable that can be serialized.
Parametry
No parameters.
Zwracane wartości
any PHP variable that can be serialized and is stored as meta-data for the Phar archive,
or NULL if no meta-data is stored.
Przykłady
Przykład #1 A Phar::getMetadata() example
<?php
// make sure it doesn't exist
@unlink('brandnewphar.phar');
try {
$p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
$p['file.php'] = '<?php echo "hello";';
$p->setMetadata(array('bootstrap' => 'file.php'));
var_dump($p->getMetadata());
} catch (Exception $e) {
echo 'Could not modify phar:', $e;
}
?>
Powyższy przykład wyświetli:
array(1) {
["bootstrap"]=>
string(8) "file.php"
}
Zobacz też:
- Phar::setMetadata() - Sets phar archive meta-data
- Phar::delMetadata() - Deletes the global metadata of the phar
- Phar::hasMetadata() - Returns whether phar has global meta-data
Phar::getModified
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::getModified — Return whether phar was modified
Opis
This method can be used to determine whether a phar has either had an internal file deleted, or contents of a file changed in some way.
Parametry
No parameters.
Zwracane wartości
TRUE if the phar has been modified since opened, FALSE if not.
Phar::getSignature
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::getSignature — Return MD5/SHA1/SHA256/SHA512/OpenSSL signature of a Phar archive
Opis
Returns the verification signature of a phar archive in a hexadecimal string.
Parametry
Zwracane wartości
Array with the opened archive's signature in hash key and MD5, SHA-1, SHA-256, SHA-512, or OpenSSL in hash_type. This signature is a hash calculated on the entire phar's contents, and may be used to verify the integrity of the archive. A valid signature is absolutely required of all executable phar archives if the phar.require_hash INI variable is set to true.
Phar::getStub
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::getStub — Return the PHP loader or bootstrap stub of a Phar archive
Opis
Phar archives contain a bootstrap loader, or stub written in PHP that is executed when the archive is executed in PHP either via include:
<?php
include 'myphar.phar';
?>
php myphar.phar
Zwracane wartości
Returns a string containing the contents of the bootstrap loader (stub) of the current Phar archive.
Błędy/Wyjątki
Throws RuntimeException if it is not possible to read the stub from the Phar archive.
Przykłady
Przykład #1 A Phar::getStub() example
<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
echo $p->getStub();
echo "==NEXT==\n";
$p->setStub("<?php
function __autoload($class)
{
include 'phar://' . str_replace('_', '/', $class);
}
Phar::mapPhar('myphar.phar');
include 'phar://myphar.phar/startup.php';
__HALT_COMPILER(); ?>");
echo $p->getStub();
?>
Powyższy przykład wyświetli:
<?php __HALT_COMPILER(); ?>
==NEXT==
<?php
function __autoload($class)
{
include 'phar://' . str_replace('_', '/', $class);
}
Phar::mapPhar('myphar.phar');
include 'phar://myphar.phar/startup.php';
__HALT_COMPILER(); ?>
Zobacz też:
- Phar::setStub() - Used to set the PHP loader or bootstrap stub of a Phar archive
- Phar::createDefaultStub() - Create a phar-file format specific stub
Phar::getSupportedCompression
(PHP >= 5.3.0, PECL phar >= 1.2.0)
Phar::getSupportedCompression — Return array of supported compression algorithms
Opis
Parametry
No parameters.
Zwracane wartości
Returns an array containing any of Phar::GZ or Phar::BZ2, depending on the availability of the zlib extension or the bz2 extension.
Zobacz też:
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- Phar::compress() - Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::decompress() - Decompresses the entire Phar archive
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressFiles() - Compresses all files in the current Phar archive
- Phar::decompressFiles() - Decompresses all files in the current Phar archive
Phar::getSupportedSignatures
(PHP >= 5.3.0, PECL phar >= 1.1.0)
Phar::getSupportedSignatures — Return array of supported signature types
Opis
Return array of supported signature types
Parametry
No parameters.
Zwracane wartości
Returns an array containing any of MD5, SHA-1, SHA-256, SHA-512, or OpenSSL.
Zobacz też:
- Phar::getSignature() - Return MD5/SHA1/SHA256/SHA512/OpenSSL signature of a Phar archive
- Phar::setSignatureAlgorithm() - set the signature algorithm for a phar and apply it. The
Phar::getVersion
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::getVersion — Return version info of Phar archive
Opis
Returns the API version of an opened Phar archive.
Parametry
Zwracane wartości
The opened archive's API version. This is not to be confused with the API version that the loaded phar extension will use to create new phars. Each Phar archive has the API version hard-coded into its manifest. See Phar file format documentation for more information.
Phar::hasMetadata
(PHP >= 5.3.0, PECL phar >= 1.2.0)
Phar::hasMetadata — Returns whether phar has global meta-data
Opis
Returns whether phar has global meta-data set.
Parametry
No parameters.
Zwracane wartości
Returns TRUE if meta-data has been set, and FALSE if not.
Przykłady
Przykład #1 A Phar::hasMetadata() example
<?php
try {
$phar = new Phar('myphar.phar');
var_dump($phar->hasMetadata());
$phar->setMetadata(array('thing' => 'hi'));
var_dump($phar->hasMetadata());
$phar->delMetadata();
var_dump($phar->hasMetadata());
} catch (Exception $e) {
// handle error
}
?>
Powyższy przykład wyświetli:
bool(false) bool(true) bool(false)
Zobacz też:
- Phar::getMetadata() - Returns phar archive meta-data
- Phar::setMetadata() - Sets phar archive meta-data
- Phar::delMetadata() - Deletes the global metadata of the phar
Phar::interceptFileFuncs
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::interceptFileFuncs — instructs phar to intercept fopen, file_get_contents, opendir, and all of the stat-related functions
Opis
instructs phar to intercept fopen(), readfile(), file_get_contents(), opendir(), and all of the stat-related functions. If any of these functions is called from within a phar archive with a relative path, the call is modified to access a file within the phar archive. Absolute paths are assumed to be attempts to load external files from the filesystem.
This function makes it possible to run PHP applications designed to run off of a hard disk as a phar application.
Parametry
No parameters.
Zwracane wartości
Przykłady
Przykład #1 A Phar::interceptFileFuncs() example
<?php
Phar::interceptFileFuncs();
include 'phar://' . __FILE__ . '/file.php';
?>
Assuming that this phar is at /path/to/myphar.phar and it contains file.php and file2.txt, if file.php contains this code:
Przykład #2 A Phar::interceptFileFuncs() example
<?php
echo file_get_contents('file2.txt');
?>
Normally PHP would search the current directory for file2.txt, which would translate as the directory of file.php, or the current directory of a command-line user. Phar::interceptFileFuncs() instructs PHP to consider the current directory to be phar:///path/to/myphar.phar/ and so opens phar:///path/to/myphar.phar/file2.txt in the above example code.
Phar::isBuffering
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::isBuffering — Used to determine whether Phar write operations are being buffered, or are flushing directly to disk
Opis
This method can be used to determine whether a Phar will save changes to disk immediately, or whether a call to Phar::stopBuffering() is needed to enable saving changes.
Phar write buffering is per-archive, buffering active for the foo.phar Phar archive does not affect changes to the bar.phar Phar archive.
Zwracane wartości
Returns TRUE if the write operations are being buffer, FALSE otherwise.
Przykłady
Przykład #1 A Phar::isBuffering() example
<?php
$p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
$p2 = new Phar('existingphar.phar');
$p['file1.txt'] = 'hi';
var_dump($p->isBuffering());
var_dump($p2->isBuffering());
?>
=2=
<?php
$p->startBuffering();
var_dump($p->isBuffering());
var_dump($p2->isBuffering());
$p->stopBuffering();
?>
=3=
<?php
var_dump($p->isBuffering());
var_dump($p2->isBuffering());
?>
Powyższy przykład wyświetli:
bool(false) bool(false) =2= bool(true) bool(false) =3= bool(false) bool(false)
Zobacz też:
- Phar::startBuffering() - Start buffering Phar write operations, do not modify the Phar object on disk
- Phar::stopBuffering() - Stop buffering write requests to the Phar archive, and save changes to disk
Phar::isCompressed
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::isCompressed — Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
Opis
Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed
(.tar.gz/tar.bz and so on). Zip-based phar archives cannot be compressed as a
file, and so this method will always return FALSE if a zip-based phar archive is queried.
Parametry
No parameters.
Zwracane wartości
Phar::GZ, Phar::BZ2 or FALSE
Przykłady
Przykład #1 A Phar::isCompressed() example
<?php
try {
$phar1 = new Phar('myphar.zip.phar');
var_dump($phar1->isCompressed());
$phar2 = new Phar('myuncompressed.tar.phar');
var_dump($phar2->isCompressed());
$phar2->compressAllFilesGZ();
var_dump($phar2->isCompressed() == Phar::GZ);
} catch (Exception $e) {
}
?>
Powyższy przykład wyświetli:
bool(false) bool(false) bool(true)
Zobacz też:
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- Phar::decompress() - Decompresses the entire Phar archive
- Phar::compress() - Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::compressFiles() - Compresses all files in the current Phar archive
- Phar::decompressFiles() - Decompresses all files in the current Phar archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms
Phar::isFileFormat
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::isFileFormat — Returns true if the phar archive is based on the tar/phar/zip file format depending on the parameter
Opis
$format
)
Parametry
-
format -
Either Phar::PHAR, Phar::TAR, or Phar::ZIP to test for the format of the archive.
Zwracane wartości
Returns TRUE if the phar archive matches the file format requested by the parameter
Błędy/Wyjątki
PharException is thrown if the parameter is an unknown file format specifier.
Zobacz też:
- Phar::convertToExecutable() - Convert a phar archive to another executable phar archive file format
- Phar::convertToData() - Convert a phar archive to a non-executable tar or zip file
Phar::isValidPharFilename
(PHP >= 5.3.0, PECL phar >= 1.2.0)
Phar::isValidPharFilename — Returns whether the given filename is a valid phar filename
Opis
$filename
[, bool $executable = true
] )Returns whether the given filename is a valid phar filename that will be recognized as a phar archive by the phar extension. This can be used to test a name without having to instantiate a phar archive and catch the inevitable Exception that will be thrown if an invalid name is specified.
Parametry
-
filename -
The name or full path to a phar archive not yet created
-
executable -
This parameter determines whether the filename should be treated as a phar executable archive, or a data non-executable archive
Zwracane wartości
Returns TRUE if the filename is valid, FALSE if not.
Phar::isWritable
(Unknown)
Phar::isWritable — Returns true if the phar archive can be modified
Opis
This method returns TRUE if phar.readonly is 0,
and the actual phar archive on disk is not read-only.
Parametry
No parameters.
Zwracane wartości
Returns TRUE if the phar archive can be modified
Zobacz też:
- Phar::canWrite() - Returns whether phar extension supports writing and creating phars
- PharData::isWritable() - Returns true if the tar/zip archive can be modified
Phar::loadPhar
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::loadPhar — Loads any phar archive with an alias
Opis
$filename
[, string $alias
] )This can be used to read the contents of an external Phar archive. This is most useful for assigning an alias to a phar so that subsequent references to the phar can use the shorter alias, or for loading Phar archives that only contain data and are not intended for execution/inclusion in PHP scripts.
Parametry
-
filename -
the full or relative path to the phar archive to open
-
alias -
The alias that may be used to refer to the phar archive. Note that many phar archives specify an explicit alias inside the phar archive, and a PharException will be thrown if a new alias is specified in this case.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Błędy/Wyjątki
PharException is thrown if an alias is passed in and the phar archive already has an explicit alias
Przykłady
Przykład #1 A Phar::loadPhar() example
Phar::loadPhar can be used anywhere to load an external Phar archive, whereas Phar::mapPhar should be used in a loader stub for a Phar.
<?php
try {
Phar::loadPhar('/path/to/phar.phar', 'my.phar');
echo file_get_contents('phar://my.phar/file.txt');
} catch (PharException $e) {
echo $e;
}
?>
Phar::mapPhar
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::mapPhar — Reads the currently executed file (a phar) and registers its manifest
Opis
$alias
[, int $dataoffset = 0
]] )This static method can only be used inside a Phar archive's loader stub in order to initialize the phar when it is directly executed, or when it is included in another script.
Parametry
-
alias -
The alias that can be used in phar:// URLs to refer to this archive, rather than its full path.
-
dataoffset -
Unused variable, here for compatibility with PEAR's PHP_Archive.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Błędy/Wyjątki
PharException is thrown if not called directly within PHP execution, if no __HALT_COMPILER(); token is found in the current source file, or if the file cannot be opened for reading.
Przykłady
Przykład #1 A Phar::mapPhar() example
mapPhar should be used only inside a phar's loader stub. Use loadPhar to load an external phar into memory.
Here is a sample Phar loader stub that uses mapPhar.
<?php
function __autoload($class)
{
include 'phar://me.phar/' . str_replace('_', '/', $class) . '.php';
}
try {
Phar::mapPhar('me.phar');
include 'phar://me.phar/startup.php';
} catch (PharException $e) {
echo $e->getMessage();
die('Cannot initialize Phar');
}
__HALT_COMPILER();
Phar::mount
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::mount — Mount an external path or file to a virtual location within the phar archive
Opis
$pharpath
, string $externalpath
)Much like the unix file system concept of mounting external devices to paths within the directory tree, Phar::mount() allows referring to external files and directories as if they were inside of an archive. This allows powerful abstraction such as referring to external configuration files as if they were inside the archive.
Parametry
-
pharpath -
The internal path within the phar archive to use as the mounted path location. This must be a relative path within the phar archive, and must not already exist.
-
externalpath -
A path or URL to an external file or directory to mount within the phar archive
Zwracane wartości
No return. PharException is thrown on failure.
Błędy/Wyjątki
Throws PharException if any problems occur mounting the path.
Przykłady
Przykład #1 A Phar::mount() example
The following example shows accessing an external configuration file as if it were a path within a phar archive.
First, the code inside of a phar archive:
<?php
$configuration = simplexml_load_string(file_get_contents(
Phar::running(false) . '/config.xml'));
?>
Next the external code used to mount the configuration file:
<?php
// first set up the association between the abstract config.xml
// and the actual one on disk
Phar::mount('phar://config.xml', '/home/example/config.xml');
// now run the application
include '/path/to/archive.phar';
?>
Another method is to put the mounting code inside the stub of the phar archive. Here is an example of setting up a default configuration file if no user configuration is specified:
<?php
// first set up the association between the abstract config.xml
// and the actual one on disk
if (defined('EXTERNAL_CONFIG')) {
Phar::mount('config.xml', EXTERNAL_CONFIG);
if (file_exists(__DIR__ . '/extra_config.xml')) {
Phar::mount('extra.xml', __DIR__ . '/extra_config.xml');
}
} else {
Phar::mount('config.xml', 'phar://' . __FILE__ . '/default_config.xml');
Phar::mount('extra.xml', 'phar://' . __FILE__ . '/default_extra.xml');
}
// now run the application
include 'phar://' . __FILE__ . '/index.php';
__HALT_COMPILER();
?>
...and the code externally to load this phar archive:
<?php
define('EXTERNAL_CONFIG', '/home/example/config.xml');
// now run the application
include '/path/to/archive.phar';
?>
Phar::mungServer
(Unknown)
Phar::mungServer — Defines a list of up to 4 $_SERVER variables that should be modified for execution
Opis
$munglist
)Phar::mungServer() should only be called within the stub of a phar archive.
Defines a list of up to 4 $_SERVER variables that should be modified for execution. Variables that can be modified to remove traces of phar execution are REQUEST_URI, PHP_SELF, SCRIPT_NAME and SCRIPT_FILENAME.
On its own, this method does nothing. Only when combined with Phar::webPhar() does it take effect, and only when the requested file is a PHP file to be parsed. Note that the PATH_INFO and PATH_TRANSLATED variables are always modified.
The original values of variables that are modified are stored in the SERVER array with PHAR_ prepended, so for instance SCRIPT_NAME would be saved as PHAR_SCRIPT_NAME.
Parametry
-
munglist -
an array containing as string indices any of REQUEST_URI, PHP_SELF, SCRIPT_NAME and SCRIPT_FILENAME. Other values trigger an exception, and Phar::mungServer() is case-sensitive.
Zwracane wartości
No return.
Błędy/Wyjątki
Throws UnexpectedValueException if any problems are found with the passed in data.
Przykłady
Przykład #1 A Phar::mungServer() example
<?php
// example stub
Phar::mungServer(array('REQUEST_URI'));
Phar::webPhar();
__HALT_COMPILER();
?>
Zobacz też:
- Phar::webPhar() - mapPhar for web-based phars. front controller for web applications
- Phar::setStub() - Used to set the PHP loader or bootstrap stub of a Phar archive
Phar::offsetExists
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::offsetExists — determines whether a file exists in the phar
Opis
$offset
)This is an implementation of the ArrayAccess interface allowing direct manipulation of the contents of a Phar archive using array access brackets.
offsetExists() is called whenever isset() is called.
Parametry
-
offset -
The filename (relative path) to look for in a Phar.
Zwracane wartości
Returns TRUE if the file exists within the phar, or FALSE if not.
Przykłady
Przykład #1 A Phar::offsetExists() example
<?php
$p = new Phar(dirname(__FILE__) . '/my.phar', 0, 'my.phar');
$p['firstfile.txt'] = 'first file';
$p['secondfile.txt'] = 'second file';
// the next set of lines call offsetExists() indirectly
var_dump(isset($p['firstfile.txt']));
var_dump(isset($p['nothere.txt']));
?>
Powyższy przykład wyświetli:
bool(true) bool(false)
Zobacz też:
- Phar::offsetGet() - Gets a PharFileInfo object for a specific file
- Phar::offsetSet() - set the contents of an internal file to those of an external file
- Phar::offsetUnset() - remove a file from a phar
Phar::offsetGet
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::offsetGet — Gets a PharFileInfo object for a specific file
Opis
$offset
)This is an implementation of the ArrayAccess interface allowing direct manipulation of the contents of a Phar archive using array access brackets. Phar::offsetGet() is used for retrieving files from a Phar archive.
Parametry
-
offset -
The filename (relative path) to look for in a Phar.
Zwracane wartości
A PharFileInfo object is returned that can be used to iterate over a file's contents or to retrieve information about the current file.
Błędy/Wyjątki
This method throws BadMethodCallException if the file does not exist in the Phar archive.
Przykłady
Przykład #1 Phar::offsetGet() example
As with all classes that implement the ArrayAccess interface, Phar::offsetGet() is automatically called when using the [] angle bracket operator.
<?php
$p = new Phar(dirname(__FILE__) . '/myphar.phar', 0, 'myphar.phar');
$p['exists.txt'] = "file exists\n";
try {
// automatically calls offsetGet()
echo $p['exists.txt'];
echo $p['doesnotexist.txt'];
} catch (BadMethodCallException $e) {
echo $e;
}
?>
Powyższy przykład wyświetli:
file exists Entry doesnotexist.txt does not exist
Zobacz też:
- Phar::offsetExists() - determines whether a file exists in the phar
- Phar::offsetSet() - set the contents of an internal file to those of an external file
- Phar::offsetUnset() - remove a file from a phar
Phar::offsetSet
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::offsetSet — set the contents of an internal file to those of an external file
Opis
$offset
, string $value
)Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
This is an implementation of the ArrayAccess interface allowing direct manipulation of the contents of a Phar archive using array access brackets. offsetSet is used for modifying an existing file, or adding a new file to a Phar archive.
Parametry
-
offset -
The filename (relative path) to modify in a Phar.
-
value -
Content of the file.
Zwracane wartości
No return values.
Błędy/Wyjątki
if phar.readonly is 1, BadMethodCallException is thrown, as modifying a Phar is only allowed when phar.readonly is set to 0. Throws PharException if there are any problems flushing changes made to the Phar archive to disk.
Przykłady
Przykład #1 A Phar::offsetSet() example
offsetSet should not be accessed directly, but instead used via array access with the [] operator.
<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
try {
// calls offsetSet
$p['file.txt'] = 'Hi there';
} catch (Exception $e) {
echo 'Could not modify file.txt:', $e;
}
?>
Zobacz też:
- Phar::offsetExists() - determines whether a file exists in the phar
- Phar::offsetGet() - Gets a PharFileInfo object for a specific file
- Phar::offsetUnset() - remove a file from a phar
Phar::offsetUnset
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::offsetUnset — remove a file from a phar
Opis
$offset
)Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
This is an implementation of the ArrayAccess interface allowing direct manipulation of the contents of a Phar archive using array access brackets. offsetUnset is used for deleting an existing file, and is called by the unset() language construct.
Parametry
-
offset -
The filename (relative path) to modify in a Phar.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Błędy/Wyjątki
if phar.readonly is 1, BadMethodCallException is thrown, as modifying a Phar is only allowed when phar.readonly is set to 0. Throws PharException if there are any problems flushing changes made to the Phar archive to disk.
Przykłady
Przykład #1 A Phar::offsetUnset() example
<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
try {
// deletes file.txt from my.phar by calling offsetUnset
unset($p['file.txt']);
} catch (Exception $e) {
echo 'Could not delete file.txt: ', $e;
}
?>
Zobacz też:
- Phar::offsetExists() - determines whether a file exists in the phar
- Phar::offsetGet() - Gets a PharFileInfo object for a specific file
- Phar::offsetSet() - set the contents of an internal file to those of an external file
- Phar::unlinkArchive() - Completely remove a phar archive from disk and from memory
- Phar::delete() - Delete a file within a phar archive
Phar::running
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::running — Returns the full path on disk or full phar URL to the currently executing Phar archive
Opis
$retphar = true
] )Returns the full path to the running phar archive. This is intended for use much like the __FILE__ magic constant, and only has effect inside an executing phar archive.
Inside the stub of an archive, Phar::running() returns
"". Simply use __FILE__
to access the current running phar inside a stub.
Parametry
-
retphar -
If
FALSE, the full path on disk to the phar archive is returned. IfTRUE, a full phar URL is returned.
Zwracane wartości
Returns the filename if valid, empty string otherwise.
Przykłady
Przykład #1 A Phar::running() example
For the following example, assume the phar archive is located at /path/to/phar/my.phar.
<?php
$a = Phar::running(); // $a is "phar:///path/to/my.phar"
$b = Phar::running(false); // $b is "/path/to/my.phar"
?>
Phar::setAlias
(PHP >= 5.3.0, PECL phar >= 1.2.1)
Phar::setAlias — Set the alias for the Phar archive
Opis
$alias
)Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
Set the alias for the Phar archive, and write it as the permanent alias for this phar archive. An alias can be used internally to a phar archive to ensure that use of the phar stream wrapper to access internal files always works regardless of the location of the phar archive on the filesystem. Another alternative is to rely upon Phar's interception of include() or to use Phar::interceptFileFuncs() and use relative paths.
Parametry
-
alias -
A shorthand string that this archive can be referred to in phar stream wrapper access.
Zwracane wartości
Błędy/Wyjątki
Throws UnexpectedValueException when write access is disabled, and PharException if the alias is already in use or any problems were encountered flushing changes to disk.
Przykłady
Przykład #1 A Phar::setAlias() example
<?php
try {
$phar = new Phar('myphar.phar');
$phar->setAlias('myp.phar');
} catch (Exception $e) {
// handle error
}
?>
Zobacz też:
- Phar::__construct() - Construct a Phar archive object
- Phar::interceptFileFuncs() - instructs phar to intercept fopen, file_get_contents, opendir, and all of the stat-related functions
Phar::setDefaultStub
(Unknown)
Phar::setDefaultStub — Used to set the PHP loader or bootstrap stub of a Phar archive to the default loader
Opis
$index
[, string $webindex
]] )Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
This method is a convenience method that combines the functionality of Phar::createDefaultStub() and Phar::setStub().
Parametry
-
index -
Relative path within the phar archive to run if accessed on the command-line
-
webindex -
Relative path within the phar archive to run if accessed through a web browser
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Błędy/Wyjątki
UnexpectedValueException is thrown if phar.readonly is enabled in php.ini. PharException is thrown if any problems are encountered flushing changes to disk.
Przykłady
Przykład #1 A Phar::setDefaultStub() example
<?php
try {
$phar = new Phar('myphar.phar');
$phar->setDefaultStub('cli.php', 'web/index.php');
// this is the same as:
// $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
} catch (Exception $e) {
// handle errors
}
?>
Zobacz też:
- Phar::setStub() - Used to set the PHP loader or bootstrap stub of a Phar archive
- Phar::createDefaultStub() - Create a phar-file format specific stub
Phar::setMetadata
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::setMetadata — Sets phar archive meta-data
Opis
Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
Phar::setMetadata() should be used to store customized data that describes something about the phar archive as a complete entity. PharFileInfo::setMetadata() should be used for file-specific meta-data. Meta-data can slow down the performance of loading a phar archive if the data is large.
Some possible uses for meta-data include specifying which file within the archive should be used to bootstrap the archive, or the location of a file manifest like » PEAR's package.xml file. However, any useful data that describes the phar archive may be stored.
Parametry
-
metadata -
Any PHP variable containing information to store that describes the phar archive
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 A Phar::setMetadata() example
<?php
// make sure it doesn't exist
@unlink('brandnewphar.phar');
try {
$p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
$p['file.php'] = '<?php echo "hello"';
$p->setMetadata(array('bootstrap' => 'file.php'));
var_dump($p->getMetadata());
} catch (Exception $e) {
echo 'Could not create and/or modify phar:', $e;
}
?>
Powyższy przykład wyświetli:
array(1) {
["bootstrap"]=>
string(8) "file.php"
}
Zobacz też:
- Phar::getMetadata() - Returns phar archive meta-data
- Phar::delMetadata() - Deletes the global metadata of the phar
- Phar::hasMetadata() - Returns whether phar has global meta-data
Phar::setSignatureAlgorithm
(PHP >= 5.3.0, PECL phar >= 1.1.0)
Phar::setSignatureAlgorithm — set the signature algorithm for a phar and apply it.
Opis
Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
set the signature algorithm for a phar and apply it. The signature algorithm must be one of Phar::MD5, Phar::SHA1, Phar::SHA256, Phar::SHA512, or Phar::OPENSSL.
Note that all executable phar archives have a signature created automatically, SHA1 by default. data tar- or zip-based archives (archives created with the PharData class) must have their signature created and set explicitly via Phar::setSignatureAlgorithm().
Parametry
-
sigtype -
One of Phar::MD5, Phar::SHA1, Phar::SHA256, Phar::SHA512, or Phar::OPENSSL
-
privatekey -
The contents of an OpenSSL private key, as extracted from a certificate or OpenSSL key file:
See phar introduction for instructions on naming and placement of the public key file.<?php
$private = openssl_get_privatekey(file_get_contents('private.pem'));
$pkey = '';
openssl_pkey_export($private, $pkey);
$p->setSignatureAlgorithm(Phar::OPENSSL, $pkey);
?>
Zwracane wartości
Nie jest zwracana żadna wartość.
Błędy/Wyjątki
Throws UnexpectedValueException for many errors, and a PharException if any problems occur flushing changes to disk.
Zobacz też:
- Phar::getSupportedSignatures() - Return array of supported signature types
- Phar::getSignature() - Return MD5/SHA1/SHA256/SHA512/OpenSSL signature of a Phar archive
Phar::setStub
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::setStub — Used to set the PHP loader or bootstrap stub of a Phar archive
Opis
$stub
)Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
This method is used to add a PHP bootstrap loader stub to a new Phar archive, or to replace the loader stub in an existing Phar archive.
The loader stub for a Phar archive is used whenever an archive is included directly as in this example:
<?php
include 'myphar.phar';
?>
The loader is not accessed when including a file through the phar stream wrapper like so:
<?php
include 'phar://myphar.phar/somefile.php';
?>
Parametry
-
stub -
A string or an open stream handle to use as the executable stub for this phar archive.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Błędy/Wyjątki
UnexpectedValueException is thrown if phar.readonly is enabled in php.ini. PharException is thrown if any problems are encountered flushing changes to disk.
Przykłady
Przykład #1 A Phar::setStub() example
<?php
try {
$p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
$p['a.php'] = '<?php var_dump("Hello");';
$p->setStub('<?php var_dump("First"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>');
include 'phar://brandnewphar.phar/a.php';
var_dump($p->getStub());
$p['b.php'] = '<?php var_dump("World");';
$p->setStub('<?php var_dump("Second"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>');
include 'phar://brandnewphar.phar/b.php';
var_dump($p->getStub());
} catch (Exception $e) {
echo 'Write operations failed on brandnewphar.phar: ', $e;
}
?>
Powyższy przykład wyświetli:
string(5) "Hello"
string(82) "<?php var_dump("First"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>"
string(5) "World"
string(83) "<?php var_dump("Second"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>"
Zobacz też:
- Phar::getStub() - Return the PHP loader or bootstrap stub of a Phar archive
- Phar::createDefaultStub() - Create a phar-file format specific stub
Phar::startBuffering
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::startBuffering — Start buffering Phar write operations, do not modify the Phar object on disk
Opis
Although technically unnecessary, the Phar::startBuffering() method can provide a significant performance boost when creating or modifying a Phar archive with a large number of files. Ordinarily, every time a file within a Phar archive is created or modified in any way, the entire Phar archive will be recreated with the changes. In this way, the archive will be up-to-date with the activity performed on it.
However, this can be unnecessary when simply creating a new Phar archive, when it would make more sense to write the entire archive out at once. Similarly, it is often necessary to make a series of changes and to ensure that they all are possible before making any changes on disk, similar to the relational database concept of transactions. the Phar::startBuffering()/Phar::stopBuffering() pair of methods is provided for this purpose.
Phar write buffering is per-archive, buffering active for the foo.phar Phar archive does not affect changes to the bar.phar Phar archive.
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 A Phar::startBuffering() example
<?php
// make sure it doesn't exist
@unlink('brandnewphar.phar');
try {
$p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
} catch (Exception $e) {
echo 'Could not create phar:', $e;
}
echo 'The new phar has ' . $p->count() . " entries\n";
$p->startBuffering();
$p['file.txt'] = 'hi';
$p['file2.txt'] = 'there';
$p['file2.txt']->setCompressedGZ();
$p['file3.txt'] = 'babyface';
$p['file3.txt']->setMetadata(42);
$p->setStub("<?php
function __autoload($class)
{
include 'phar://myphar.phar/' . str_replace('_', '/', $class) . '.php';
}
Phar::mapPhar('myphar.phar');
include 'phar://myphar.phar/startup.php';
__HALT_COMPILER();");
$p->stopBuffering();
?>
Zobacz też:
- Phar::stopBuffering() - Stop buffering write requests to the Phar archive, and save changes to disk
- Phar::isBuffering() - Used to determine whether Phar write operations are being buffered, or are flushing directly to disk
Phar::stopBuffering
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::stopBuffering — Stop buffering write requests to the Phar archive, and save changes to disk
Opis
Phar::stopBuffering() is used in conjunction with the Phar::startBuffering() method. Phar::startBuffering() can provide a significant performance boost when creating or modifying a Phar archive with a large number of files. Ordinarily, every time a file within a Phar archive is created or modified in any way, the entire Phar archive will be recreated with the changes. In this way, the archive will be up-to-date with the activity performed on it.
However, this can be unnecessary when simply creating a new Phar archive, when it would make more sense to write the entire archive out at once. Similarly, it is often necessary to make a series of changes and to ensure that they all are possible before making any changes on disk, similar to the relational database concept of transactions. The Phar::startBuffering()/Phar::stopBuffering() pair of methods is provided for this purpose.
Phar write buffering is per-archive, buffering active for the foo.phar Phar archive does not affect changes to the bar.phar Phar archive.
Zwracane wartości
Nie jest zwracana żadna wartość.
Błędy/Wyjątki
PharException is thrown if any problems are encountered flushing changes to disk.
Przykłady
Przykład #1 A Phar::stopBuffering() example
<?php
$p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
$p['file1.txt'] = 'hi';
$p->startBuffering();
var_dump($p->getStub());
$p->setStub("<?php
function __autoload(\$class)
{
include 'phar://brandnewphar.phar/' . str_replace('_', '/', \$class) . '.php';
}
Phar::mapPhar('brandnewphar.phar');
include 'phar://brandnewphar.phar/startup.php';
__HALT_COMPILER();");
$p->stopBuffering();
var_dump($p->getStub());
?>
Powyższy przykład wyświetli:
string(24) "<?php __HALT_COMPILER();"
string(195) "<?php
function __autoload($class)
{
include 'phar://' . str_replace('_', '/', $class);
}
Phar::mapPhar('brandnewphar.phar');
include 'phar://brandnewphar.phar/startup.php';
__HALT_COMPILER();"
Zobacz też:
- Phar::startBuffering() - Start buffering Phar write operations, do not modify the Phar object on disk
- Phar::isBuffering() - Used to determine whether Phar write operations are being buffered, or are flushing directly to disk
Phar::uncompressAllFiles
(PECL phar < 2.0.0)
Phar::uncompressAllFiles — Uncompresses all files in the current Phar archive
Opis
Informacja:
Ta metoda została usunięta z rozszerzenia phar w wersji 2.0.0. Dostępne są zastępcze implementacje: Phar::compress(), Phar::decompress(), Phar::compressFiles() i Phar::decompressFiles().
Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
This method decompresses all files in the Phar archive. If any files are already compressed using gzip compression, the zlib extension must be enabled in order to decompress the files, and any files compressed using bzip2 compression require the bzip2 extension to decompress the files. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Błędy/Wyjątki
Throws BadMethodCallException if the phar.readonly INI variable is on, the bzip2 extension is not enabled and any files are compressed using bzip2 compression, or if any files are compressed using gzip compression and the zlib extension is not enabled.
Przykłady
Przykład #1 A Phar::uncompressAllFiles() example
<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p->compressAllFilesGZ();
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressedBZIP2());
var_dump($file->isCompressedGZ());
}
$p->uncompressAllFiles();
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressedBZIP2());
var_dump($file->isCompressedGZ());
}
} catch (Exception $e) {
echo 'Write operations failed on my.phar: ', $e;
}
?>
Powyższy przykład wyświetli:
string(10) "myfile.txt" bool(true) bool(false) bool(true) string(11) "myfile2.txt" bool(true) bool(false) bool(true) string(10) "myfile.txt" bool(false) bool(false) bool(false) string(11) "myfile2.txt" bool(false) bool(false) bool(false)
Zobacz też:
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressedBZIP2() - Returns whether the entry is compressed using bzip2
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::isCompressedGZ() - Returns whether the entry is compressed using gz
- PharFileInfo::setCompressedBZIP2() - Compresses the current Phar entry within the phar using Bzip2 compression
- PharFileInfo::setUncompressed() - Uncompresses the current Phar entry within the phar, if it is compressed
- PharFileInfo::setCompressedGZ() - Compresses the current Phar entry within the phar using gz compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressAllFilesBZIP2() - Compresses all files in the current Phar archive using Bzip2 compression
- Phar::compressAllFilesGZ() - Compresses all files in the current Phar archive using Gzip compression
- Phar::getSupportedCompression() - Return array of supported compression algorithms
Phar::unlinkArchive
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::unlinkArchive — Completely remove a phar archive from disk and from memory
Opis
$archive
)Removes a phar archive for disk and memory.
Parametry
-
archive -
The path on disk to the phar archive.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Błędy/Wyjątki
PharException is thrown if there are any open file pointers to the phar archive, or any existing Phar, PharData, or PharFileInfo objects referring to the phar archive.
Przykłady
Przykład #1 A Phar::unlinkArchive() example
<?php
// simple usage
Phar::unlinkArchive('/path/to/my.phar');
// more common example:
$p = new Phar('my.phar');
$fp = fopen('phar://my.phar/file.txt', 'r');
// this creates 'my.phar.gz'
$gp = $p->compress(Phar::GZ);
// remove all references to the archive
unset($p);
fclose($fp);
// now remove all traces of the archive
Phar::unlinkArchive('my.phar');
?>
Zobacz też:
- Phar::delete() - Delete a file within a phar archive
- Phar::offsetUnset() - remove a file from a phar
Phar::webPhar
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::webPhar — mapPhar for web-based phars. front controller for web applications
Opis
$alias
[, string $index = "index.php"
[, string $f404
[, array $mimetypes
[, array $rewrites
]]]]] )Phar::mapPhar() for web-based phars. This method parses $_SERVER['REQUEST_URI'] and routes a request from a web browser to an internal file within the phar archive. In essence, it simulates a web server, routing requests to the correct file, echoing the correct headers and parsing PHP files as needed. This powerful method is part of what makes it easy to convert an existing PHP application into a phar archive. Combined with Phar::mungServer() and Phar::interceptFileFuncs(), any web application can be used unmodified from a phar archive.
Phar::webPhar() should only be called from the stub of a phar archive (see here for more information on what a stub is).
Parametry
-
alias -
The alias that can be used in phar:// URLs to refer to this archive, rather than its full path.
-
index -
The location within the phar of the directory index.
-
f404 -
The location of the script to run when a file is not found. This script should output the proper HTTP 404 headers.
-
mimetypes -
An array mapping additional file extensions to MIME type. If the default mapping is sufficient, pass an empty array. By default, these extensions are mapped to these MIME types:
<?php
$mimes = array(
'phps' => Phar::PHPS, // pass to highlight_file()
'c' => 'text/plain',
'cc' => 'text/plain',
'cpp' => 'text/plain',
'c++' => 'text/plain',
'dtd' => 'text/plain',
'h' => 'text/plain',
'log' => 'text/plain',
'rng' => 'text/plain',
'txt' => 'text/plain',
'xsd' => 'text/plain',
'php' => Phar::PHP, // parse as PHP
'inc' => Phar::PHP, // parse as PHP
'avi' => 'video/avi',
'bmp' => 'image/bmp',
'css' => 'text/css',
'gif' => 'image/gif',
'htm' => 'text/html',
'html' => 'text/html',
'htmls' => 'text/html',
'ico' => 'image/x-ico',
'jpe' => 'image/jpeg',
'jpg' => 'image/jpeg',
'jpeg' => 'image/jpeg',
'js' => 'application/x-javascript',
'midi' => 'audio/midi',
'mid' => 'audio/midi',
'mod' => 'audio/mod',
'mov' => 'movie/quicktime',
'mp3' => 'audio/mp3',
'mpg' => 'video/mpeg',
'mpeg' => 'video/mpeg',
'pdf' => 'application/pdf',
'png' => 'image/png',
'swf' => 'application/shockwave-flash',
'tif' => 'image/tiff',
'tiff' => 'image/tiff',
'wav' => 'audio/wav',
'xbm' => 'image/xbm',
'xml' => 'text/xml',
);
?> -
rewrites -
An array mapping URI to internal file, simulating mod_rewrite of apache. For example:
would route calls to http://<host>/myphar.phar/myinfo to the file phar:///path/to/myphar.phar/myinfo.php, preserving GET/POST. This does not quite work like mod_rewrite in that it would not match http://<host>/myphar.phar/myinfo/another.<?php
array(
'myinfo' => 'myinfo.php'
);
?>
Zwracane wartości
Nie jest zwracana żadna wartość.
Błędy/Wyjątki
Throws PharException when unable to open the internal
file to output, or if
called from a non-stub. If an invalid array value is passed into
mimetypes or to rewrites, then
UnexpectedValueException is thrown.
Przykłady
Przykład #1 A Phar::webPhar() example
With the example below, the created phar will display Hello World if one browses to /myphar.phar/index.php or to /myphar.phar, and will display the source of index.phps if one browses to /myphar.phar/index.phps.
<?php
// creating the phar archive:
try {
$phar = new Phar('myphar.phar');
$phar['index.php'] = '<?php echo "Hello World"; ?>';
$phar['index.phps'] = '<?php echo "Hello World"; ?>';
$phar->setStub('<?php
Phar::webPhar();
__HALT_COMPILER(); ?>');
} catch (Exception $e) {
// handle error here
}
?>
Zobacz też:
- Phar::mungServer() - Defines a list of up to 4 $_SERVER variables that should be modified for execution
- Phar::interceptFileFuncs() - instructs phar to intercept fopen, file_get_contents, opendir, and all of the stat-related functions
Spis treści
- Phar::addEmptyDir — Add an empty directory to the phar archive
- Phar::addFile — Add a file from the filesystem to the phar archive
- Phar::addFromString — Add a file from the filesystem to the phar archive
- Phar::apiVersion — Returns the api version
- Phar::buildFromDirectory — Construct a phar archive from the files within a directory.
- Phar::buildFromIterator — Construct a phar archive from an iterator.
- Phar::canCompress — Returns whether phar extension supports compression using either zlib or bzip2
- Phar::canWrite — Returns whether phar extension supports writing and creating phars
- Phar::compress — Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::compressAllFilesBZIP2 — Compresses all files in the current Phar archive using Bzip2 compression
- Phar::compressAllFilesGZ — Compresses all files in the current Phar archive using Gzip compression
- Phar::compressFiles — Compresses all files in the current Phar archive
- Phar::__construct — Construct a Phar archive object
- Phar::convertToData — Convert a phar archive to a non-executable tar or zip file
- Phar::convertToExecutable — Convert a phar archive to another executable phar archive file format
- Phar::copy — Copy a file internal to the phar archive to another new file within the phar
- Phar::count — Returns the number of entries (files) in the Phar archive
- Phar::createDefaultStub — Create a phar-file format specific stub
- Phar::decompress — Decompresses the entire Phar archive
- Phar::decompressFiles — Decompresses all files in the current Phar archive
- Phar::delMetadata — Deletes the global metadata of the phar
- Phar::delete — Delete a file within a phar archive
- Phar::extractTo — Extract the contents of a phar archive to a directory
- Phar::getMetadata — Returns phar archive meta-data
- Phar::getModified — Return whether phar was modified
- Phar::getSignature — Return MD5/SHA1/SHA256/SHA512/OpenSSL signature of a Phar archive
- Phar::getStub — Return the PHP loader or bootstrap stub of a Phar archive
- Phar::getSupportedCompression — Return array of supported compression algorithms
- Phar::getSupportedSignatures — Return array of supported signature types
- Phar::getVersion — Return version info of Phar archive
- Phar::hasMetadata — Returns whether phar has global meta-data
- Phar::interceptFileFuncs — instructs phar to intercept fopen, file_get_contents, opendir, and all of the stat-related functions
- Phar::isBuffering — Used to determine whether Phar write operations are being buffered, or are flushing directly to disk
- Phar::isCompressed — Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::isFileFormat — Returns true if the phar archive is based on the tar/phar/zip file format depending on the parameter
- Phar::isValidPharFilename — Returns whether the given filename is a valid phar filename
- Phar::isWritable — Returns true if the phar archive can be modified
- Phar::loadPhar — Loads any phar archive with an alias
- Phar::mapPhar — Reads the currently executed file (a phar) and registers its manifest
- Phar::mount — Mount an external path or file to a virtual location within the phar archive
- Phar::mungServer — Defines a list of up to 4 $_SERVER variables that should be modified for execution
- Phar::offsetExists — determines whether a file exists in the phar
- Phar::offsetGet — Gets a PharFileInfo object for a specific file
- Phar::offsetSet — set the contents of an internal file to those of an external file
- Phar::offsetUnset — remove a file from a phar
- Phar::running — Returns the full path on disk or full phar URL to the currently executing Phar archive
- Phar::setAlias — Set the alias for the Phar archive
- Phar::setDefaultStub — Used to set the PHP loader or bootstrap stub of a Phar archive to the default loader
- Phar::setMetadata — Sets phar archive meta-data
- Phar::setSignatureAlgorithm — set the signature algorithm for a phar and apply it.
- Phar::setStub — Used to set the PHP loader or bootstrap stub of a Phar archive
- Phar::startBuffering — Start buffering Phar write operations, do not modify the Phar object on disk
- Phar::stopBuffering — Stop buffering write requests to the Phar archive, and save changes to disk
- Phar::uncompressAllFiles — Uncompresses all files in the current Phar archive
- Phar::unlinkArchive — Completely remove a phar archive from disk and from memory
- Phar::webPhar — mapPhar for web-based phars. front controller for web applications
The PharData class
(No version information available, might only be in SVN)
Wstęp
The PharData class provides a high-level interface to accessing and creating non-executable tar and zip archives. Because these archives do not contain a stub and cannot be executed by the phar extension, it is possible to create and manipulate regular zip and tar files using the PharData class even if phar.readonly php.ini setting is 1.
Krótki opis klasy
$format = 9021976
[, int $compression = 9021976
[, string $extension
]]] )$format = 9021976
[, int $compression = 9021976
[, string $extension
]]] )$alias
[, string $index = "index.php"
[, string $f404
[, array $mimetypes
[, array $rewrites
]]]]] )PharData::addEmptyDir
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::addEmptyDir — Add an empty directory to the tar/zip archive
Opis
$dirname
)With this method, an empty directory is created with path dirname. This method is similar to ZipArchive::addEmptyDir().
Parametry
-
dirname -
The name of the empty directory to create in the phar archive
Zwracane wartości
no return value, exception is thrown on failure.
Przykłady
Przykład #1 A PharData::addEmptyDir() example
<?php
try {
$a = new PharData('/path/to/my.tar');
$a->addEmptyDir('/full/path/to/file');
// demonstrates how this file is stored
$b = $a['full/path/to/file']->isDir();
} catch (Exception $e) {
// handle errors here
}
?>
Zobacz też:
- Phar::addEmptyDir() - Add an empty directory to the phar archive
- PharData::addFile() - Add a file from the filesystem to the tar/zip archive
- PharData::addFromString() - Add a file from the filesystem to the tar/zip archive
PharData::addFile
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::addFile — Add a file from the filesystem to the tar/zip archive
Opis
With this method, any file or URL can be added to the tar/zip archive. If the optional second parameter localname is specified, the file will be stored in the archive with that name, otherwise the file parameter is used as the path to store within the archive. URLs must have a localname or an exception is thrown. This method is similar to ZipArchive::addFile().
Parametry
-
file -
Full or relative path to a file on disk to be added to the phar archive.
-
localname -
Path that the file will be stored in the archive.
Zwracane wartości
no return value, exception is thrown on failure.
Przykłady
Przykład #1 A PharData::addFile() example
<?php
try {
$a = new PharData('/path/to/my.tar');
$a->addFile('/full/path/to/file');
// demonstrates how this file is stored
$b = $a['full/path/to/file']->getContent();
$a->addFile('/full/path/to/file', 'my/file.txt');
$c = $a['my/file.txt']->getContent();
// demonstrate URL usage
$a->addFile('http://www.example.com', 'example.html');
} catch (Exception $e) {
// handle errors here
}
?>
Zobacz też:
- PharData::offsetSet() - set the contents of a file within the tar/zip to those of an external file or string
- Phar::addFile() - Add a file from the filesystem to the phar archive
- PharData::addFromString() - Add a file from the filesystem to the tar/zip archive
- PharData::addEmptyDir() - Add an empty directory to the tar/zip archive
PharData::addFromString
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::addFromString — Add a file from the filesystem to the tar/zip archive
Opis
$localname
, string $contents
)With this method, any string can be added to the tar/zip archive. The file will be stored in the archive with localname as its path. This method is similar to ZipArchive::addFromString().
Parametry
-
localname -
Path that the file will be stored in the archive.
-
contents -
The file contents to store
Zwracane wartości
no return value, exception is thrown on failure.
Przykłady
Przykład #1 A PharData::addFromString() example
<?php
try {
$a = new PharData('/path/to/my.tar');
$a->addFromString('path/to/file.txt', 'my simple file');
$b = $a['path/to/file.txt']->getContent();
// to add contents from a stream handle for large files, use offsetSet()
$c = fopen('/path/to/hugefile.bin');
$a['largefile.bin'] = $c;
fclose($c);
} catch (Exception $e) {
// handle errors here
}
?>
Zobacz też:
- PharData::offsetSet() - set the contents of a file within the tar/zip to those of an external file or string
- Phar::addFromString() - Add a file from the filesystem to the phar archive
- PharData::addFile() - Add a file from the filesystem to the tar/zip archive
- PharData::addEmptyDir() - Add an empty directory to the tar/zip archive
PharData::buildFromDirectory
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::buildFromDirectory — Construct a tar/zip archive from the files within a directory.
Opis
Populate a tar/zip archive from directory contents. The optional second parameter is a regular expression (pcre) that is used to exclude files. Any filename that matches the regular expression will be included, all others will be excluded. For more fine-grained control, use PharData::buildFromIterator().
Parametry
-
base_dir -
The full or relative path to the directory that contains all files to add to the archive.
-
regex -
An optional pcre regular expression that is used to filter the list of files. Only file paths matching the regular expression will be included in the archive.
Zwracane wartości
Phar::buildFromDirectory() returns an associative array mapping internal path of file to the full path of the file on the filesystem.
Błędy/Wyjątki
This method throws BadMethodCallException when unable to instantiate the internal directory iterators, or a PharException if there were errors saving the phar archive.
Przykłady
Przykład #1 A PharData::buildFromDirectory() example
<?php
$phar = new PharData('project.tar');
// add all files in the project
$phar->buildFromDirectory(dirname(__FILE__) . '/project');
$phar2 = new PharData('project2.zip');
// add all files in the project, only include php files
$phar->buildFromDirectory(dirname(__FILE__) . '/project', '/\.php$/');
?>
Zobacz też:
- Phar::buildFromDirectory() - Construct a phar archive from the files within a directory.
- PharData::buildFromIterator() - Construct a tar or zip archive from an iterator.
PharData::buildFromIterator
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::buildFromIterator — Construct a tar or zip archive from an iterator.
Opis
Populate a tar or zip archive from an iterator. Two styles of iterators are supported, iterators that map the filename within the tar/zip to the name of a file on disk, and iterators like DirectoryIterator that return SplFileInfo objects. For iterators that return SplFileInfo objects, the second parameter is required.
Przykłady
Przykład #1 A PharData::buildFromIterator() with SplFileInfo
For most tar/zip archives, the archive will reflect an actual directory layout, and the second style is the most useful. For instance, to create a tar/zip archive containing the files in this sample directory layout:
/path/to/project/
config/
dist.xml
debug.xml
lib/
file1.php
file2.php
src/
processthing.php
www/
index.php
cli/
index.php
This code could be used to add these files to the "project.tar" tar archive:
<?php
$phar = new PharData('project.tar');
$phar->buildFromIterator(
new RecursiveIteratorIterator(
new RecursiveDirectoryIterator('/path/to/project')),
'/path/to/project');
?>
The file project.tar can then be used immediately. PharData::buildFromIterator() does not set values such as compression, metadata, and this can be done after creating the tar/zip archive.
As an interesting note, PharData::buildFromIterator() can also be used to copy the contents of an existing phar, tar or zip archive, as the PharData object descends from DirectoryIterator:
<?php
$phar = new PharData('project.tar');
$phar->buildFromIterator(
new RecursiveIteratorIterator(
new Phar('/path/to/anotherphar.phar')),
'phar:///path/to/anotherphar.phar/path/to/project');
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
?>
Przykład #2 A PharData::buildFromIterator() with other iterators
The second form of the iterator can be used with any iterator that returns a key => value mapping, such as an ArrayIterator:
<?php
$phar = new PharData('project.tar');
$phar->buildFromIterator(
new ArrayIterator(
array(
'internal/file.php' => dirname(__FILE__) . '/somefile.php',
'another/file.jpg' => fopen('/path/to/bigfile.jpg', 'rb'),
)));
?>
Parametry
-
iter -
Any iterator that either associatively maps tar/zip file to location or returns SplFileInfo objects
-
base_directory -
For iterators that return SplFileInfo objects, the portion of each file's full path to remove when adding to the tar/zip archive
Zwracane wartości
PharData::buildFromIterator() returns an associative array mapping internal path of file to the full path of the file on the filesystem.
Błędy/Wyjątki
This method returns UnexpectedValueException when the
iterator returns incorrect values, such as an integer key instead of a
string, a BadMethodCallException when an
SplFileInfo-based iterator is passed without a base_directory
parameter, or a PharException if there were errors
saving the phar archive.
PharData::compress
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::compress — Compresses the entire tar/zip archive using Gzip or Bzip2 compression
Opis
$compression
[, string $extension
] )For tar archives, this method compresses the entire archive using gzip compression or bzip2 compression. The resulting file can be processed with the gunzip command/bunzip command, or accessed directly and transparently with the Phar extension.
For zip archives, this method fails with an exception. The zlib extension must be enabled to compress with gzip compression, the bzip2 extension must be enabled in order to compress with bzip2 compression.
In addition, this method automatically renames the archive, appending .gz, .bz2 or removing the extension if passed Phar::NONE to remove compression. Alternatively, a file extension may be specified with the second parameter.
Parametry
-
compression -
Compression must be one of Phar::GZ, Phar::BZ2 to add compression, or Phar::NONE to remove compression.
-
extension -
By default, the extension is .tar.gz or .tar.bz2 for compressing a tar, and .tar for decompressing.
Zwracane wartości
A PharData object is returned.
Błędy/Wyjątki
Throws BadMethodCallException if the zlib extension is not available, or the bzip2 extension is not enabled.
Przykłady
Przykład #1 A PharData::compress() example
<?php
$p = new PharData('/path/to/my.tar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p1 = $p->compress(Phar::GZ); // copies to /path/to/my.phar.gz
$p2 = $p->compress(Phar::BZ2); // copies to /path/to/my.phar.bz2
$p3 = $p2->compress(Phar::NONE); // exception: /path/to/my.phar already exists
?>
PharData::compressFiles
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::compressFiles — Compresses all files in the current tar/zip archive
Opis
$compression
)For tar-based archives, this method throws a BadMethodCallException, as compression of individual files within a tar archive is not supported by the file format. Use PharData::compress() to compress an entire tar-based archive.
For Zip-based archives, this method compresses all files in the archive using the specified compression. The zlib or bzip2 extensions must be enabled to take advantage of this feature. In addition, if any files are already compressed using bzip2/zlib compression, the respective extension must be enabled in order to decompress the files prior to re-compressing.
Parametry
-
compression -
Compression must be one of Phar::GZ, Phar::BZ2 to add compression, or Phar::NONE to remove compression.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Błędy/Wyjątki
Throws BadMethodCallException if the phar.readonly INI variable is on, the zlib extension is not available, or if any files are compressed using bzip2 compression and the bzip2 extension is not enabled.
Przykłady
Przykład #1 A PharData::compressFiles() example
<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressed(Phar::BZ2));
var_dump($file->isCompressed(Phar::GZ));
}
$p->compressFiles(Phar::GZ);
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressed(Phar::BZ2));
var_dump($file->isCompressed(Phar::GZ));
}
?>
Powyższy przykład wyświetli:
string(10) "myfile.txt" bool(false) bool(false) bool(false) string(11) "myfile2.txt" bool(false) bool(false) bool(false) string(10) "myfile.txt" int(4096) bool(false) bool(true) string(11) "myfile2.txt" int(4096) bool(false) bool(true)
Zobacz też:
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- PharData::decompressFiles() - Decompresses all files in the current zip archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- PharData::compress() - Compresses the entire tar/zip archive using Gzip or Bzip2 compression
- PharData::decompress() - Decompresses the entire Phar archive
PharData::__construct
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::__construct — Construct a non-executable tar or zip archive object
Opis
$fname
[, int $flags
[, string $alias
[, int $format = Phar::TAR
]]] )Parametry
-
fname -
Path to an existing tar/zip archive or to-be-created archive
-
flags -
Flags to pass to Phar parent class RecursiveDirectoryIterator.
-
alias -
Alias with which this Phar archive should be referred to in calls to stream functionality.
-
format -
One of the file format constants available within the Phar class.
Błędy/Wyjątki
Throws BadMethodCallException if called twice; UnexpectedValueException if the Phar archive can't be opened.
Przykłady
Przykład #1 A PharData::__construct() example
<?php
try {
$p = new PharData('/path/to/my.tar', CURRENT_AS_FILEINFO | KEY_AS_FILENAME);
} catch (UnexpectedValueException $e) {
die('Could not open my.tar');
} catch (BadMethodCallException $e) {
echo 'technically, this cannot happen';
}
echo file_get_contents('phar:///path/to/my.tar/example.txt');
?>
PharData::convertToData
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::convertToData — Convert a phar archive to a non-executable tar or zip file
Opis
This method is used to convert a non-executable tar or zip archive to another non-executable format.
If no changes are specified, this method throws a BadMethodCallException. This method should be used to convert a tar archive to zip format or vice-versa. Although it is possible to simply change the compression of a tar archive using this method, it is better to use the PharData::compress() method for logical consistency.
If successful, the method creates a new archive on disk and returns a PharData object. The old archive is not removed from disk, and should be done manually after the process has finished.
Parametry
-
format -
This should be one of Phar::TAR or Phar::ZIP. If set to
NULL, the existing file format will be preserved. -
compression -
This should be one of Phar::NONE for no whole-archive compression, Phar::GZ for zlib-based compression, and Phar::BZ2 for bzip-based compression.
-
extension -
This parameter is used to override the default file extension for a converted archive. Note that .phar cannot be used anywhere in the filename for a non-executable tar or zip archive.
If converting to a tar-based phar archive, the default extensions are .tar, .tar.gz, and .tar.bz2 depending on specified compression. For zip-based archives, the default extension is .zip.
Zwracane wartości
The method returns a PharData object on success and throws an exception on failure.
Błędy/Wyjątki
This method throws BadMethodCallException when unable to compress, an unknown compression method has been specified, the requested archive is buffering with Phar::startBuffering() and has not concluded with Phar::stopBuffering(), and a PharException if any problems are encountered during the phar creation process.
Przykłady
Przykład #1 A PharData::convertToData() example
Using PharData::convertToData():
<?php
try {
$tarphar = new PharData('myphar.tar');
// note that myphar.tar is *not* unlinked
// convert it to the non-executable tar file format
// creates myphar.zip
$zip = $tarphar->convertToData(Phar::ZIP);
// create myphar.tbz
$tgz = $zip->convertToData(Phar::TAR, Phar::BZ2, '.tbz');
// creates myphar.phar.tgz
$phar = $tarphar->convertToData(Phar::PHAR); // throws exception
} catch (Exception $e) {
// handle the error here
}
?>
Zobacz też:
- Phar::convertToExecutable() - Convert a phar archive to another executable phar archive file format
- Phar::convertToData() - Convert a phar archive to a non-executable tar or zip file
- PharData::convertToExecutable() - Convert a non-executable tar/zip archive to an executable phar archive
PharData::convertToExecutable
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::convertToExecutable — Convert a non-executable tar/zip archive to an executable phar archive
Opis
Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
This method is used to convert a non-executable tar or zip archive to an executable phar archive. Any of the three executable file formats (phar, tar or zip) can be used, and whole-archive compression can also be performed.
If no changes are specified, this method throws a BadMethodCallException.
If successful, the method creates a new archive on disk and returns a Phar object. The old archive is not removed from disk, and should be done manually after the process has finished.
Parametry
-
format -
This should be one of Phar::PHAR, Phar::TAR, or Phar::ZIP. If set to
NULL, the existing file format will be preserved. -
compression -
This should be one of Phar::NONE for no whole-archive compression, Phar::GZ for zlib-based compression, and Phar::BZ2 for bzip-based compression.
-
extension -
This parameter is used to override the default file extension for a converted archive. Note that all zip- and tar-based phar archives must contain .phar in their file extension in order to be processed as a phar archive.
If converting to a phar-based archive, the default extensions are .phar, .phar.gz, or .phar.bz2 depending on the specified compression. For tar-based phar archives, the default extensions are .phar.tar, .phar.tar.gz, and .phar.tar.bz2. For zip-based phar archives, the default extension is .phar.zip.
Zwracane wartości
The method returns a Phar object on success and throws an exception on failure.
Błędy/Wyjątki
This method throws BadMethodCallException when unable to compress, an unknown compression method has been specified, the requested archive is buffering with Phar::startBuffering() and has not concluded with Phar::stopBuffering(), an UnexpectedValueException if write support is disabled, and a PharException if any problems are encountered during the phar creation process.
Przykłady
Przykład #1 A PharData::convertToExecutable() example
Using PharData::convertToExecutable():
<?php
try {
$tarphar = new PharData('myphar.tar');
// convert it to the phar file format
// note that myphar.tar is *not* unlinked
$phar = $tarphar->convertToExecutable(Phar::PHAR); // creates myphar.phar
$phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
// creates myphar.phar.tgz
$compressed = $tarphar->convertToExecutable(Phar::TAR, Phar::GZ, '.phar.tgz');
} catch (Exception $e) {
// handle the error here
}
?>
Zobacz też:
- Phar::convertToExecutable() - Convert a phar archive to another executable phar archive file format
- Phar::convertToData() - Convert a phar archive to a non-executable tar or zip file
- PharData::convertToData() - Convert a phar archive to a non-executable tar or zip file
PharData::copy
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::copy — Copy a file internal to the phar archive to another new file within the phar
Opis
$oldfile
, string $newfile
)Copy a file internal to the tar/zip archive to another new file within the same archive. This is an object-oriented alternative to using copy() with the phar stream wrapper.
Parametry
-
oldfile -
-
newfile -
Zwracane wartości
returns TRUE on success, but it is safer to encase method call in a
try/catch block and assume success if no exception is thrown.
Błędy/Wyjątki
throws UnexpectedValueException if the source file does not exist, the destination file already exists, write access is disabled, opening either file fails, reading the source file fails, or a PharException if writing the changes to the phar fails.
Przykłady
Przykład #1 A PharData::copy() example
This example shows using PharData::copy() and the equivalent stream wrapper performance of the same thing. The primary difference between the two approaches is error handling. All PharData methods throw exceptions, whereas the stream wrapper uses trigger_error().
<?php
try {
$phar = new PharData('myphar.tar');
$phar['a'] = 'hi';
$phar->copy('a', 'b');
echo $phar['b']; // outputs "phar://myphar.tar/b"
} catch (Exception $e) {
// handle error
}
// the stream wrapper equivalent of the above code.
// E_WARNINGS are triggered on error rather than exceptions.
copy('phar://myphar.tar/a', 'phar//myphar.tar/c');
echo file_get_contents('phar://myphar.tar/c'); // outputs "hi"
?>
PharData::decompress
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::decompress — Decompresses the entire Phar archive
Opis
$extension
] )For tar-based archives, this method decompresses the entire archive.
For Zip-based archives, this method fails with an exception. The zlib extension must be enabled to decompress an archive compressed with gzip compression, and the bzip2 extension must be enabled in order to decompress an archive compressed with bzip2 compression.
In addition, this method automatically renames the file extension of the archive, .tar by default. Alternatively, a file extension may be specified with the second parameter.
Parametry
-
extension -
For decompressing, the default file extension is .phar.tar. Use this parameter to specify another file extension. Be aware that no non-executable archives cannot contain .phar in their filename.
Zwracane wartości
A PharData object is returned.
Błędy/Wyjątki
Throws BadMethodCallException if the zlib extension is not available, or the bzip2 extension is not enabled.
Przykłady
Przykład #1 A PharData::decompress() example
<?php
$p = new PharData('/path/to/my.tar', 0, 'my.tar.gz');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p3 = $p2->decompress(); // creates /path/to/my.tar
?>
Zobacz też:
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- PharData::compress() - Compresses the entire tar/zip archive using Gzip or Bzip2 compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- PharData::compress() - Compresses the entire tar/zip archive using Gzip or Bzip2 compression
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- PharData::compressFiles() - Compresses all files in the current tar/zip archive
- PharData::decompressFiles() - Decompresses all files in the current zip archive
PharData::decompressFiles
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::decompressFiles — Decompresses all files in the current zip archive
Opis
Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
For tar-based archives, this method throws a BadMethodCallException, as compression of individual files within a tar archive is not supported by the file format. Use PharData::compress() to compress an entire tar-based archive.
For Zip-based archives, this method decompresses all files in the archive. The zlib or bzip2 extensions must be enabled to take advantage of this feature if any files are compressed using bzip2/zlib compression.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Błędy/Wyjątki
Throws BadMethodCallException if the zlib extension is not available, or if any files are compressed using bzip2 compression and the bzip2 extension is not enabled.
Przykłady
Przykład #1 A PharData::decompressFiles() example
<?php
$p = new PharData('/path/to/my.zip');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p->compressFiles(Phar::GZ);
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressed(Phar::BZ2));
var_dump($file->isCompressed(Phar::GZ));
}
$p->decompressFiles();
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressed(Phar::BZ2));
var_dump($file->isCompressed(Phar::GZ));
}
?>
Powyższy przykład wyświetli:
string(10) "myfile.txt" int(4096) bool(false) bool(true) string(11) "myfile2.txt" int(4096) bool(false) bool(true) string(10) "myfile.txt" bool(false) bool(false) bool(false) string(11) "myfile2.txt" bool(false) bool(false) bool(false)
Zobacz też:
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- PharData::compressFiles() - Compresses all files in the current tar/zip archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- PharData::compress() - Compresses the entire tar/zip archive using Gzip or Bzip2 compression
- PharData::decompress() - Decompresses the entire Phar archive
PharData::delMetadata
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::delMetadata — Deletes the global metadata of a zip archive
Opis
Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
Deletes the global metadata of the zip archive
Parametry
Zwracane wartości
returns TRUE on success, but it is better to check for thrown exception,
and assume success if none is thrown.
Błędy/Wyjątki
Throws PharException if errors occur while flushing changes to disk.
Przykłady
Przykład #1 A PharData::delMetaData() example
<?php
try {
$phar = new PharData('myphar.zip');
var_dump($phar->getMetadata());
$phar->setMetadata("hi there");
var_dump($phar->getMetadata());
$phar->delMetadata();
var_dump($phar->getMetadata());
} catch (Exception $e) {
// handle errors
}
?>
Powyższy przykład wyświetli:
NULL string(8) "hi there" NULL
PharData::delete
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::delete — Delete a file within a tar/zip archive
Opis
$entry
)Delete a file within an archive. This is the functional equivalent of calling unlink() on the stream wrapper equivalent, as shown in the example below.
Parametry
-
entry -
Path within an archive to the file to delete.
Zwracane wartości
returns TRUE on success, but it is better to check for thrown exception,
and assume success if none is thrown.
Błędy/Wyjątki
Throws PharException if errors occur while flushing changes to disk.
Przykłady
Przykład #1 A PharData::delete() example
<?php
try {
$phar = new PharData('myphar.zip');
$phar->delete('unlink/me.php');
// this is equivalent to:
unlink('phar://myphar.phar/unlink/me.php');
} catch (Exception $e) {
// handle errors
}
?>
PharData::extractTo
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::extractTo — Extract the contents of a tar/zip archive to a directory
Opis
$pathto
[, string|array $files
[, bool $overwrite = false
]] )Extract all files within a tar/zip archive to disk. Extracted files and directories preserve permissions as stored in the archive. The optional parameters allow optional control over which files are extracted, and whether existing files on disk can be overwritten. The second parameter files can be either the name of a file or directory to extract, or an array of names of files and directories to extract. By default, this method will not overwrite existing files, the third parameter can be set to true to enable overwriting of files. This method is similar to ZipArchive::extractTo().
Parametry
-
pathto -
Path within an archive to the file to delete.
-
files -
The name of a file or directory to extract, or an array of files/directories to extract
-
overwrite -
Set to
TRUEto enable overwriting existing files
Zwracane wartości
returns TRUE on success, but it is better to check for thrown exception,
and assume success if none is thrown.
Błędy/Wyjątki
Throws PharException if errors occur while flushing changes to disk.
Przykłady
Przykład #1 A PharData::extractTo() example
<?php
try {
$phar = new PharData('myphar.tar');
$phar->extractTo('/full/path'); // extract all files
$phar->extractTo('/another/path', 'file.txt'); // extract only file.txt
$phar->extractTo('/this/path',
array('file1.txt', 'file2.txt')); // extract 2 files only
$phar->extractTo('/third/path', null, true); // extract all files, and overwrite
} catch (Exception $e) {
// handle errors
}
?>
PharData::isWritable
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::isWritable — Returns true if the tar/zip archive can be modified
Opis
This method returns TRUE if the tar/zip archive on disk is not read-only.
Unlike Phar::isWritable(), data-only tar/zip archives
can be modified even if phar.readonly is set to 1.
Parametry
No parameters.
Zwracane wartości
Returns TRUE if the tar/zip archive can be modified
Zobacz też:
- Phar::canWrite() - Returns whether phar extension supports writing and creating phars
- Phar::isWritable() - Returns true if the phar archive can be modified
PharData::offsetSet
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::offsetSet — set the contents of a file within the tar/zip to those of an external file or string
Opis
$offset
, string $value
)This is an implementation of the ArrayAccess interface allowing direct manipulation of the contents of a tar/zip archive using array access brackets. offsetSet is used for modifying an existing file, or adding a new file to a tar/zip archive.
Parametry
-
offset -
The filename (relative path) to modify in a tar or zip archive.
-
value -
Content of the file.
Zwracane wartości
No return values.
Błędy/Wyjątki
Throws PharException if there are any problems flushing changes made to the tar/zip archive to disk.
Przykłady
Przykład #1 A PharData::offsetSet() example
offsetSet should not be accessed directly, but instead used via array access with the [] operator.
<?php
$p = new PharData('/path/to/my.tar');
try {
// calls offsetSet
$p['file.txt'] = 'Hi there';
} catch (Exception $e) {
echo 'Could not modify file.txt:', $e;
}
?>
PharData::offsetUnset
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::offsetUnset — remove a file from a tar/zip archive
Opis
$offset
)This is an implementation of the ArrayAccess interface allowing direct manipulation of the contents of a tar/zip archive using array access brackets. offsetUnset is used for deleting an existing file, and is called by the unset() language construct.
Parametry
-
offset -
The filename (relative path) to modify in the tar/zip archive.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Błędy/Wyjątki
Throws PharException if there are any problems flushing changes made to the tar/zip archive to disk.
Przykłady
Przykład #1 A PharData::offsetUnset() example
<?php
$p = new PharData('/path/to/my.zip');
try {
// deletes file.txt from my.zip by calling offsetUnset
unset($p['file.txt']);
} catch (Exception $e) {
echo 'Could not delete file.txt: ', $e;
}
?>
PharData::setAlias
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::setAlias — dummy function (Phar::setAlias is not valid for PharData)
Opis
$alias
)Non-executable tar/zip archives cannot have an alias, so this method simply throws an exception.
Parametry
-
alias -
A shorthand string that this archive can be referred to in phar stream wrapper access. This parameter is ignored.
Zwracane wartości
Błędy/Wyjątki
Throws PharException on all method calls
PharData::setDefaultStub
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::setDefaultStub — dummy function (Phar::setDefaultStub is not valid for PharData)
Opis
$index
[, string $webindex
]] )Non-executable tar/zip archives cannot have a stub, so this method simply throws an exception.
Parametry
-
index -
Relative path within the phar archive to run if accessed on the command-line
-
webindex -
Relative path within the phar archive to run if accessed through a web browser
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Błędy/Wyjątki
Throws PharException on all method calls
Zobacz też:
- Phar::setDefaultStub() - Used to set the PHP loader or bootstrap stub of a Phar archive to the default loader
Phar::setMetadata
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::setMetadata — Sets phar archive meta-data
Opis
Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
Phar::setMetadata() should be used to store customized data that describes something about the phar archive as a complete entity. PharFileInfo::setMetadata() should be used for file-specific meta-data. Meta-data can slow down the performance of loading a phar archive if the data is large.
Some possible uses for meta-data include specifying which file within the archive should be used to bootstrap the archive, or the location of a file manifest like » PEAR's package.xml file. However, any useful data that describes the phar archive may be stored.
Parametry
-
metadata -
Any PHP variable containing information to store that describes the phar archive
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 A Phar::setMetadata() example
<?php
// make sure it doesn't exist
@unlink('brandnewphar.phar');
try {
$p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
$p['file.php'] = '<?php echo "hello"';
$p->setMetadata(array('bootstrap' => 'file.php'));
var_dump($p->getMetadata());
} catch (Exception $e) {
echo 'Could not create and/or modify phar:', $e;
}
?>
Powyższy przykład wyświetli:
array(1) {
["bootstrap"]=>
string(8) "file.php"
}
Zobacz też:
- Phar::getMetadata() - Returns phar archive meta-data
- Phar::delMetadata() - Deletes the global metadata of the phar
- Phar::hasMetadata() - Returns whether phar has global meta-data
Phar::setSignatureAlgorithm
(PHP >= 5.3.0, PECL phar >= 1.1.0)
Phar::setSignatureAlgorithm — set the signature algorithm for a phar and apply it. The
Opis
$sigtype
)Informacja:
Ta metoda wymaga ustawienia w php.ini wartości phar.readonly na 0 aby działała z obiektami Phar. W przeciwnym przypadku, klasa PharException zwróci wyjątek .
set the signature algorithm for a phar and apply it. The signature algorithm must be one of Phar::MD5, Phar::SHA1, Phar::SHA256, Phar::SHA512, or Phar::PGP (pgp not yet supported and falls back to SHA-1).
Parametry
-
sigtype -
One of Phar::MD5, Phar::SHA1, Phar::SHA256, Phar::SHA512, or Phar::PGP
Zwracane wartości
Nie jest zwracana żadna wartość.
Błędy/Wyjątki
Throws UnexpectedValueException for many errors, BadMethodCallException if called for a zip- or a tar-based phar archive, and a PharException if any problems occur flushing changes to disk.
Zobacz też:
- Phar::getSupportedSignatures() - Return array of supported signature types
- Phar::getSignature() - Return MD5/SHA1/SHA256/SHA512/OpenSSL signature of a Phar archive
PharData::setStub
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::setStub — dummy function (Phar::setStub is not valid for PharData)
Opis
$stub
)Non-executable tar/zip archives cannot have a stub, so this method simply throws an exception.
Parametry
-
stub -
A string or an open stream handle to use as the executable stub for this phar archive. This parameter is ignored.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Błędy/Wyjątki
Throws PharException on all method calls
Spis treści
- PharData::addEmptyDir — Add an empty directory to the tar/zip archive
- PharData::addFile — Add a file from the filesystem to the tar/zip archive
- PharData::addFromString — Add a file from the filesystem to the tar/zip archive
- PharData::buildFromDirectory — Construct a tar/zip archive from the files within a directory.
- PharData::buildFromIterator — Construct a tar or zip archive from an iterator.
- PharData::compress — Compresses the entire tar/zip archive using Gzip or Bzip2 compression
- PharData::compressFiles — Compresses all files in the current tar/zip archive
- PharData::__construct — Construct a non-executable tar or zip archive object
- PharData::convertToData — Convert a phar archive to a non-executable tar or zip file
- PharData::convertToExecutable — Convert a non-executable tar/zip archive to an executable phar archive
- PharData::copy — Copy a file internal to the phar archive to another new file within the phar
- PharData::decompress — Decompresses the entire Phar archive
- PharData::decompressFiles — Decompresses all files in the current zip archive
- PharData::delMetadata — Deletes the global metadata of a zip archive
- PharData::delete — Delete a file within a tar/zip archive
- PharData::extractTo — Extract the contents of a tar/zip archive to a directory
- PharData::isWritable — Returns true if the tar/zip archive can be modified
- PharData::offsetSet — set the contents of a file within the tar/zip to those of an external file or string
- PharData::offsetUnset — remove a file from a tar/zip archive
- PharData::setAlias — dummy function (Phar::setAlias is not valid for PharData)
- PharData::setDefaultStub — dummy function (Phar::setDefaultStub is not valid for PharData)
- Phar::setMetadata — Sets phar archive meta-data
- Phar::setSignatureAlgorithm — set the signature algorithm for a phar and apply it. The
- PharData::setStub — dummy function (Phar::setStub is not valid for PharData)
The PharFileInfo class
(No version information available, might only be in SVN)
Wstęp
The PharFileInfo class provides a high-level interface to the contents and attributes of a single file within a phar archive.
Krótki opis klasy
PharFileInfo::chmod
(PHP >= 5.3.0, PECL phar >= 1.0.0)
PharFileInfo::chmod — Sets file-specific permission bits
Opis
$permissions
)PharFileInfo::chmod() allows setting of the executable file permissions bit, as well as read-only bits. Writeable bits are ignored, and set at runtime based on the phar.readonly INI variable. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed if the file is within a Phar archive. Files within PharData archives do not have this restriction.
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 A PharFileInfo::chmod() example
<?php
// make sure it doesn't exist
@unlink('brandnewphar.phar');
try {
$p = new Phar('brandnewphar.phar', 0, 'brandnewphar.phar');
$p['file.sh'] = '#!/usr/local/lib/php
<?php echo "hi"; ?>';
// set executable bit
$p['file.sh']->chmod(0555);
var_dump($p['file.sh']->isExecutable());
} catch (Exception $e) {
echo 'Could not create/modify phar: ', $e;
}
?>
Powyższy przykład wyświetli:
bool(true)
PharFileInfo::compress
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharFileInfo::compress — Compresses the current Phar entry with either zlib or bzip2 compression
Opis
$compression
)This method compresses the file inside the Phar archive using either bzip2 compression or zlib compression. The bzip2 or zlib extension must be enabled to take advantage of this feature. In addition, if the file is already compressed, the respective extension must be enabled in order to decompress the file. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed if the file is within a Phar archive. Files within PharData archives do not have this restriction.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Błędy/Wyjątki
Throws BadMethodCallException if the phar.readonly INI variable is on, or if the bzip2/zlib extension is not available.
Przykłady
Przykład #1 A PharFileInfo::compress() example
<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$file = $p['myfile.txt'];
var_dump($file->isCompressed(Phar::BZ2));
$p['myfile.txt']->compress(Phar::BZ2);
var_dump($file->isCompressed(Phar::BZ2));
} catch (Exception $e) {
echo 'Create/modify operations on my.phar failed: ', $e;
}
?>
Powyższy przykład wyświetli:
bool(false) bool(true)
Zobacz też:
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressFiles() - Compresses all files in the current Phar archive
- Phar::decompressFiles() - Decompresses all files in the current Phar archive
- Phar::compress() - Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::decompress() - Decompresses the entire Phar archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms
PharFileInfo::__construct
(PHP >= 5.3.0, PECL phar >= 1.0.0)
PharFileInfo::__construct — Construct a Phar entry object
Opis
$entry
)This should not be called directly. Instead, a PharFileInfo object is initialized by calling Phar::offsetGet() through array access.
Parametry
-
entry -
The full url to retrieve a file. If you wish to retrieve the information for the file my/file.php from the phar boo.phar, the entry should be phar://boo.phar/my/file.php.
Błędy/Wyjątki
Throws BadMethodCallException if __construct() is called twice. Throws UnexpectedValueException if the phar URL requested is malformed, the requested phar cannot be opened, or the file can't be found within the phar.
Przykłady
Przykład #1 A PharFileInfo::__construct() example
<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['testfile.txt'] = "hi\nthere\ndude";
$file = $p['testfile.txt'];
foreach ($file as $line => $text) {
echo "line number $line: $text";
}
// this also works
$file = new PharFileInfo('phar:///path/to/my.phar/testfile.txt');
foreach ($file as $line => $text) {
echo "line number $line: $text";
}
} catch (Exception $e) {
echo 'Phar operations failed: ', $e;
}
?>
Powyższy przykład wyświetli:
line number 1: hi line number 2: there line number 3: dude line number 1: hi line number 2: there line number 3: dude
PharFileInfo::decompress
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharFileInfo::decompress — Decompresses the current Phar entry within the phar
Opis
This method decompresses the file inside the Phar archive. Depending on how the file is compressed, the bzip2 or zlib extensions must be enabled to take advantage of this feature. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed if the file is within a Phar archive. Files within PharData archives do not have this restriction.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Błędy/Wyjątki
Throws BadMethodCallException if the phar.readonly INI variable is on, or if the bzip2/zlib extension is not available.
Przykłady
Przykład #1 A PharFileInfo::decompress() example
<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$file = $p['myfile.txt'];
$file->compress(Phar::GZ);
var_dump($file->isCompressed());
$p['myfile.txt']->decompress();
var_dump($file->isCompressed());
} catch (Exception $e) {
echo 'Create/modify failed for my.phar: ', $e;
}
?>
Powyższy przykład wyświetli:
int(4096) bool(false)
Zobacz też:
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressFiles() - Compresses all files in the current Phar archive
- Phar::decompressFiles() - Decompresses all files in the current Phar archive
- Phar::compress() - Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::decompress() - Decompresses the entire Phar archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms
PharFileInfo::delMetadata
(PHP >= 5.3.0, PECL phar >= 1.2.0)
PharFileInfo::delMetadata — Deletes the metadata of the entry
Opis
Deletes the metadata of the entry, if any.
Parametry
No parameters.
Zwracane wartości
Returns TRUE if successful, FALSE if the entry had no metadata.
As with all functionality that modifies the contents of
a phar, the phar.readonly INI variable
must be off in order to succeed if the file is within a Phar
archive. Files within PharData archives do not have
this restriction.
Błędy/Wyjątki
Throws PharException if errors occurred while flushing changes to disk, and BadMethodCallException if write access is disabled.
Przykłady
Przykład #1 A PharFileInfo::delMetaData() example
<?php
try {
$a = new Phar('myphar.phar');
$a['hi'] = 'hi';
var_dump($a['hi']->delMetadata());
$a['hi']->setMetadata('there');
var_dump($a['hi']->delMetadata());
var_dump($a['hi']->delMetadata());
} catch (Exception $e) {
// handle errors
}
?>
Powyższy przykład wyświetli:
bool(false) bool(true) bool(false)
Zobacz też:
- PharFileInfo::setMetadata() - Sets file-specific meta-data saved with a file
- PharFileInfo::hasMetadata() - Returns the metadata of the entry
- PharFileInfo::getMetadata() - Returns file-specific meta-data saved with a file
- Phar::setMetadata() - Sets phar archive meta-data
- Phar::hasMetadata() - Returns whether phar has global meta-data
- Phar::getMetadata() - Returns phar archive meta-data
PharFileInfo::getCRC32
(PHP >= 5.3.0, PECL phar >= 1.0.0)
PharFileInfo::getCRC32 — Returns CRC32 code or throws an exception if CRC has not been verified
Opis
This returns the crc32() checksum of the file within the Phar archive.
Zwracane wartości
The crc32() checksum of the file within the Phar archive.
Błędy/Wyjątki
Throws BadMethodCallException if the file has not yet had its CRC32 verified. This should be impossible with normal use, as the CRC is verified upon opening the file for reading or writing.
Przykłady
Przykład #1 A PharFileInfo::getCRC32() example
<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$file = $p['myfile.txt'];
echo $file->getCRC32();
} catch (Exception $e) {
echo 'Write operations on my.phar.phar failed: ', $e;
}
?>
Powyższy przykład wyświetli:
3633523372
PharFileInfo::getCompressedSize
(PHP >= 5.3.0, PECL phar >= 1.0.0)
PharFileInfo::getCompressedSize — Returns the actual size of the file (with compression) inside the Phar archive
Opis
This returns the size of the file within the Phar archive. Uncompressed files will return the same value for getCompressedSize as they will with filesize()
Zwracane wartości
The size in bytes of the file within the Phar archive on disk.
Przykłady
Przykład #1 A PharFileInfo::getCompressedSize() example
<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$file = $p['myfile.txt'];
echo $file->getCompressedSize();
} catch (Exception $e) {
echo 'Write operations failed on my.phar: ', $e;
}
?>
Powyższy przykład wyświetli:
2
Zobacz też:
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compress() - Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::decompress() - Decompresses the entire Phar archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::decompressFiles() - Decompresses all files in the current Phar archive
- Phar::compressFiles() - Compresses all files in the current Phar archive
PharFileInfo::getMetadata
(PHP >= 5.3.0, PECL phar >= 1.0.0)
PharFileInfo::getMetadata — Returns file-specific meta-data saved with a file
Opis
Return meta-data that was saved in the Phar archive's manifest for this file.
Parametry
Zwracane wartości
any PHP variable that can be serialized and is stored as meta-data for the file,
or NULL if no meta-data is stored.
Przykłady
Przykład #1 A PharFileInfo::getMetadata() example
<?php
// make sure it doesn't exist
@unlink('brandnewphar.phar');
try {
$p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
$p['file.txt'] = 'hello';
$p['file.txt']->setMetadata(array('user' => 'bill', 'mime-type' => 'text/plain'));
var_dump($p['file.txt']->getMetadata());
} catch (Exception $e) {
echo 'Could not create/modify brandnewphar.phar: ', $e;
}
?>
Powyższy przykład wyświetli:
array(2) {
["user"]=>
string(4) "bill"
["mime-type"]=>
string(10) "text/plain"
}
Zobacz też:
- PharFileInfo::setMetadata() - Sets file-specific meta-data saved with a file
- PharFileInfo::hasMetadata() - Returns the metadata of the entry
- PharFileInfo::delMetadata() - Deletes the metadata of the entry
- Phar::setMetadata() - Sets phar archive meta-data
- Phar::hasMetadata() - Returns whether phar has global meta-data
- Phar::getMetadata() - Returns phar archive meta-data
PharFileInfo::getPharFlags
(PHP >= 5.3.0, PECL phar >= 1.0.0)
PharFileInfo::getPharFlags — Returns the Phar file entry flags
Opis
This returns the flags set in the manifest for a Phar. This will always return 0 in the current implementation.
Zwracane wartości
The Phar flags (always 0 in the current implementation)
Przykłady
Przykład #1 A PharFileInfo::getPharFlags() example
<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$file = $p['myfile.txt'];
var_dump($file->getPharFlags());
} catch (Exception $e) {
echo 'Could not create/modify my.phar: ', $e;
}
?>
Powyższy przykład wyświetli:
int(0)
PharFileInfo::hasMetadata
(PHP >= 5.3.0, PECL phar >= 1.2.0)
PharFileInfo::hasMetadata — Returns the metadata of the entry
Opis
Returns the metadata of a file within a phar archive.
Parametry
No parameters.
Zwracane wartości
Returns FALSE if no metadata is set or is NULL, TRUE if metadata is not NULL
Zobacz też:
- PharFileInfo::setMetadata() - Sets file-specific meta-data saved with a file
- PharFileInfo::getMetadata() - Returns file-specific meta-data saved with a file
- PharFileInfo::delMetadata() - Deletes the metadata of the entry
- Phar::setMetadata() - Sets phar archive meta-data
- Phar::hasMetadata() - Returns whether phar has global meta-data
- Phar::getMetadata() - Returns phar archive meta-data
PharFileInfo::isCRCChecked
(PHP >= 5.3.0, PECL phar >= 1.0.0)
PharFileInfo::isCRCChecked — Returns whether file entry has had its CRC verified
Opis
This returns whether a file within a Phar archive has had its CRC verified.
Zwracane wartości
TRUE if the file has had its CRC verified, FALSE if not.
Przykłady
Przykład #1 A PharFileInfo::isCRCChecked() example
<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$file = $p['myfile.txt'];
var_dump($file->isCRCChecked());
} catch (Exception $e) {
echo 'Create/modify operations failed on my.phar: ', $e;
}
?>
Powyższy przykład wyświetli:
bool(true)
PharFileInfo::isCompressed
(PHP >= 5.3.0, PECL phar >= 1.0.0)
PharFileInfo::isCompressed — Returns whether the entry is compressed
Opis
$compression_type = 9021976
] )This returns whether a file is compressed within a Phar archive with either Gzip or Bzip2 compression.
Parametry
-
compression_type -
One of
Phar::GZorPhar::BZ2, defaults to any compression.
Zwracane wartości
TRUE if the file is compressed within the Phar archive, FALSE if not.
Przykłady
Przykład #1 A PharFileInfo::isCompressed() example
<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p['myfile2.txt']->setCompressedGZ();
$file = $p['myfile.txt'];
$file2 = $p['myfile2.txt'];
var_dump($file->isCompressed());
var_dump($file2->isCompressed());
} catch (Exception $e) {
echo 'Create/modify on phar my.phar failed: ', $e;
}
?>
Powyższy przykład wyświetli:
bool(false) bool(true)
Zobacz też:
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- Phar::decompress() - Decompresses the entire Phar archive
- Phar::compress() - Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::decompressFiles() - Decompresses all files in the current Phar archive
- Phar::compressFiles() - Compresses all files in the current Phar archive
PharFileInfo::isCompressedBZIP2
(PHP >= 5.3.0, PECL phar >= 1.0.0)
PharFileInfo::isCompressedBZIP2 — Returns whether the entry is compressed using bzip2
Opis
Informacja:
Ta metoda została usunięta z rozszerzenia phar w wersji 2.0.0. Dostępne są zastępcze implementacje: PharFileInfo::isCompressed(), PharFileInfo::decompress(), i PharFileInfo::compress().
This returns whether a file is compressed within a Phar archive with Bzip2 compression.
Zwracane wartości
TRUE if the file is compressed within the Phar archive using Bzip2, FALSE if not.
Przykłady
Przykład #1 A PharFileInfo::isCompressedBZIP2() example
<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p['myfile3.txt'] = 'hi';
$p['myfile2.txt']->setCompressedGZ();
$p['myfile3.txt']->setCompressedBZIP2();
$file = $p['myfile.txt'];
$file2 = $p['myfile2.txt'];
$file3 = $p['myfile3.txt'];
var_dump($file->isCompressedBZIP2());
var_dump($file2->isCompressedBZIP2());
var_dump($file3->isCompressedBZIP2());
} catch (Exception $e) {
echo 'Create/modify on phar my.phar failed: ', $e;
}
?>
Powyższy przykład wyświetli:
bool(false) bool(false) bool(true)
Zobacz też:
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::isCompressedGZ() - Returns whether the entry is compressed using gz
- PharFileInfo::setCompressedBZIP2() - Compresses the current Phar entry within the phar using Bzip2 compression
- PharFileInfo::setUncompressed() - Uncompresses the current Phar entry within the phar, if it is compressed
- PharFileInfo::setCompressedGZ() - Compresses the current Phar entry within the phar using gz compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressAllFilesBZIP2() - Compresses all files in the current Phar archive using Bzip2 compression
- Phar::compressAllFilesGZ() - Compresses all files in the current Phar archive using Gzip compression
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::uncompressAllFiles() - Uncompresses all files in the current Phar archive
PharFileInfo::isCompressedGZ
(PHP >= 5.3.0, PECL phar >= 1.0.0)
PharFileInfo::isCompressedGZ — Returns whether the entry is compressed using gz
Opis
Informacja:
Ta metoda została usunięta z rozszerzenia phar w wersji 2.0.0. Dostępne są zastępcze implementacje: PharFileInfo::isCompressed(), PharFileInfo::decompress(), i PharFileInfo::compress().
This returns whether a file is compressed within a Phar archive with Gzip compression.
Zwracane wartości
TRUE if the file is compressed within the Phar archive using Gzip, FALSE if not.
Przykłady
Przykład #1 A PharFileInfo::isCompressedGZ() example
<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p['myfile3.txt'] = 'hi';
$p['myfile2.txt']->setCompressedGZ();
$p['myfile3.txt']->setCompressedBZIP2();
$file = $p['myfile.txt'];
$file2 = $p['myfile2.txt'];
$file3 = $p['myfile3.txt'];
var_dump($file->isCompressedGZ());
var_dump($file2->isCompressedGZ());
var_dump($file3->isCompressedGZ());
} catch (Exception $e) {
echo 'Create/modify on phar my.phar failed: ', $e;
}
?>
Powyższy przykład wyświetli:
bool(false) bool(true) bool(false)
Zobacz też:
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressedBZIP2() - Returns whether the entry is compressed using bzip2
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::setCompressedBZIP2() - Compresses the current Phar entry within the phar using Bzip2 compression
- PharFileInfo::setUncompressed() - Uncompresses the current Phar entry within the phar, if it is compressed
- PharFileInfo::setCompressedGZ() - Compresses the current Phar entry within the phar using gz compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressAllFilesBZIP2() - Compresses all files in the current Phar archive using Bzip2 compression
- Phar::compressAllFilesGZ() - Compresses all files in the current Phar archive using Gzip compression
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::uncompressAllFiles() - Uncompresses all files in the current Phar archive
PharFileInfo::setCompressedBZIP2
(PHP >= 5.3.0, PECL phar >= 1.0.0)
PharFileInfo::setCompressedBZIP2 — Compresses the current Phar entry within the phar using Bzip2 compression
Opis
Informacja:
Ta metoda została usunięta z rozszerzenia phar w wersji 2.0.0. Dostępne są zastępcze implementacje: PharFileInfo::isCompressed(), PharFileInfo::decompress(), i PharFileInfo::compress().
This method compresses the file inside the Phar archive using bzip2 compression. The bzip2 extension must be enabled to take advantage of this feature. In addition, if the file is already compressed using gzip compression, the zlib extension must be enabled in order to decompress the file. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Błędy/Wyjątki
Throws BadMethodCallException if the phar.readonly INI variable is on, or if the bzip2 extension is not available.
Przykłady
Przykład #1 A PharFileInfo::setCompressedBZIP2() example
<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$file = $p['myfile.txt'];
var_dump($file->isCompressedBZIP2());
$p['myfile.txt']->setCompressedBZIP2();
var_dump($file->isCompressedBZIP2());
} catch (Exception $e) {
echo 'Create/modify operations on my.phar failed: ', $e;
}
?>
Powyższy przykład wyświetli:
bool(false) bool(true)
Zobacz też:
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressedBZIP2() - Returns whether the entry is compressed using bzip2
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::isCompressedGZ() - Returns whether the entry is compressed using gz
- PharFileInfo::setUncompressed() - Uncompresses the current Phar entry within the phar, if it is compressed
- PharFileInfo::setCompressedGZ() - Compresses the current Phar entry within the phar using gz compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressAllFilesBZIP2() - Compresses all files in the current Phar archive using Bzip2 compression
- Phar::compressAllFilesGZ() - Compresses all files in the current Phar archive using Gzip compression
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::uncompressAllFiles() - Uncompresses all files in the current Phar archive
PharFileInfo::setCompressedGZ
(PHP >= 5.3.0, PECL phar >= 1.0.0)
PharFileInfo::setCompressedGZ — Compresses the current Phar entry within the phar using gz compression
Opis
Informacja:
Ta metoda została usunięta z rozszerzenia phar w wersji 2.0.0. Dostępne są zastępcze implementacje: PharFileInfo::isCompressed(), PharFileInfo::decompress(), i PharFileInfo::compress().
This method compresses the file inside the Phar archive using gzip compression. The zlib extension must be enabled to take advantage of this feature. In addition, if the file is already compressed using bzip2 compression, the bzip2 extension must be enabled in order to decompress the file. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Błędy/Wyjątki
Throws BadMethodCallException if the phar.readonly INI variable is on, or if the zlib extension is not available.
Przykłady
Przykład #1 A PharFileInfo::setCompressedGZ() example
<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$file = $p['myfile.txt'];
var_dump($file->isCompressedGZ());
$p['myfile.txt']->setCompressedGZ();
var_dump($file->isCompressedGZ());
} catch (Exception $e) {
echo 'Create/modify operations on my.phar failed: ', $e;
}
?>
Powyższy przykład wyświetli:
bool(false) bool(true)
Zobacz też:
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressedBZIP2() - Returns whether the entry is compressed using bzip2
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::isCompressedGZ() - Returns whether the entry is compressed using gz
- PharFileInfo::setCompressedBZIP2() - Compresses the current Phar entry within the phar using Bzip2 compression
- PharFileInfo::setUncompressed() - Uncompresses the current Phar entry within the phar, if it is compressed
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressAllFilesBZIP2() - Compresses all files in the current Phar archive using Bzip2 compression
- Phar::compressAllFilesGZ() - Compresses all files in the current Phar archive using Gzip compression
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::uncompressAllFiles() - Uncompresses all files in the current Phar archive
PharFileInfo::setMetadata
(PHP >= 5.3.0, PECL phar >= 1.0.0)
PharFileInfo::setMetadata — Sets file-specific meta-data saved with a file
Opis
PharFileInfo::setMetadata() should only be used to store customized data in a file that cannot be represented with existing information stored with a file. Meta-data can significantly slow down the performance of loading a phar archive if the data is large, or if there are many files containing meta-data. It is important to note that file permissions are natively supported inside a phar; it is possible to set them with the PharFileInfo::chmod() method. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed if the file is within a Phar archive. Files within PharData archives do not have this restriction.
Some possible uses for meta-data include passing a user/group that should be set when a file is extracted from the phar to disk. Other uses could include explicitly specifying a MIME type to return. However, any useful data that describes a file, but should not be contained inside of it may be stored.
Parametry
-
metadata -
Any PHP variable containing information to store alongside a file
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 A PharFileInfo::setMetadata() example
<?php
// make sure it doesn't exist
@unlink('brandnewphar.phar');
try {
$p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
$p['file.txt'] = 'hello';
$p['file.txt']->setMetadata(array('user' => 'bill', 'mime-type' => 'text/plain'));
var_dump($p['file.txt']->getMetaData());
} catch (Exception $e) {
echo 'Could not create/modify phar: ', $e;
}
?>
Powyższy przykład wyświetli:
array(2) {
["user"]=>
string(4) "bill"
["mime-type"]=>
string(10) "text/plain"
}
Zobacz też:
- PharFileInfo::hasMetadata() - Returns the metadata of the entry
- PharFileInfo::getMetadata() - Returns file-specific meta-data saved with a file
- PharFileInfo::delMetadata() - Deletes the metadata of the entry
- Phar::setMetadata() - Sets phar archive meta-data
- Phar::hasMetadata() - Returns whether phar has global meta-data
- Phar::getMetadata() - Returns phar archive meta-data
PharFileInfo::setUncompressed
(PHP >= 5.3.0, PECL phar >= 1.0.0)
PharFileInfo::setUncompressed — Uncompresses the current Phar entry within the phar, if it is compressed
Opis
Informacja:
Ta metoda została usunięta z rozszerzenia phar w wersji 2.0.0. Dostępne są zastępcze implementacje: PharFileInfo::isCompressed(), PharFileInfo::decompress(), i PharFileInfo::compress().
This method decompresses the file inside the Phar archive. Depending on how the file is compressed, the bzip2 or zlib extensions must be enabled to take advantage of this feature. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Błędy/Wyjątki
Throws BadMethodCallException if the phar.readonly INI variable is on, or if the bzip2/zlib extension is not available.
Przykłady
Przykład #1 A PharFileInfo::setUncompressed() example
<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$file = $p['myfile.txt'];
$file->setCompressedGZ();
var_dump($file->isCompressed());
$p['myfile.txt']->setUncompressed();
var_dump($file->isCompressed());
} catch (Exception $e) {
echo 'Create/modify failed for my.phar: ', $e;
}
?>
Powyższy przykład wyświetli:
bool(true) bool(false)
Zobacz też:
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressedBZIP2() - Returns whether the entry is compressed using bzip2
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::isCompressedGZ() - Returns whether the entry is compressed using gz
- PharFileInfo::setCompressedBZIP2() - Compresses the current Phar entry within the phar using Bzip2 compression
- PharFileInfo::setCompressedGZ() - Compresses the current Phar entry within the phar using gz compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressAllFilesBZIP2() - Compresses all files in the current Phar archive using Bzip2 compression
- Phar::compressAllFilesGZ() - Compresses all files in the current Phar archive using Gzip compression
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::uncompressAllFiles() - Uncompresses all files in the current Phar archive
Spis treści
- PharFileInfo::chmod — Sets file-specific permission bits
- PharFileInfo::compress — Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::__construct — Construct a Phar entry object
- PharFileInfo::decompress — Decompresses the current Phar entry within the phar
- PharFileInfo::delMetadata — Deletes the metadata of the entry
- PharFileInfo::getCRC32 — Returns CRC32 code or throws an exception if CRC has not been verified
- PharFileInfo::getCompressedSize — Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::getMetadata — Returns file-specific meta-data saved with a file
- PharFileInfo::getPharFlags — Returns the Phar file entry flags
- PharFileInfo::hasMetadata — Returns the metadata of the entry
- PharFileInfo::isCRCChecked — Returns whether file entry has had its CRC verified
- PharFileInfo::isCompressed — Returns whether the entry is compressed
- PharFileInfo::isCompressedBZIP2 — Returns whether the entry is compressed using bzip2
- PharFileInfo::isCompressedGZ — Returns whether the entry is compressed using gz
- PharFileInfo::setCompressedBZIP2 — Compresses the current Phar entry within the phar using Bzip2 compression
- PharFileInfo::setCompressedGZ — Compresses the current Phar entry within the phar using gz compression
- PharFileInfo::setMetadata — Sets file-specific meta-data saved with a file
- PharFileInfo::setUncompressed — Uncompresses the current Phar entry within the phar, if it is compressed
The PharException class
(Unknown)
Wstęp
The PharException class provides a phar-specific exception class for try/catch blocks.
Krótki opis klasy
PharException
(Unknown)
PharException — The PharException class provides a phar-specific exception class for try/catch blocks.
Opis
Spis treści
- PharException — The PharException class provides a phar-specific exception class for try/catch blocks.
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Using Phar Archives
- Creating Phar Archives
- What makes a phar a phar and not a tar or a zip?
- Phar — The Phar class
- Phar::addEmptyDir — Add an empty directory to the phar archive
- Phar::addFile — Add a file from the filesystem to the phar archive
- Phar::addFromString — Add a file from the filesystem to the phar archive
- Phar::apiVersion — Returns the api version
- Phar::buildFromDirectory — Construct a phar archive from the files within a directory.
- Phar::buildFromIterator — Construct a phar archive from an iterator.
- Phar::canCompress — Returns whether phar extension supports compression using either zlib or bzip2
- Phar::canWrite — Returns whether phar extension supports writing and creating phars
- Phar::compress — Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::compressAllFilesBZIP2 — Compresses all files in the current Phar archive using Bzip2 compression
- Phar::compressAllFilesGZ — Compresses all files in the current Phar archive using Gzip compression
- Phar::compressFiles — Compresses all files in the current Phar archive
- Phar::__construct — Construct a Phar archive object
- Phar::convertToData — Convert a phar archive to a non-executable tar or zip file
- Phar::convertToExecutable — Convert a phar archive to another executable phar archive file format
- Phar::copy — Copy a file internal to the phar archive to another new file within the phar
- Phar::count — Returns the number of entries (files) in the Phar archive
- Phar::createDefaultStub — Create a phar-file format specific stub
- Phar::decompress — Decompresses the entire Phar archive
- Phar::decompressFiles — Decompresses all files in the current Phar archive
- Phar::delMetadata — Deletes the global metadata of the phar
- Phar::delete — Delete a file within a phar archive
- Phar::extractTo — Extract the contents of a phar archive to a directory
- Phar::getMetadata — Returns phar archive meta-data
- Phar::getModified — Return whether phar was modified
- Phar::getSignature — Return MD5/SHA1/SHA256/SHA512/OpenSSL signature of a Phar archive
- Phar::getStub — Return the PHP loader or bootstrap stub of a Phar archive
- Phar::getSupportedCompression — Return array of supported compression algorithms
- Phar::getSupportedSignatures — Return array of supported signature types
- Phar::getVersion — Return version info of Phar archive
- Phar::hasMetadata — Returns whether phar has global meta-data
- Phar::interceptFileFuncs — instructs phar to intercept fopen, file_get_contents, opendir, and all of the stat-related functions
- Phar::isBuffering — Used to determine whether Phar write operations are being buffered, or are flushing directly to disk
- Phar::isCompressed — Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::isFileFormat — Returns true if the phar archive is based on the tar/phar/zip file format depending on the parameter
- Phar::isValidPharFilename — Returns whether the given filename is a valid phar filename
- Phar::isWritable — Returns true if the phar archive can be modified
- Phar::loadPhar — Loads any phar archive with an alias
- Phar::mapPhar — Reads the currently executed file (a phar) and registers its manifest
- Phar::mount — Mount an external path or file to a virtual location within the phar archive
- Phar::mungServer — Defines a list of up to 4 $_SERVER variables that should be modified for execution
- Phar::offsetExists — determines whether a file exists in the phar
- Phar::offsetGet — Gets a PharFileInfo object for a specific file
- Phar::offsetSet — set the contents of an internal file to those of an external file
- Phar::offsetUnset — remove a file from a phar
- Phar::running — Returns the full path on disk or full phar URL to the currently executing Phar archive
- Phar::setAlias — Set the alias for the Phar archive
- Phar::setDefaultStub — Used to set the PHP loader or bootstrap stub of a Phar archive to the default loader
- Phar::setMetadata — Sets phar archive meta-data
- Phar::setSignatureAlgorithm — set the signature algorithm for a phar and apply it.
- Phar::setStub — Used to set the PHP loader or bootstrap stub of a Phar archive
- Phar::startBuffering — Start buffering Phar write operations, do not modify the Phar object on disk
- Phar::stopBuffering — Stop buffering write requests to the Phar archive, and save changes to disk
- Phar::uncompressAllFiles — Uncompresses all files in the current Phar archive
- Phar::unlinkArchive — Completely remove a phar archive from disk and from memory
- Phar::webPhar — mapPhar for web-based phars. front controller for web applications
- PharData — The PharData class
- PharData::addEmptyDir — Add an empty directory to the tar/zip archive
- PharData::addFile — Add a file from the filesystem to the tar/zip archive
- PharData::addFromString — Add a file from the filesystem to the tar/zip archive
- PharData::buildFromDirectory — Construct a tar/zip archive from the files within a directory.
- PharData::buildFromIterator — Construct a tar or zip archive from an iterator.
- PharData::compress — Compresses the entire tar/zip archive using Gzip or Bzip2 compression
- PharData::compressFiles — Compresses all files in the current tar/zip archive
- PharData::__construct — Construct a non-executable tar or zip archive object
- PharData::convertToData — Convert a phar archive to a non-executable tar or zip file
- PharData::convertToExecutable — Convert a non-executable tar/zip archive to an executable phar archive
- PharData::copy — Copy a file internal to the phar archive to another new file within the phar
- PharData::decompress — Decompresses the entire Phar archive
- PharData::decompressFiles — Decompresses all files in the current zip archive
- PharData::delMetadata — Deletes the global metadata of a zip archive
- PharData::delete — Delete a file within a tar/zip archive
- PharData::extractTo — Extract the contents of a tar/zip archive to a directory
- PharData::isWritable — Returns true if the tar/zip archive can be modified
- PharData::offsetSet — set the contents of a file within the tar/zip to those of an external file or string
- PharData::offsetUnset — remove a file from a tar/zip archive
- PharData::setAlias — dummy function (Phar::setAlias is not valid for PharData)
- PharData::setDefaultStub — dummy function (Phar::setDefaultStub is not valid for PharData)
- Phar::setMetadata — Sets phar archive meta-data
- Phar::setSignatureAlgorithm — set the signature algorithm for a phar and apply it. The
- PharData::setStub — dummy function (Phar::setStub is not valid for PharData)
- PharFileInfo — The PharFileInfo class
- PharFileInfo::chmod — Sets file-specific permission bits
- PharFileInfo::compress — Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::__construct — Construct a Phar entry object
- PharFileInfo::decompress — Decompresses the current Phar entry within the phar
- PharFileInfo::delMetadata — Deletes the metadata of the entry
- PharFileInfo::getCRC32 — Returns CRC32 code or throws an exception if CRC has not been verified
- PharFileInfo::getCompressedSize — Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::getMetadata — Returns file-specific meta-data saved with a file
- PharFileInfo::getPharFlags — Returns the Phar file entry flags
- PharFileInfo::hasMetadata — Returns the metadata of the entry
- PharFileInfo::isCRCChecked — Returns whether file entry has had its CRC verified
- PharFileInfo::isCompressed — Returns whether the entry is compressed
- PharFileInfo::isCompressedBZIP2 — Returns whether the entry is compressed using bzip2
- PharFileInfo::isCompressedGZ — Returns whether the entry is compressed using gz
- PharFileInfo::setCompressedBZIP2 — Compresses the current Phar entry within the phar using Bzip2 compression
- PharFileInfo::setCompressedGZ — Compresses the current Phar entry within the phar using gz compression
- PharFileInfo::setMetadata — Sets file-specific meta-data saved with a file
- PharFileInfo::setUncompressed — Uncompresses the current Phar entry within the phar, if it is compressed
- PharException — The PharException class
- PharException — The PharException class provides a phar-specific exception class for try/catch blocks.
Rar Archiving
Wstęp
Rar is a powerful and effective archiver created by Eugene Roshal. This extension gives you possibility to read Rar archives but doesn't support writing Rar archives, because this is not supported by the UnRar library and is directly prohibited by its license.
More information about Rar and UnRar can be found at » http://www.rarlabs.com/.
Instalacja/Konfiguracja
Spis treści
Wymagania
Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.
Instalacja
Rar is currently available through PECL » http://pecl.php.net/package/rar.
Also you can use the PECL installer to install the Rar extension, using the following command: pecl -v install rar.
You can always download the tar.gz package and install Rar by hand:
Przykład #1 Rar installation
gunzip rar-xxx.tgz tar -xvf rar-xxx.tar cd rar-xxx phpize ./configure && make && make install
Windows users will enable php_rar.dll inside of php.ini in order to use these functions. DLL z tym rozszerzeniem PECL można pobrać zarówno ze strony » PHP Downloads lub z » http://pecl4win.php.net/
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
This extension registers three internal classes: The archive representations returned by rar_open() – RarArchive –, the entry representations returned by rar_list() and rar_entry_get() – RarEntry and the exception type RarException.
This extension also register a stream resource, called "rar" and a URL wrapper called "rar wrapper" and registered under the prefix "rar".
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
-
RAR_HOST_MSDOS(integer) -
Use
RarEntry::HOST_MSDOSinstead. -
RAR_HOST_OS2(integer) -
Use
RarEntry::HOST_OS2instead. -
RAR_HOST_WIN32(integer) -
Use
RarEntry::HOST_WIN32instead. -
RAR_HOST_UNIX(integer) -
Use
RarEntry::HOST_UNIXinstead. -
RAR_HOST_BEOS(integer) -
Use
RarEntry::HOST_BEOSinstead.
Przykłady
See also the examples under rar:// wrapper.
Przykład #1 On-the-fly decompression
<?php
if (!array_key_exists("i", $_GET) || !is_numeric($_GET["i"]))
die("Index unspecified or non-numeric");
$index = (int) $_GET["i"];
$arch = RarArchive::open("example.rar");
if ($arch === FALSE)
die("Cannot open example.rar");
$entries = $arch->getEntries();
if ($entries === FALSE)
die("Cannot retrieve entries");
if (!array_key_exists($index, $entries))
die("No such index: $index");
$orfilename = $entries[$index]->getName(); //UTF-8 encoded
$filesize = $entries[$index]->getUnpackedSize();
/* you could check HTTP_IF_MODIFIED_SINCE here and compare with
* $entries[$index]->getFileTime(). You could also send a
* "Last modified" header */
$fp = $entries[$index]->getStream();
if ($fp === FALSE)
die("Cannot open file with index $index insided the archive.");
$arch->close(); //no longer needed; stream is independent
function detectUserAgent() {
if (!array_key_exists('HTTP_USER_AGENT', $_SERVER))
return "Other";
$uas = $_SERVER['HTTP_USER_AGENT'];
if (preg_match("@Opera/@", $uas))
return "Opera";
if (preg_match("@Firefox/@", $uas))
return "Firefox";
if (preg_match("@Chrome/@", $uas))
return "Chrome";
if (preg_match("@MSIE ([0-9.]+);@", $uas, $matches)) {
if (((float)$matches[1]) >= 7.0)
return "IE";
}
return "Other";
}
/*
* We have 3 options:
* - For FF and Opera, which support RFC 2231, use that format.
* - For IE and Chrome, use attwithfnrawpctenclong
* (http://greenbytes.de/tech/tc2231/#attwithfnrawpctenclong)
* - For the others, convert to ISO-8859-1, if possible
*/
$formatRFC2231 = 'Content-Disposition: attachment; filename*=UTF-8\'\'%s';
$formatDef = 'Content-Disposition: attachment; filename="%s"';
switch (detectUserAgent()) {
case "Opera":
case "Firefox":
$orfilename = rawurlencode($orfilename);
$format = $formatRFC2231;
break;
case "IE":
case "Chrome":
$orfilename = rawurlencode($orfilename);
$format = $formatDef;
break;
default:
if (function_exists('iconv'))
$orfilename =
@iconv("UTF-8", "ISO-8859-1//TRANSLIT", $orfilename);
$format = $formatDef;
}
header(sprintf($format, $orfilename));
//cannot send error messages from now on (headers already sent)
//replace by real content type, perhaps infering from the file extension
$contentType = "application/octet-stream";
header("Content-Type: $contentType");
header("Content-Transfer-Encoding: binary");
header("Content-Length: $filesize");
if ($_SERVER['REQUEST_METHOD'] == "HEAD")
die();
while (!feof($fp)) {
$s = @fread($fp, 8192);
if ($s === false)
break; //useless to send error messages
echo $s;
}
?>
This example opens a RAR file and presents the requested file inside the RAR archive for download to the client.
Przykład #2 RAR extension filesystem extraction example
<?php
$rar_file = rar_open('example.rar') or die("Can't open Rar archive");
$entries = rar_list($rar_file);
foreach ($entries as $entry) {
echo 'Filename: ' . $entry->getName() . "\n";
echo 'Packed size: ' . $entry->getPackedSize() . "\n";
echo 'Unpacked size: ' . $entry->getUnpackedSize() . "\n";
$entry->extract('/dir/extract/to/');
}
rar_close($rar_file);
?>
This example opens a RAR file archive and extracts each entry to the specified directory.
Rar Funkcje
rar_wrapper_cache_stats
(PECL rar >= 3.0.0)
rar_wrapper_cache_stats — Cache hits and misses for the URL wrapper
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Spis treści
- rar_wrapper_cache_stats — Cache hits and misses for the URL wrapper
The RarArchive class
(No version information available, might only be in SVN)
Wstęp
This class represents a RAR archive, which may be formed by several volumes (parts) and which contains a number of RAR entries (i.e., files, directories and other special objects such as symbolic links).
Objects of this class can be traversed, yielding the entries stored in the respective RAR archive. Those entries can also be obtained through RarArchive::getEntry() and RarArchive::getEntries().
Krótki opis klasy
$filename
[, string $password = NULL
[, callable $volume_callback = NULL
]] )RarArchive::close
rar_close
(PECL rar >= 2.0.0)
RarArchive::close -- rar_close — Close RAR archive and free all resources
Opis
Styl obiektowy (method):
Styl proceduralny:
Close RAR archive and free all allocated resources.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 2.0.0 | The RAR entries returned by RarArchive::getEntry() and RarArchive::getEntries() are now invalidated when calling this method. This means that all instance methods called for such entries and not guaranteed to succeed. |
Przykłady
Przykład #1 Styl obiektowy
<?php
$rar_arch = RarArchive::open('latest_winrar.rar');
echo $rar_arch."\n";
$rar_arch->close();
echo $rar_arch."\n";
?>
Powyższy przykład wyświetli coś podobnego do:
RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" (closed)
Przykład #2 Styl proceduralny
<?php
$rar_arch = rar_open('latest_winrar.rar');
echo $rar_arch."\n";
rar_close($rar_arch);
echo $rar_arch."\n";
?>
RarArchive::getComment
rar_comment_get
(PECL rar >= 2.0.0)
RarArchive::getComment -- rar_comment_get — Get comment text from the RAR archive
Opis
Styl obiektowy (method):
Styl proceduralny:
Get the (global) comment stored in the RAR archive. It may be up to 64 KiB long.
Informacja:
This extension does not support comments at the entry level.
Zwracane wartości
Returns the comment or NULL if there is none.
Informacja:
RAR has currently no support for unicode comments. The encoding of the result of this function is not specified, but it will probably be Windows-1252.
Przykłady
Przykład #1 Styl obiektowy
<?php
$rar_arch = RarArchive::open('commented.rar');
echo $rar_arch->getComment();
?>
Powyższy przykład wyświetli coś podobnego do:
This is the comment of the file commented.rar.
Przykład #2 Styl proceduralny
<?php
$rar_arch = rar_open('commented.rar');
echo rar_comment_get($rar_arch);
?>
RarArchive::getEntries
rar_list
(PECL rar >= 2.0.0)
RarArchive::getEntries -- rar_list — Get full list of entries from the RAR archive
Opis
Styl obiektowy (method):
Styl proceduralny:
Get entries list (files and directories) from the RAR archive.
Informacja:
If the archive has entries with the same name, this method, together with RarArchive foreach iteration and array-like access with numeric indexes, are the only ones to access all the entries (i.e., RarArchive::getEntry() and the rar:// wrapper are insufficient).
Zwracane wartości
rar_list() returns array of RarEntry objects
lub FALSE w przypadku niepowodzenia.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 3.0.0 | Support for RAR archives with repeated entry names is no longer defective. |
Przykłady
Przykład #1 Styl obiektowy
<?php
$rar_arch = RarArchive::open('solid.rar');
if ($rar_arch === FALSE)
die("Could not open RAR archive.");
$rar_entries = $rar_arch->getEntries();
if ($rar_entries === FALSE)
die("Could retrieve entries.");
echo "Found " . count($rar_entries) . " entries.\n";
foreach ($rar_entries as $e) {
echo $e;
echo "\n";
}
$rar_arch->close();
?>
Powyższy przykład wyświetli coś podobnego do:
Found 2 entries. RarEntry for file "tese.txt" (23b93a7a) RarEntry for file "unrardll.txt" (2ed64b6e)
Przykład #2 Styl proceduralny
<?php
$rar_arch = rar_open('solid.rar');
if ($rar_arch === FALSE)
die("Could not open RAR archive.");
$rar_entries = rar_list($rar_arch);
if ($rar_entries === FALSE)
die("Could retrieve entries.");
echo "Found " . count($rar_entries) . " entries.\n";
foreach ($rar_entries as $e) {
echo $e;
echo "\n";
}
rar_close($rar_arch);
?>
RarArchive::getEntry
rar_entry_get
(PECL rar >= 2.0.0)
RarArchive::getEntry -- rar_entry_get — Get entry object from the RAR archive
Opis
Styl obiektowy (method):
Styl proceduralny:
Get entry object (file or directory) from the RAR archive.
Informacja:
You can also get entry objects using RarArchive::getEntries().
Note that a RAR archive can have multiple entries with the same name; this method will retrieve only the first.
Parametry
-
rarfile -
A RarArchive object, opened with rar_open().
-
entryname -
Path to the entry within the RAR archive.
Informacja:
The path must be the same returned by RarEntry::getName().
Zwracane wartości
Returns the matching RarEntry object lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 Styl obiektowy
<?php
$rar_arch = RarArchive::open('solid.rar');
if ($rar_arch === FALSE)
die("Could not open RAR archive.");
$rar_entry = $rar_arch->getEntry('tese.txt');
if ($rar_entry === FALSE)
die("Could get such entry");
echo get_class($rar_entry)."\n";
echo $rar_entry;
$rar_arch->close();
?>
Powyższy przykład wyświetli coś podobnego do:
RarEntry RarEntry for file "tese.txt" (23b93a7a)
Przykład #2 Styl proceduralny
<?php
$rar_arch = rar_open('solid.rar');
if ($rar_arch === FALSE)
die("Could not open RAR archive.");
$rar_entry = rar_entry_get($rar_arch, 'tese.txt');
if ($rar_entry === FALSE)
die("Could get such entry");
echo get_class($rar_entry)."\n";
echo $rar_entry;
rar_close($rar_arch);
?>
RarArchive::isBroken
rar_broken_is
(PECL rar >= 3.0.0)
RarArchive::isBroken -- rar_broken_is — Test whether an archive is broken (incomplete)
Opis
Styl obiektowy (method):
Styl proceduralny:
This function determines whether an archive is incomplete, i.e., if a volume is missing or a volume is truncated.
Zwracane wartości
Returns TRUE if the archive is broken, FALSE otherwise. This function may also
return FALSE if the passed file has already been closed. The only way
to tell the two cases apart is to enable
exceptions with RarException::setUsingExceptions(); however,
this should be unnecessary as a program should not operate on closed files.
Przykłady
Przykład #1 Styl obiektowy
<?php
function retnull() { return null; }
$file = dirname(__FILE__) . "/multi_broken.part1.rar";
/* Third argument is used to omit notice */
$arch = RarArchive::open($file, null, 'retnull');
var_dump($arch->isBroken());
?>
Powyższy przykład wyświetli coś podobnego do:
bool(true)
Przykład #2 Styl proceduralny
<?php
function retnull() { return null; }
$file = dirname(__FILE__) . "/multi_broken.part1.rar";
/* Third argument is used to omit notice */
$arch = rar_open($file, null, 'retnull');
var_dump(rar_broken_is($arch));
?>
RarArchive::isSolid
rar_solid_is
(PECL rar >= 2.0.0)
RarArchive::isSolid -- rar_solid_is — Check whether the RAR archive is solid
Opis
Styl obiektowy (method):
Styl proceduralny:
Check whether the RAR archive is solid. Individual file extraction is slower on solid archives.
Zwracane wartości
Returns TRUE if the archive is solid, FALSE otherwise.
Przykłady
Przykład #1 Styl obiektowy
<?php
$arch1 = RarArchive::open("store_method.rar");
$arch2 = RarArchive::open("solid.rar");
echo "$arch1: " . ($arch1->isSolid()?'yes':'no') ."\n";
echo "$arch2: " . ($arch2->isSolid()?'yes':'no') . "\n";
?>
Powyższy przykład wyświetli coś podobnego do:
RAR Archive "C:\php_rar\trunk\tests\store_method.rar": no RAR Archive "C:\php_rar\trunk\tests\solid.rar": yes
Przykład #2 Styl proceduralny
<?php
$arch1 = rar_open("store_method.rar");
$arch2 = rar_open("solid.rar");
echo "$arch1: " . (rar_solid_is($arch1)?'yes':'no') ."\n";
echo "$arch2: " . (rar_solid_is($arch2)?'yes':'no') . "\n";
?>
RarArchive::open
rar_open
(PECL rar >= 2.0.0)
RarArchive::open -- rar_open — Open RAR archive
Opis
Styl obiektowy (method):
$filename
[, string $password = NULL
[, callable $volume_callback = NULL
]] )Styl proceduralny:
$filename
[, string $password = NULL
[, callable $volume_callback = NULL
]] )Open specified RAR archive and return RarArchive instance representing it.
Informacja:
If opening a multi-volume archive, the path of the first volume should be passed as the first parameter. Otherwise, not all files will be shown. This is by design.
Parametry
-
filename -
Path to the Rar archive.
-
password -
A plain password, if needed to decrypt the headers. It will also be used by default if encrypted files are found. Note that the files may have different passwords in respect to the headers and among them.
-
volume_callback -
A function that receives one parameter – the path of the volume that was not found – and returns a string with the correct path for such volume or
NULLif such volume does not exist or is not known. The programmer should ensure the passed function doesn't cause loops as this function is called repeatedly if the path returned in a previous call did not correspond to the needed volume. Specifying this parameter omits the notice that would otherwise be emitted whenever a volume is not found; an implementation that only returnsNULLcan therefore be used to merely omit such notices.
Prior to version 2.0.0, this function would not handle relative paths correctly. Use realpath() as a workaround.
Zwracane wartości
Returns the requested RarArchive instance lub FALSE w przypadku niepowodzenia.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 3.0.0 |
volume_callback was added.
|
Przykłady
Przykład #1 Styl obiektowy
<?php
$rar_arch = RarArchive::open('encrypted_headers.rar', 'samplepassword');
if ($rar_arch === FALSE)
die("Failed opening file");
$entries = $rar_arch->getEntries();
if ($entries === FALSE)
die("Failed fetching entries");
echo "Found " . count($entries) . " files.\n";
if (empty($entries))
die("No valid entries found.");
$stream = reset($entries)->getStream();
if ($stream === FALSE)
die("Failed opening first file");
$rar_arch->close();
echo "Content of first one follows:\n";
echo stream_get_contents($stream);
fclose($stream);
?>
Powyższy przykład wyświetli coś podobnego do:
Found 2 files. Content of first one follows: Encrypted file 1 contents.
Przykład #2 Styl proceduralny
<?php
$rar_arch = rar_open('encrypted_headers.rar', 'samplepassword');
if ($rar_arch === FALSE)
die("Failed opening file");
$entries = rar_list($rar_arch);
if ($entries === FALSE)
die("Failed fetching entries");
echo "Found " . count($entries) . " files.\n";
if (empty($entries))
die("No valid entries found.");
$stream = reset($entries)->getStream();
if ($stream === FALSE)
die("Failed opening first file");
rar_close($rar_arch);
echo "Content of first one follows:\n";
echo stream_get_contents($stream);
fclose($stream);
?>
Przykład #3 Volume Callback
<?php
/* In this example, there's a volume named multi_broken.part1.rar
* whose next volume is named multi.part2.rar */
function resolve($vol) {
if (preg_match('/_broken/', $vol))
return str_replace('_broken', '', $vol);
else
return null;
}
$rar_file1 = rar_open(dirname(__FILE__).'/multi_broken.part1.rar', null, 'resolve');
$entry = $rar_file1->getEntry('file2.txt');
$entry->extract(null, dirname(__FILE__) . "/temp_file2.txt");
?>
RarArchive::setAllowBroken
(PECL rar >= 3.0.0)
RarArchive::setAllowBroken — Whether opening broken archives is allowed
Opis
Styl obiektowy (method):
$allow_broken
)Styl proceduralny:
This method defines whether broken archives can be read or all the operations that attempt to extract the archive entries will fail. Broken archives are archives for which no error is detected when the file is opened but an error occurs when reading the entries.
Parametry
-
rarfile -
A RarArchive object, opened with rar_open().
-
allow_broken -
Whether to allow reading broken files (
TRUE) or not (FALSE).
Zwracane wartości
Returns TRUE lub FALSE w przypadku niepowodzenia. It will only fail if the file has
already been closed.
Przykłady
Przykład #1 Styl obiektowy
<?php
function retnull() { return null; }
$file = dirname(__FILE__) . "/multi_broken.part1.rar";
/* Third argument omits "volume not found" message */
$a = RarArchive::open($file, null, 'retnull');
$a->setAllowBroken(true);
foreach ($a->getEntries() as $e) {
echo "$e\n";
}
var_dump(count($a));
?>
Powyższy przykład wyświetli coś podobnego do:
RarEntry for file "file1.txt" (52b28202) int(1)
Przykład #2 Styl proceduralny
<?php
function retnull() { return null; }
$file = dirname(__FILE__) . "/multi_broken.part1.rar";
/* Third argument omits "volume not found" message */
$a = rar_open($file, null, 'retnull');
rar_allow_broken_set($a, true);
foreach (rar_list($a) as $e) {
echo "$e\n";
}
var_dump(count($a));
?>
RarArchive::__toString
(PECL rar >= 2.0.0)
RarArchive::__toString — Get text representation
Opis
Provides a string representation for this RarArchive object. It currently shows the full path name of the archive volume that was opened and whether the resource is valid or was already closed through a call to RarArchive::close().
This method may be used only for debugging purposes, as there are no guarantees as to which information the result contains or how it is formatted.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
A textual representation of this RarArchive object. The content of this representation is unspecified.
Przykłady
Przykład #1 RarArchive::__toString() example
<?php
$rar_arch = RarArchive::open('latest_winrar.rar');
echo $rar_arch."\n";
$rar_arch->close();
echo $rar_arch."\n";
?>
Powyższy przykład wyświetli coś podobnego do:
RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" (closed)
Spis treści
- RarArchive::close — Close RAR archive and free all resources
- RarArchive::getComment — Get comment text from the RAR archive
- RarArchive::getEntries — Get full list of entries from the RAR archive
- RarArchive::getEntry — Get entry object from the RAR archive
- RarArchive::isBroken — Test whether an archive is broken (incomplete)
- RarArchive::isSolid — Check whether the RAR archive is solid
- RarArchive::open — Open RAR archive
- RarArchive::setAllowBroken — Whether opening broken archives is allowed
- RarArchive::__toString — Get text representation
The RarEntry class
(No version information available, might only be in SVN)
Wstęp
A RAR entry, representing a directory or a compressed file inside a RAR archive.
Krótki opis klasy
$dir
[, string $filepath = ''
[, string $password = NULL
[, bool $extended_data = false
]]] )Stałe predefiniowane
-
RarEntry::HOST_MSDOS -
If the return value of RarEntry::getHostOs() equals this constant, MS-DOS was used to add this entry. Use instead of
RAR_HOST_MSDOS. -
RarEntry::HOST_OS2 -
If the return value of RarEntry::getHostOs() equals this constant, OS/2 was used to add this entry. Intended to replace
RAR_HOST_OS2. -
RarEntry::HOST_WIN32 -
If the return value of RarEntry::getHostOs() equals this constant, Microsoft Windows was used to add this entry. Intended to replace
RAR_HOST_WIN32. -
RarEntry::HOST_UNIX -
If the return value of RarEntry::getHostOs() equals this constant, an unspecified UNIX OS was used to add this entry. Intended to replace
RAR_HOST_UNIX. -
RarEntry::HOST_MACOS -
If the return value of RarEntry::getHostOs() equals this constant, Mac OS was used to add this entry.
-
RarEntry::HOST_BEOS -
If the return value of RarEntry::getHostOs() equals this constant, BeOS was used to add this entry. Intended to replace
RAR_HOST_BEOS. -
RarEntry::ATTRIBUTE_WIN_READONLY -
Bit that represents a Windows entry with a read-only attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
-
Bit that represents a Windows entry with a hidden attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
-
RarEntry::ATTRIBUTE_WIN_SYSTEM -
Bit that represents a Windows entry with a system attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
-
RarEntry::ATTRIBUTE_WIN_DIRECTORY -
Bit that represents a Windows entry with a directory attribute (entry is a directory). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows. See also RarEntry::isDirectory(), which also works with entries that were not added in WinRAR.
-
RarEntry::ATTRIBUTE_WIN_ARCHIVE -
Bit that represents a Windows entry with an archive attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
-
RarEntry::ATTRIBUTE_WIN_DEVICE -
Bit that represents a Windows entry with a device attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
-
RarEntry::ATTRIBUTE_WIN_NORMAL -
Bit that represents a Windows entry with a normal file attribute (entry is NOT a directory). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows. See also RarEntry::isDirectory(), which also works with entries that were not added in WinRAR.
-
RarEntry::ATTRIBUTE_WIN_TEMPORARY -
Bit that represents a Windows entry with a temporary attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
-
RarEntry::ATTRIBUTE_WIN_SPARSE_FILE -
Bit that represents a Windows entry with a sparse file attribute (file is an NTFS sparse file). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
-
RarEntry::ATTRIBUTE_WIN_REPARSE_POINT -
Bit that represents a Windows entry with a reparse point attribute (entry is an NTFS reparse point, e.g. a directory junction or a mount file system). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
-
RarEntry::ATTRIBUTE_WIN_COMPRESSED -
Bit that represents a Windows entry with a compressed attribute (NTFS only). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
-
RarEntry::ATTRIBUTE_WIN_OFFLINE -
Bit that represents a Windows entry with an offline attribute (entry is offline and not accessible). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
-
RarEntry::ATTRIBUTE_WIN_NOT_CONTENT_INDEXED -
Bit that represents a Windows entry with a not content indexed attribute (entry is to be indexed). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
-
RarEntry::ATTRIBUTE_WIN_ENCRYPTED -
Bit that represents a Windows entry with an encrypted attribute (NTFS only). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
-
RarEntry::ATTRIBUTE_WIN_VIRTUAL -
Bit that represents a Windows entry with a virtual attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
-
RarEntry::ATTRIBUTE_UNIX_WORLD_EXECUTE -
Bit that represents a UNIX entry that is world executable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
-
RarEntry::ATTRIBUTE_UNIX_WORLD_WRITE -
Bit that represents a UNIX entry that is world writable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
-
RarEntry::ATTRIBUTE_UNIX_WORLD_READ -
Bit that represents a UNIX entry that is world readable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
-
RarEntry::ATTRIBUTE_UNIX_GROUP_EXECUTE -
Bit that represents a UNIX entry that is group executable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
-
RarEntry::ATTRIBUTE_UNIX_GROUP_WRITE -
Bit that represents a UNIX entry that is group writable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
-
RarEntry::ATTRIBUTE_UNIX_GROUP_READ -
Bit that represents a UNIX entry that is group readable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
-
RarEntry::ATTRIBUTE_UNIX_OWNER_EXECUTE -
Bit that represents a UNIX entry that is owner executable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
-
RarEntry::ATTRIBUTE_UNIX_OWNER_WRITE -
Bit that represents a UNIX entry that is owner writable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
-
RarEntry::ATTRIBUTE_UNIX_OWNER_READ -
Bit that represents a UNIX entry that is owner readable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
-
RarEntry::ATTRIBUTE_UNIX_STICKY -
Bit that represents the UNIX sticky bit. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
-
RarEntry::ATTRIBUTE_UNIX_SETGID -
Bit that represents the UNIX setgid attribute. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
-
RarEntry::ATTRIBUTE_UNIX_SETUID -
Bit that represents the UNIX setuid attribute. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
-
RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET -
Mask to isolate the last four bits (nibble) of UNIX attributes (_S_IFMT, the type of file mask). To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constants
RarEntry::ATTRIBUTE_UNIX_FIFO,RarEntry::ATTRIBUTE_UNIX_CHAR_DEV,RarEntry::ATTRIBUTE_UNIX_DIRECTORY,RarEntry::ATTRIBUTE_UNIX_BLOCK_DEV,RarEntry::ATTRIBUTE_UNIX_REGULAR_FILE,RarEntry::ATTRIBUTE_UNIX_SYM_LINKandRarEntry::ATTRIBUTE_UNIX_SOCKET. -
RarEntry::ATTRIBUTE_UNIX_FIFO -
Unix FIFOs will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant
RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET. -
RarEntry::ATTRIBUTE_UNIX_CHAR_DEV -
Unix character devices will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant
RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET. -
RarEntry::ATTRIBUTE_UNIX_DIRECTORY -
Unix directories will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant
RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET. See also RarEntry::isDirectory(), which also works with entries that were added in other operating systems. -
RarEntry::ATTRIBUTE_UNIX_BLOCK_DEV -
Unix block devices will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant
RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET. -
RarEntry::ATTRIBUTE_UNIX_REGULAR_FILE -
Unix regular files (not directories) will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant
RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET. See also RarEntry::isDirectory(), which also works with entries that were added in other operating systems. -
RarEntry::ATTRIBUTE_UNIX_SYM_LINK -
Unix symbolic links will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant
RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET. -
RarEntry::ATTRIBUTE_UNIX_SOCKET -
Unix sockets will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant
RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.
RarEntry::extract
(PECL rar >= 0.1)
RarEntry::extract — Extract entry from the archive
Opis
$dir
[, string $filepath = ''
[, string $password = NULL
[, bool $extended_data = false
]]] )
RarEntry::extract() extracts the entry's data.
It will create new file in the specified
dir with the name identical to the entry's name,
unless the second argument is specified. See below for more information.
Parametry
-
dir -
Path to the directory where files should be extracted. This parameter is considered if and only if
filepathis not. If both parameters are empty an extraction to the current directory will be attempted. -
filepath -
Path (relative or absolute) containing the directory and filename of the extracted file. This parameter overrides both the parameter
dirand the original file name. -
password -
The password used to encrypt this entry. If the entry is not encrypted, this value will not be used and can be omitted. If this parameter is omitted and the entry is encrypted, the password given to rar_open(), if any, will be used. If a wrong password is given, either explicitly or implicitly via rar_open(), CRC checking will fail and this method will fail and return
FALSE. If no password is given and one is required, this method will fail and returnFALSE. You can check whether an entry is encrypted with RarEntry::isEncrypted(). -
extended_data -
If
TRUE, extended information such as NTFS ACLs and Unix owner information will be set in the extract files, as long as it's present in the archive.
Prior to version 2.0.0, this function would not handle relative paths correctly. Use realpath() as a workaround.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 3.0.0 |
extended_data was added.
|
| 3.0.0 | Support for RAR archives with repeated entry names is no longer defective. |
Przykłady
Przykład #1 RarEntry::extract() example
<?php
$rar_file = rar_open('example.rar') or die("Failed to open Rar archive");
$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");
$entry->extract('/dir/to'); // create /dir/to/Dir/file.txt
$entry->extract(false, '/dir/to/new_name.txt'); // create /dir/to/new_name.txt
?>
Przykład #2 How to extract all files in archive:
<?php
/* example by Erik Jenssen aka erix */
$filename = "foobar.rar";
$filepath = "/home/foo/bar/";
$rar_file = rar_open($filepath.$filename);
$list = rar_list($rar_file);
foreach($list as $file) {
$entry = rar_entry_get($rar_file, $file);
$entry->extract("."); // extract to the current dir
}
rar_close($rar_file);
?>
RarEntry::getAttr
(PECL rar >= 0.1)
RarEntry::getAttr — Get attributes of the entry
Opis
Returns the OS-dependent attributes of the archive entry.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the attributes or FALSE on error.
Przykłady
Przykład #1 RarEntry::getAttr() example
<?php
$rar_file = rar_open('example.rar') or die("Can't open Rar archive");
$entry = rar_entry_get($rar_file, 'dir/in/the/archive') or die("Can't find such entry");
$host_os = $entry->getHostOs();
$attr = $entry->getAttr();
switch($host_os) {
case RAR_HOST_MSDOS:
case RAR_HOST_OS2:
case RAR_HOST_WIN32:
case RAR_HOST_MACOS:
printf("%c%c%c%c%c%c\n",
($attr & 0x08) ? 'V' : '.',
($attr & 0x10) ? 'D' : '.',
($attr & 0x01) ? 'R' : '.',
($attr & 0x02) ? 'H' : '.',
($attr & 0x04) ? 'S' : '.',
($attr & 0x20) ? 'A' : '.');
break;
case RAR_HOST_UNIX:
case RAR_HOST_BEOS:
switch ($attr & 0xF000)
{
case 0x4000:
printf("d");
break;
case 0xA000:
printf("l");
break;
default:
printf("-");
break;
}
printf("%c%c%c%c%c%c%c%c%c\n",
($attr & 0x0100) ? 'r' : '-',
($attr & 0x0080) ? 'w' : '-',
($attr & 0x0040) ? (($attr & 0x0800) ? 's':'x'):(($attr & 0x0800) ? 'S':'-'),
($attr & 0x0020) ? 'r' : '-',
($attr & 0x0010) ? 'w' : '-',
($attr & 0x0008) ? (($attr & 0x0400) ? 's':'x'):(($attr & 0x0400) ? 'S':'-'),
($attr & 0x0004) ? 'r' : '-',
($attr & 0x0002) ? 'w' : '-',
($attr & 0x0001) ? 'x' : '-');
break;
}
rar_close($rar_file);
?>
RarEntry::getCrc
(PECL rar >= 0.1)
RarEntry::getCrc — Get CRC of the entry
Opis
Returns an hexadecimal string representation of the CRC of the archive entry.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the CRC of the archive entry or FALSE on error.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 2.0.0 | This method now returns correct values for multiple volume archives. |
RarEntry::getFileTime
(PECL rar >= 0.1)
RarEntry::getFileTime — Get entry last modification time
Opis
Gets entry last modification time.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns entry last modification time as string in format
YYYY-MM-DD HH:II:SS, or FALSE on error.
RarEntry::getHostOs
(PECL rar >= 0.1)
RarEntry::getHostOs — Get entry host OS
Opis
Returns the code of the host OS of the archive entry.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the code of the host OS, or FALSE on error.
Przykłady
Przykład #1 RarEntry::getHostOs() example (version >= 2.0.0)
<?php
$rar_file = rar_open('example.rar') or die("Failed to open Rar archive");
$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");
switch ($entry->getHostOs()) {
case RarEntry::HOST_MSDOS:
echo "MS-DOS\n";
break;
case RarEntry::HOST_OS2:
echo "OS2\n";
break;
case RarEntry::HOST_WIN32:
echo "Win32\n";
break;
case RarEntry::HOST_MACOS:
echo "MacOS\n";
break;
case RarEntry::HOST_UNIX:
echo "Unix/Linux\n";
break;
case RarEntry::HOST_BEOS:
echo "BeOS\n";
break;
}
?>
Przykład #2 RarEntry::getHostOs() example (version <= 1.0.0)
<?php
$rar_file = rar_open('example.rar') or die("Failed to open Rar archive");
$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");
switch ($entry->getHostOs()) {
case RAR_HOST_MSDOS:
echo "MS-DOS\n";
break;
case RAR_HOST_OS2:
echo "OS2\n";
break;
case RAR_HOST_WIN32:
echo "Win32\n";
break;
case RAR_HOST_MACOS:
echo "MacOS\n";
break;
case RAR_HOST_UNIX:
echo "Unix/Linux\n";
break;
case RAR_HOST_BEOS:
echo "BeOS\n";
break;
}
?>
RarEntry::getMethod
(PECL rar >= 0.1)
RarEntry::getMethod — Get pack method of the entry
Opis
RarEntry::getMethod() returns number of the method used when adding current archive entry.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the method number or FALSE on error.
Przykłady
Przykład #1 RarEntry::getMethod() example
<?php
$rar_file = rar_open('example.rar') or die("Failed to open Rar archive");
$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");
echo "Method number: " . $entry->getMethod();
?>
RarEntry::getName
(PECL rar >= 0.1)
RarEntry::getName — Get name of the entry
Opis
Returns the name (with path) of the archive entry.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the entry name as a string, or FALSE on error.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 2.0.0 | As of version 2.0.0, the returned string is encoded in Unicode/UTF-8. |
Przykłady
Przykład #1 RarEntry::getName() example
<?php
//this example is safe even in pages not encoded in UTF-8
//for those encoded in UTF-8, the call to mb_convert_encoding is unnecessary
$rar_file = rar_open('example.rar') or die("Failed to open Rar archive");
$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");
echo "Entry name: " . mb_convert_encoding(
htmlentities(
$entry->getName(),
ENT_COMPAT,
"UTF-8"
),
"HTML-ENTITIES",
"UTF-8"
);
?>
RarEntry::getPackedSize
(PECL rar >= 0.1)
RarEntry::getPackedSize — Get packed size of the entry
Opis
Get packed size of the archive entry.
Informacja:
Note that on platforms with 32-bit longs (that includes Windows x64), the maximum size returned is capped at 2 GiB. Check the constant
PHP_INT_MAX.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the packed size, or FALSE on error.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 2.0.0 | This method now returns correct values of packed sizes bigger than 2 GiB on platforms with 64-bit integers and never returns negative values on other platforms. |
Przykłady
Przykład #1 RarEntry::getPackedSize() example
<?php
$rar_file = rar_open('example.rar') or die("Failed to open Rar archive");
$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");
echo "Packed size of " . $entry->getName() . " = " . $entry->getPackedSize() . " bytes";
?>
RarEntry::getStream
(PECL rar >= 2.0.0)
RarEntry::getStream — Get file handler for entry
Opis
$password
] )Returns a file handler that supports read operations. This handler provides on-the-fly decompression for this entry.
The handler is not invalidated by calling rar_close().
The resulting stream has no integrity verification. In particular, file corruption and decryption with a wrong a key will not be detected. It is the programmer's responsability to use the entry's CRC to check for integrity, if he so wishes.
Parametry
-
password -
The password used to encrypt this entry. If the entry is not encrypted, this value will not be used and can be omitted. If this parameter is omitted and the entry is encrypted, the password given to rar_open(), if any, will be used. If a wrong password is given, either explicitly or implicitly via rar_open(), this method's resulting stream will produce wrong output. If no password is given and one is required, this method will fail and return
FALSE. You can check whether an entry is encrypted with RarEntry::isEncrypted().
Zwracane wartości
The file handler lub FALSE w przypadku niepowodzenia.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 3.0.0 | Support for RAR archives with repeated entry names is no longer defective. |
Przykłady
Przykład #1 RarEntry::getStream() example
<?php
$rar_file = rar_open('example.rar');
if ($rar_file === false)
die("Failed to open Rar archive");
$entry = rar_entry_get($rar_file, 'Dir/file.txt');
if ($entry === false)
die("Failed to find such entry");
$stream = $entry->getStream();
if ($stream === false)
die("Failed to obtain stream.");
rar_close($rar_file); //stream is independent from file
while (!feof($stream)) {
$buff = fread($stream, 8192);
if ($buff !== false)
echo $buff;
else
break; //fread error
}
fclose($stream);
?>
RarEntry::getUnpackedSize
(PECL rar >= 0.1)
RarEntry::getUnpackedSize — Get unpacked size of the entry
Opis
Get unpacked size of the archive entry.
Informacja:
Note that on platforms with 32-bit longs (that includes Windows x64), the maximum size returned is capped at 2 GiB. Check the constant
PHP_INT_MAX.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the unpacked size, or FALSE on error.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 2.0.0 | This method now returns correct values of unpacked sizes bigger than 2 GiB on platforms with 64-bit integers and never returns negative values on other platforms. |
Zwracane wartości
Przykład #1 RarEntry::getUnpackedSize() example
<?php
$rar_file = rar_open('example.rar') or die("Failed to open Rar archive");
$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");
echo "Unpacked size of " . $entry->getName() . " = " . $entry->getPackedSize() . " bytes";
?>
RarEntry::getVersion
(PECL rar >= 0.1)
RarEntry::getVersion — Get minimum version of RAR program required to unpack the entry
Opis
Returns minimum version of RAR program (e.g. WinRAR) required to unpack the entry. It is encoded as 10 * major version + minor version.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the version or FALSE on error.
Przykłady
Przykład #1 RarEntry::getVersion() example
<?php
$rar_file = rar_open('example.rar') or die("Failed to open Rar archive");
$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");
echo "Rar version required for unpacking: " . $entry->getVersion();
?>
RarEntry::isDirectory
(PECL rar >= 2.0.0)
RarEntry::isDirectory — Test whether an entry represents a directory
Opis
Tests whether the current entry is a directory.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns TRUE if this entry is a directory and FALSE otherwise.
Notatki
This function is only available starting with version 2.0.0, but one can also test whether an entry is a directory by checking the entry attributes, like this (only works for files compressed in RAR for Windows or Unix):
<?php
//...
//Open file, get entry and store in variable $e...
//...
$isDirectory = (bool) ((($e->getHostOs() == RAR_HOST_WIN32) && ($e->getAttr() & 0x10)) ||
(($e->getHostOs() == RAR_HOST_UNIX) && (($e->getAttr() & 0xf000) == 0x4000)));
?>
RarEntry::isEncrypted
(PECL rar >= 2.0.0)
RarEntry::isEncrypted — Test whether an entry is encrypted
Opis
Tests whether the current entry contents are encrypted.
Informacja:
The password used may differ between files inside the same RAR archive.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns TRUE if the current entry is encrypted and FALSE otherwise.
RarEntry::__toString
(PECL rar >= 2.0.0)
RarEntry::__toString — Get text representation of entry
Opis
RarEntry::__toString() returns a textual representation for this entry. It includes whether the entry is a file or a directory (symbolic links and other special objects will be treated as files), the UTF-8 name of the entry and its CRC. The form and content of this representation may be changed in the future, so they cannot be relied upon.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
A textual representation for the entry.
Spis treści
- RarEntry::extract — Extract entry from the archive
- RarEntry::getAttr — Get attributes of the entry
- RarEntry::getCrc — Get CRC of the entry
- RarEntry::getFileTime — Get entry last modification time
- RarEntry::getHostOs — Get entry host OS
- RarEntry::getMethod — Get pack method of the entry
- RarEntry::getName — Get name of the entry
- RarEntry::getPackedSize — Get packed size of the entry
- RarEntry::getStream — Get file handler for entry
- RarEntry::getUnpackedSize — Get unpacked size of the entry
- RarEntry::getVersion — Get minimum version of RAR program required to unpack the entry
- RarEntry::isDirectory — Test whether an entry represents a directory
- RarEntry::isEncrypted — Test whether an entry is encrypted
- RarEntry::__toString — Get text representation of entry
The RarException class
(No version information available, might only be in SVN)
Wstęp
This class serves two purposes: it is the type of the exceptions thrown by the RAR extension functions and methods and it allows, through static methods to query and define the error behaviour of the extension, i.e., whether exceptions are thrown or only warnings are emitted.
The following error codes are used:
- -1 - error outside UnRAR library
- 11 - insufficient memory
- 12 - bad data
- 13 - bad archive
- 14 - unknown format
- 15 - file open error
- 16 - file create error
- 17 - file close error
- 18 - read error
- 19 - write error
- 20 - buffer too small
- 21 - unkown RAR error
- 22 - password required but not given
Krótki opis klasy
RarException::isUsingExceptions
(PECL rar >= 2.0.0)
RarException::isUsingExceptions — Check whether error handling with exceptions is in use
Opis
Checks whether the RAR functions will emit warnings and return error values or whether they will throw exceptions in most of the circumstances (does not include some programmatic errors such as passing the wrong type of arguments).
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns TRUE if exceptions are being used, FALSE otherwise.
Przykłady
Przykład #1 RarException::isUsingExceptions() example
<?php
//The default is not to use exceptions
var_dump(RarException::isUsingExceptions());
?>
Powyższy przykład wyświetli coś podobnego do:
bool(false)
Zobacz też:
- RarException::setUsingExceptions() - Activate and deactivate error handling with exceptions
RarException::setUsingExceptions
(PECL rar >= 2.0.0)
RarException::setUsingExceptions — Activate and deactivate error handling with exceptions
Opis
$using_exceptions
)
If and only if the argument is TRUE, then, instead of emitting warnings and returning a special value indicating error when the UnRAR library encounters an error, an exception of type RarException will be thrown.
Exceptions will also be thrown for the following errors, which occur outside the library (their error code will be -1):
- attempting some operations on a closed RarArchive object or a RarEntry object relative to the first;
- attempting to get an entry that does not exist with RarArchive::getEntry().
Parametry
-
using_exceptions -
Should be
TRUEto activate exception throwing,FALSEto deactivate (the default).
Przykłady
Przykład #1 RarException::setUsingExceptions() example
<?php
var_dump(RarException::isUsingExceptions());
$arch = RarArchive::open("does_not_exist.rar");
var_dump($arch);
RarException::setUsingExceptions(true);
var_dump(RarException::isUsingExceptions());
$arch = RarArchive::open("does_not_exist.rar");
var_dump($arch); //not reached
?>
Powyższy przykład wyświetli coś podobnego do:
bool(false)
Warning: RarArchive::open(): Failed to open does_not_exist.rar: ERAR_EOPEN (file open error) in C:\php_rar\trunk\tests\test.php on line 3
bool(false)
bool(true)
Fatal error: Uncaught exception 'RarException' with message 'unRAR internal error: Failed to open does_not_exist.rar: ERAR_EOPEN (file open error)' in C:\php_rar\trunk\tests\test.php:8
Stack trace:
#0 C:\php_rar\trunk\tests\test.php(8): RarArchive::open('does_not_exist....')
#1 {main}
thrown in C:\php_rar\trunk\tests\test.php on line 8
Zobacz też:
- RarException::isUsingExceptions() - Check whether error handling with exceptions is in use
Spis treści
- RarException::isUsingExceptions — Check whether error handling with exceptions is in use
- RarException::setUsingExceptions — Activate and deactivate error handling with exceptions
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Przykłady
- Rar Funkcje
- rar_wrapper_cache_stats — Cache hits and misses for the URL wrapper
- RarArchive — The RarArchive class
- RarArchive::close — Close RAR archive and free all resources
- RarArchive::getComment — Get comment text from the RAR archive
- RarArchive::getEntries — Get full list of entries from the RAR archive
- RarArchive::getEntry — Get entry object from the RAR archive
- RarArchive::isBroken — Test whether an archive is broken (incomplete)
- RarArchive::isSolid — Check whether the RAR archive is solid
- RarArchive::open — Open RAR archive
- RarArchive::setAllowBroken — Whether opening broken archives is allowed
- RarArchive::__toString — Get text representation
- RarEntry — The RarEntry class
- RarEntry::extract — Extract entry from the archive
- RarEntry::getAttr — Get attributes of the entry
- RarEntry::getCrc — Get CRC of the entry
- RarEntry::getFileTime — Get entry last modification time
- RarEntry::getHostOs — Get entry host OS
- RarEntry::getMethod — Get pack method of the entry
- RarEntry::getName — Get name of the entry
- RarEntry::getPackedSize — Get packed size of the entry
- RarEntry::getStream — Get file handler for entry
- RarEntry::getUnpackedSize — Get unpacked size of the entry
- RarEntry::getVersion — Get minimum version of RAR program required to unpack the entry
- RarEntry::isDirectory — Test whether an entry represents a directory
- RarEntry::isEncrypted — Test whether an entry is encrypted
- RarEntry::__toString — Get text representation of entry
- RarException — The RarException class
- RarException::isUsingExceptions — Check whether error handling with exceptions is in use
- RarException::setUsingExceptions — Activate and deactivate error handling with exceptions
Zip
Wstęp
This extension enables you to transparently read or write ZIP compressed archives and the files inside them.
Instalacja/Konfiguracja
Spis treści
Wymagania
PHP 4
The bundled PHP 4 version requires » ZZIPlib, by Guido Draheim, version 0.10.6 or later
PHP 5.2.0 or later
This extension uses the functions of » zlib by Jean-loup Gailly and Mark Adler.
Instalacja
PHP 4
Informacja:
Zip support before PHP 4.1.0 is experimental.
Because the PHP 4 zip extension is unmaintained we recommend that the PECL extension is used rather than the bundled one.
Linux systems
In order to use these functions you must compile PHP with zip support by using the --with-zip[=DIR] configure option, where [DIR] is the prefix of the » ZZIPlib library install.
Windows
Windows users need to enable php_zip.dll inside of php.ini in order to use these functions.
PHP 5.2.0 and later
Linux systems
In order to use these functions you must compile PHP with zip support by using the --enable-zip configure option.
Windows
Windows users need to enable php_zip.dll inside of php.ini in order to use these functions.
Installation via PECL
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/zip.
DLL z tym rozszerzeniem PECL można pobrać zarówno ze strony » PHP Downloads lub z » http://pecl4win.php.net/
W PHP 4 ten DLL znajduje się w podkatalogu extensions/ binarnej dystrybucji PHP dla Windows.
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
There are two resource types used in the Zip module. The first one is the Zip directory for the Zip archive, the second Zip Entry for the archive entries.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
ZipArchive uses class constants. There are three types of constants : Flags (prefixed with FL_), errors (prefixed with ER_) and mode (no prefix).
-
ZIPARCHIVE::CREATE(integer) - Create the archive if it does not exist.
-
ZIPARCHIVE::OVERWRITE(integer) - Always start a new archive, this mode will overwrite the file if it already exists.
-
ZIPARCHIVE::EXCL(integer) - Error if archive already exists.
-
ZIPARCHIVE::CHECKCONS(integer) - Perform additional consistency checks on the archive, and error if they fail.
-
ZIPARCHIVE::FL_NOCASE(integer) - Ignore case on name lookup
-
ZIPARCHIVE::FL_NODIR(integer) - Ignore directory component
-
ZIPARCHIVE::FL_COMPRESSED(integer) - Read compressed data
-
ZIPARCHIVE::FL_UNCHANGED(integer) - Use original data, ignoring changes.
-
ZIPARCHIVE::CM_DEFAULT(integer) - better of deflate or store.
-
ZIPARCHIVE::CM_STORE(integer) - stored (uncompressed).
-
ZIPARCHIVE::CM_SHRINK(integer) - shrunk
-
ZIPARCHIVE::CM_REDUCE_1(integer) - reduced with factor 1
-
ZIPARCHIVE::CM_REDUCE_2(integer) - reduced with factor 2
-
ZIPARCHIVE::CM_REDUCE_3(integer) - reduced with factor 3
-
ZIPARCHIVE::CM_REDUCE_4(integer) - reduced with factor 4
-
ZIPARCHIVE::CM_IMPLODE(integer) - imploded
-
ZIPARCHIVE::CM_DEFLATE(integer) - deflated
-
ZIPARCHIVE::CM_DEFLATE64(integer) - deflate64
-
ZIPARCHIVE::CM_PKWARE_IMPLODE(integer) - PKWARE imploding
-
ZIPARCHIVE::CM_BZIP2(integer) - BZIP2 algorithm
-
ZIPARCHIVE::ER_OK(integer) - No error.
-
ZIPARCHIVE::ER_MULTIDISK(integer) - Multi-disk zip archives not supported.
-
ZIPARCHIVE::ER_RENAME(integer) - Renaming temporary file failed.
-
ZIPARCHIVE::ER_CLOSE(integer) - Closing zip archive failed
-
ZIPARCHIVE::ER_SEEK(integer) - Seek error
-
ZIPARCHIVE::ER_READ(integer) - Read error
-
ZIPARCHIVE::ER_WRITE(integer) - Write error
-
ZIPARCHIVE::ER_CRC(integer) - CRC error
-
ZIPARCHIVE::ER_ZIPCLOSED(integer) - Containing zip archive was closed
-
ZIPARCHIVE::ER_NOENT(integer) - No such file.
-
ZIPARCHIVE::ER_EXISTS(integer) - File already exists
-
ZIPARCHIVE::ER_OPEN(integer) - Can't open file
-
ZIPARCHIVE::ER_TMPOPEN(integer) - Failure to create temporary file.
-
ZIPARCHIVE::ER_ZLIB(integer) - Zlib error
-
ZIPARCHIVE::ER_MEMORY(integer) - Memory allocation failure
-
ZIPARCHIVE::ER_CHANGED(string) - Entry has been changed
-
ZIPARCHIVE::ER_COMPNOTSUPP(integer) - Compression method not supported.
-
ZIPARCHIVE::ER_EOF(integer) - Premature EOF
-
ZIPARCHIVE::ER_INVAL(integer) - Invalid argument
-
ZIPARCHIVE::ER_NOZIP(integer) - Not a zip archive
-
ZIPARCHIVE::ER_INTERNAL(integer) - Internal error
-
ZIPARCHIVE::ER_INCONS(integer) - Zip archive inconsistent
-
ZIPARCHIVE::ER_REMOVE(integer) - Can't remove file
-
ZIPARCHIVE::ER_DELETED(integer) - Entry has been deleted
Przykłady
Przykład #1 Create a Zip archive
<?php
$zip = new ZipArchive();
$filename = "./test112.zip";
if ($zip->open($filename, ZIPARCHIVE::CREATE)!==TRUE) {
exit("cannot open <$filename>\n");
}
$zip->addFromString("testfilephp.txt" . time(), "#1 This is a test string added as testfilephp.txt.\n");
$zip->addFromString("testfilephp2.txt" . time(), "#2 This is a test string added as testfilephp2.txt.\n");
$zip->addFile($thisdir . "/too.php","/testfromfile.php");
echo "numfiles: " . $zip->numFiles . "\n";
echo "status:" . $zip->status . "\n";
$zip->close();
?>
Przykład #2 Dump the archive details and listing
<?php
$za = new ZipArchive();
$za->open('test_with_comment.zip');
print_r($za);
var_dump($za);
echo "numFiles: " . $za->numFiles . "\n";
echo "status: " . $za->status . "\n";
echo "statusSys: " . $za->statusSys . "\n";
echo "filename: " . $za->filename . "\n";
echo "comment: " . $za->comment . "\n";
for ($i=0; $i<$za->numFiles;$i++) {
echo "index: $i\n";
print_r($za->statIndex($i));
}
echo "numFile:" . $za->numFiles . "\n";
?>
Przykład #3 Zip stream wrapper, read an OpenOffice meta info
<?php
$reader = new XMLReader();
$reader->open('zip://' . dirname(__FILE__) . '/test.odt#meta.xml');
$odt_meta = array();
while ($reader->read()) {
if ($reader->nodeType == XMLREADER::ELEMENT) {
$elm = $reader->name;
} else {
if ($reader->nodeType == XMLREADER::END_ELEMENT && $reader->name == 'office:meta') {
break;
}
if (!trim($reader->value)) {
continue;
}
$odt_meta[$elm] = $reader->value;
}
}
print_r($odt_meta);
?>
This example uses the old API (PHP 4), it opens a ZIP file archive, reads each file in the archive and prints out its contents. The test2.zip archive used in this example is one of the test archives in the ZZIPlib source distribution.
Przykład #4 Zip Usage Example
<?php
$zip = zip_open("/tmp/test2.zip");
if ($zip) {
while ($zip_entry = zip_read($zip)) {
echo "Name: " . zip_entry_name($zip_entry) . "\n";
echo "Actual Filesize: " . zip_entry_filesize($zip_entry) . "\n";
echo "Compressed Size: " . zip_entry_compressedsize($zip_entry) . "\n";
echo "Compression Method: " . zip_entry_compressionmethod($zip_entry) . "\n";
if (zip_entry_open($zip, $zip_entry, "r")) {
echo "File Contents:\n";
$buf = zip_entry_read($zip_entry, zip_entry_filesize($zip_entry));
echo "$buf\n";
zip_entry_close($zip_entry);
}
echo "\n";
}
zip_close($zip);
}
?>
The ZipArchive class
(No version information available, might only be in SVN)
Wstęp
A file archive, compressed with Zip.
Krótki opis klasy
$filename
[, string $localname = NULL
[, int $start = 0
[, int $length = 0
]]] )Właściwości
- status
-
Status of the Zip Archive
- statusSys
-
System status of the Zip Archive
- numFiles
-
Number of files in archive
- filename
-
File name in the file system
- comment
-
Comment for the archive
ZipArchive::addEmptyDir
(PHP 5 >= 5.2.0, PECL zip >= 1.8.0)
ZipArchive::addEmptyDir — Add a new directory
Opis
$dirname
)Adds an empty directory in the archive.
Parametry
-
dirname -
The directory to add.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Create a new directory in an archive
<?php
$zip = new ZipArchive;
if ($zip->open('test.zip') === TRUE) {
if($zip->addEmptyDir('newDirectory')) {
echo 'Created a new root directory';
} else {
echo 'Could not create the directory';
}
$zip->close();
} else {
echo 'failed';
}
?>
ZipArchive::addFile
(PHP 5 >= 5.2.0, PECL zip >= 1.1.0)
ZipArchive::addFile — Adds a file to a ZIP archive from the given path
Opis
$filename
[, string $localname = NULL
[, int $start = 0
[, int $length = 0
]]] )Adds a file to a ZIP archive from a given path.
Parametry
-
filename -
The path to the file to add.
-
localname -
If supplied, this is the local name inside the ZIP archive that will override the
filename. -
start -
This parameter is not used but is required to extend ZipArchive.
-
length -
This parameter is not used but is required to extend ZipArchive.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
This example opens a ZIP file archive test.zip and add the file /path/to/index.txt. as newname.txt.
Przykład #1 Open and extract
<?php
$zip = new ZipArchive;
if ($zip->open('test.zip') === TRUE) {
$zip->addFile('/path/to/index.txt', 'newname.txt');
$zip->close();
echo 'ok';
} else {
echo 'failed';
}
?>
Notatki
Informacja:
When a file is set to be added to the archive, PHP will attempt to lock the file and it is only released once the ZIP operation is done. In short, it means you can first delete an added file after the archive is closed.
ZipArchive::addFromString
(PHP 5 >= 5.2.0, PECL zip >= 1.1.0)
ZipArchive::addFromString — Add a file to a ZIP archive using its contents
Opis
$localname
, string $contents
)Add a file to a ZIP archive using its contents.
Parametry
-
localname -
The name of the entry to create.
-
contents -
The contents to use to create the entry. It is used in a binary safe mode.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Add an entry to a new archive
<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip', ZipArchive::CREATE);
if ($res === TRUE) {
$zip->addFromString('test.txt', 'file content goes here');
$zip->close();
echo 'ok';
} else {
echo 'failed';
}
?>
Przykład #2 Add file to a directory inside an archive
<?php
$zip = new ZipArchive;
if ($zip->open('test.zip') === TRUE) {
$zip->addFromString('dir/test.txt', 'file content goes here');
$zip->close();
echo 'ok';
} else {
echo 'failed';
}
?>
ZipArchive::close
(PHP 5 >= 5.2.0, PECL zip >= 1.1.0)
ZipArchive::close — Close the active archive (opened or newly created)
Opis
Close opened or created archive and save changes. This method is automatically called at the end of the script.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
ZipArchive::deleteIndex
(PHP 5 >= 5.2.0, PECL zip >= 1.5.0)
ZipArchive::deleteIndex — delete an entry in the archive using its index
Opis
$index
)Delete an entry in the archive using its index.
Parametry
-
index -
Index of the entry to delete.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Delete file from archive using its index
<?php
$zip = new ZipArchive;
if ($zip->open('test.zip') === TRUE) {
$zip->deleteIndex(2);
$zip->close();
echo 'ok';
} else {
echo 'failed';
}
?>
ZipArchive::deleteName
(PHP 5 >= 5.2.0, PECL zip >= 1.5.0)
ZipArchive::deleteName — delete an entry in the archive using its name
Opis
$name
)Delete an entry in the archive using its name.
Parametry
-
name -
Name of the entry to delete.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Deleting a file and directory from an archive, using names
<?php
$zip = new ZipArchive;
if ($zip->open('test1.zip') === TRUE) {
$zip->deleteName('testfromfile.php');
$zip->deleteName('testDir/');
$zip->close();
echo 'ok';
} else {
echo 'failed';
}
?>
ZipArchive::extractTo
(PHP 5 >= 5.2.0, PECL zip >= 1.1.0)
ZipArchive::extractTo — Extract the archive contents
Opis
Extract the complete archive or the given files to the specified destination.
Parametry
-
destination -
Location where to extract the files.
-
entries -
The entries to extract. It accepts either a single entry name or an array of names.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Extract all entries
<?php
$zip = new ZipArchive;
if ($zip->open('test.zip') === TRUE) {
$zip->extractTo('/my/destination/dir/');
$zip->close();
echo 'ok';
} else {
echo 'failed';
}
?>
Przykład #2 Extract two entries
<?php
$zip = new ZipArchive;
$res = $zip->open('test_im.zip');
if ($res === TRUE) {
$zip->extractTo('/my/destination/dir/', array('pear_item.gif', 'testfromfile.php'));
$zip->close();
echo 'ok';
} else {
echo 'failed';
}
?>
ZipArchive::getArchiveComment
(PHP 5 >= 5.2.0, PECL zip >= 1.1.0)
ZipArchive::getArchiveComment — Returns the Zip archive comment
Opis
$flags
] )Returns the Zip archive comment.
Parametry
-
flags -
If flags is set to
ZIPARCHIVE::FL_UNCHANGED, the original unchanged comment is returned.
Zwracane wartości
Returns the Zip archive comment lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 Dump an archive comment
<?php
$zip = new ZipArchive;
$res = $zip->open('test_with_comment.zip');
if ($res === TRUE) {
var_dump($zip->getArchiveComment());
/* Or using the archive property */
var_dump($zip->comment);
} else {
echo 'failed, code:' . $res;
}
?>
ZipArchive::getCommentIndex
(PHP 5 >= 5.2.0, PECL zip >= 1.4.0)
ZipArchive::getCommentIndex — Returns the comment of an entry using the entry index
Opis
$index
[, int $flags
] )Returns the comment of an entry using the entry index.
Parametry
-
index -
Index of the entry
-
flags -
If flags is set to
ZIPARCHIVE::FL_UNCHANGED, the original unchanged comment is returned.
Zwracane wartości
Returns the comment on success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 Dump an entry comment
<?php
$zip = new ZipArchive;
$res = $zip->open('test1.zip');
if ($res === TRUE) {
var_dump($zip->getCommentIndex(1));
} else {
echo 'failed, code:' . $res;
}
?>
ZipArchive::getCommentName
(PHP 5 >= 5.2.0, PECL zip >= 1.4.0)
ZipArchive::getCommentName — Returns the comment of an entry using the entry name
Opis
$name
[, int $flags
] )Returns the comment of an entry using the entry name.
Parametry
-
name -
Name of the entry
-
flags -
If flags is set to
ZIPARCHIVE::FL_UNCHANGED, the original unchanged comment is returned.
Zwracane wartości
Returns the comment on success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 Dump an entry comment
<?php
$zip = new ZipArchive;
$res = $zip->open('test1.zip');
if ($res === TRUE) {
var_dump($zip->getCommentName('test/entry1.txt'));
} else {
echo 'failed, code:' . $res;
}
?>
ZipArchive::getFromIndex
(PHP 5 >= 5.2.0, PECL zip >= 1.3.0)
ZipArchive::getFromIndex — Returns the entry contents using its index
Opis
Returns the entry contents using its index.
Parametry
-
index -
Index of the entry
-
length -
The length to be read from the entry. If 0, then the entire entry is read.
-
flags -
The flags to use to open the archive. the following values may be ORed to it.
-
ZIPARCHIVE::FL_UNCHANGED -
ZIPARCHIVE::FL_COMPRESSED
-
Zwracane wartości
Returns the contents of the entry on success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 Get the file contents
<?php
$zip = new ZipArchive;
if ($zip->open('test.zip') === TRUE) {
echo $zip->getFromIndex(2);
$zip->close();
} else {
echo 'failed';
}
?>
ZipArchive::getFromName
(PHP 5 >= 5.2.0, PECL zip >= 1.1.0)
ZipArchive::getFromName — Returns the entry contents using its name
Opis
Returns the entry contents using its name.
Parametry
-
name -
Name of the entry
-
length -
The length to be read from the entry. If 0, then the entire entry is read.
-
flags -
The flags to use to open the archive. the following values may be ORed to it.
-
ZIPARCHIVE::FL_UNCHANGED -
ZIPARCHIVE::FL_COMPRESSED
-
Zwracane wartości
Returns the contents of the entry on success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 Get the file contents
<?php
$zip = new ZipArchive;
if ($zip->open('test1.zip') === TRUE) {
echo $zip->getFromName('testfromfile.php');
$zip->close();
} else {
echo 'failed';
}
?>
Przykład #2 Convert an image from a zip entry
<?php
$z = new ZipArchive();
if ($z->open(dirname(__FILE__) . '/test_im.zip')) {
$im_string = $z->getFromName("pear_item.gif");
$im = imagecreatefromstring($im_string);
imagepng($im, 'b.png');
}
?>
ZipArchive::getNameIndex
(PHP 5 >= 5.2.0, PECL zip >= 1.5.0)
ZipArchive::getNameIndex — Returns the name of an entry using its index
Opis
$index
[, int $flags
] )Returns the name of an entry using its index.
Parametry
-
index -
Index of the entry.
-
flags -
If flags is set to
ZIPARCHIVE::FL_UNCHANGED, the original unchanged name is returned.
Zwracane wartości
Returns the name on success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 getnameindex() example
<?php
if ($zip->open('test.zip') == TRUE) {
for ($i = 0; $i < $zip->numFiles; $i++) {
$filename = $zip->getNameIndex($i);
// ...
}
}
?>
ZipArchive::getStatusString
(PHP 5 >= 5.2.7)
ZipArchive::getStatusString — Returns the status error message, system and/or zip messages
Opis
Returns the status error message, system and/or zip messages.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns a string with the status message on success lub FALSE w przypadku niepowodzenia.
ZipArchive::getStream
(PHP 5 >= 5.2.0, PECL zip >= 1.1.0)
ZipArchive::getStream — Get a file handler to the entry defined by its name (read only).
Opis
$name
)Get a file handler to the entry defined by its name. For now it only supports read operations.
Parametry
-
name -
The name of the entry to use.
Zwracane wartości
Returns a file pointer (resource) on success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 Get the entry contents with fread() and store it
<?php
$content = '';
$z = new ZipArchive();
if ($z->open('test.zip')) {
$fp = $z->getStream('test');
if(!$fp) exit("failed\n");
while (!feof($fp)) {
$contents .= fread($fp, 2);
}
fclose($fp);
file_put_contents('t',$contents);
echo "done.\n";
}
?>
Przykład #2 Same as the previous example but with fopen() and the zip stream wrapper
<?php
$fp = fopen('zip://' . dirname(__FILE__) . '/test.zip#test', 'r');
if (!$fp) {
exit("cannot open\n");
}
while (!feof($fp)) {
$contents .= fread($fp, 2);
echo "$contents\n";
}
fclose($fp);
echo "done.\n";
?>
Przykład #3 Stream wrapper and image, can be used with the xml function as well
<?php
$im = imagecreatefromgif('zip://' . dirname(__FILE__) . '/test_im.zip#pear_item.gif');
imagepng($im, 'a.png');
?>
ZipArchive::locateName
(PHP 5 >= 5.2.0, PECL zip >= 1.5.0)
ZipArchive::locateName — Returns the index of the entry in the archive
Parametry
-
name -
The name of the entry to look up
-
flags -
The flags are specified by ORing the following values, or 0 for none of them.
-
ZIPARCHIVE::FL_NOCASE -
ZIPARCHIVE::FL_NODIR
-
Zwracane wartości
Returns the index of the entry on success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 Create an archive and then use it with ZipArchive::locateName()
<?php
$file = 'testlocate.zip';
$zip = new ZipArchive;
if ($zip->open($file, ZIPARCHIVE::CREATE) !== TRUE) {
exit('failed');
}
$zip->addFromString('entry1.txt', 'entry #1');
$zip->addFromString('entry2.txt', 'entry #2');
$zip->addFromString('dir/entry2d.txt', 'entry #2');
if (!$zip->status == ZIPARCHIVE::ER_OK) {
echo "failed to write zip\n";
}
$zip->close();
if ($zip->open($file) !== TRUE) {
exit('failed');
}
echo $zip->locateName('entry1.txt') . "\n";
echo $zip->locateName('eNtry2.txt') . "\n";
echo $zip->locateName('eNtry2.txt', ZIPARCHIVE::FL_NOCASE) . "\n";
echo $zip->locateName('enTRy2d.txt', ZIPARCHIVE::FL_NOCASE|ZIPARCHIVE::FL_NODIR) . "\n";
$zip->close();
?>
Powyższy przykład wyświetli:
0 1 2
ZipArchive::open
(PHP 5 >= 5.2.0, PECL zip >= 1.1.0)
ZipArchive::open — Open a ZIP file archive
Opis
Opens a new zip archive for reading, writing or modifying.
Parametry
-
filename -
The file name of the ZIP archive to open.
-
flags -
The mode to use to open the archive.
-
ZIPARCHIVE::OVERWRITE -
ZIPARCHIVE::CREATE -
ZIPARCHIVE::EXCL -
ZIPARCHIVE::CHECKCONS
-
Zwracane wartości
-
Error codes -
Returns
TRUEon success or the error code.-
ZIPARCHIVE::ER_EXISTSFile already exists.
-
ZIPARCHIVE::ER_INCONSZip archive inconsistent.
-
ZIPARCHIVE::ER_INVALInvalid argument.
-
ZIPARCHIVE::ER_MEMORYMalloc failure.
-
ZIPARCHIVE::ER_NOENTNo such file.
-
ZIPARCHIVE::ER_NOZIPNot a zip archive.
-
ZIPARCHIVE::ER_OPENCan't open file.
-
ZIPARCHIVE::ER_READRead error.
-
ZIPARCHIVE::ER_SEEKSeek error.
-
Przykłady
Przykład #1 Open and extract
<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip');
if ($res === TRUE) {
echo 'ok';
$zip->extractTo('test');
$zip->close();
} else {
echo 'failed, code:' . $res;
}
?>
Przykład #2 Create an archive
<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip', ZipArchive::CREATE);
if ($res === TRUE) {
$zip->addFromString('test.txt', 'file content goes here');
$zip->addFile('data.txt', 'entryname.txt');
$zip->close();
echo 'ok';
} else {
echo 'failed';
}
?>
ZipArchive::renameIndex
(PHP 5 >= 5.2.0, PECL zip >= 1.5.0)
ZipArchive::renameIndex — Renames an entry defined by its index
Opis
$index
, string $newname
)Renames an entry defined by its index.
Parametry
-
index -
Index of the entry to rename.
-
newname -
New name.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Rename one entry
<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip');
if ($res === TRUE) {
$zip->renameIndex(2,'newname.txt');
$zip->close();
} else {
echo 'failed, code:' . $res;
}
?>
ZipArchive::renameName
(PHP 5 >= 5.2.0, PECL zip >= 1.5.0)
ZipArchive::renameName — Renames an entry defined by its name
Opis
$name
, string $newname
)Renames an entry defined by its name.
Parametry
-
name -
Name of the entry to rename.
-
newname -
New name.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Rename one entry
<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip');
if ($res === TRUE) {
$zip->renameName('currentname.txt','newname.txt');
$zip->close();
} else {
echo 'failed, code:' . $res;
}
?>
ZipArchive::setArchiveComment
(PHP 5 >= 5.2.0, PECL zip >= 1.4.0)
ZipArchive::setArchiveComment — Set the comment of a ZIP archive
Parametry
-
comment -
The contents of the comment.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Create an archive and set a comment
<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip', ZipArchive::CREATE);
if ($res === TRUE) {
$zip->addFromString('test.txt', 'file content goes here');
$zip->setArchiveComment('new archive comment');
$zip->close();
echo 'ok';
} else {
echo 'failed';
}
?>
ZipArchive::setCommentIndex
(PHP 5 >= 5.2.0, PECL zip >= 1.4.0)
ZipArchive::setCommentIndex — Set the comment of an entry defined by its index
Opis
Set the comment of an entry defined by its index.
Parametry
-
index -
Index of the entry.
-
comment -
The contents of the comment.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Open an archive and set a comment for an entry
<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip');
if ($res === TRUE) {
$zip->setCommentIndex(2, 'new entry comment');
$zip->close();
echo 'ok';
} else {
echo 'failed';
}
?>
ZipArchive::setCommentName
(PHP 5 >= 5.2.0, PECL zip >= 1.4.0)
ZipArchive::setCommentName — Set the comment of an entry defined by its name
Opis
Set the comment of an entry defined by its name.
Parametry
-
name -
Name of the entry.
-
comment -
The contents of the comment.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Open an archive and set a comment for an entry
<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip');
if ($res === TRUE) {
$zip->setCommentName('entry1.txt', 'new entry comment');
$zip->close();
echo 'ok';
} else {
echo 'failed';
}
?>
ZipArchive::statIndex
(PHP 5 >= 5.2.0, PECL zip >= 1.1.0)
ZipArchive::statIndex — Get the details of an entry defined by its index.
Opis
The function obtains information about the entry defined by its index.
Parametry
-
index -
Index of the entry
-
flags -
ZIPARCHIVE::FL_UNCHANGEDmay be ORed to it to request information about the original file in the archive, ignoring any changes made.
Zwracane wartości
Returns an array containing the entry details lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 Dump the stat info of an entry
<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip');
if ($res === TRUE) {
print_r($zip->statIndex(3));
$zip->close();
} else {
echo 'failed, code:' . $res;
}
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[name] => foobar/baz
[index] => 3
[crc] => 499465816
[size] => 27
[mtime] => 1123164748
[comp_size] => 24
[comp_method] => 8
)
ZipArchive::statName
(PHP 5 >= 5.2.0, PECL zip >= 1.5.0)
ZipArchive::statName — Get the details of an entry defined by its name.
Opis
The function obtains information about the entry defined by its name.
Parametry
-
name -
Name of the entry
-
flags -
The flags argument specifies how the name lookup should be done. Also,
ZIPARCHIVE::FL_UNCHANGEDmay be ORed to it to request information about the original file in the archive, ignoring any changes made.-
ZIPARCHIVE::FL_NOCASE -
ZIPARCHIVE::FL_NODIR -
ZIPARCHIVE::FL_UNCHANGED
-
Zwracane wartości
Returns an array containing the entry details lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 Dump the stat info of an entry
<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip');
if ($res === TRUE) {
print_r($zip->statName('foobar/baz'));
$zip->close();
} else {
echo 'failed, code:' . $res;
}
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[name] => foobar/baz
[index] => 3
[crc] => 499465816
[size] => 27
[mtime] => 1123164748
[comp_size] => 24
[comp_method] => 8
)
ZipArchive::unchangeAll
(PHP 5 >= 5.2.0, PECL zip >= 1.1.0)
ZipArchive::unchangeAll — Undo all changes done in the archive
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
ZipArchive::unchangeArchive
(PHP 5 >= 5.2.0, PECL zip >= 1.1.0)
ZipArchive::unchangeArchive — Revert all global changes done in the archive.
Opis
Revert all global changes to the archive. For now, this only reverts archive comment changes.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
ZipArchive::unchangeIndex
(PHP 5 >= 5.2.0, PECL zip >= 1.1.0)
ZipArchive::unchangeIndex — Revert all changes done to an entry at the given index
Opis
Revert all changes done to an entry at the given index.
Parametry
-
index -
Index of the entry.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
ZipArchive::unchangeName
(PHP 5 >= 5.2.0, PECL zip >= 1.5.0)
ZipArchive::unchangeName — Revert all changes done to an entry with the given name.
Parametry
-
name -
Name of the entry.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Spis treści
- ZipArchive::addEmptyDir — Add a new directory
- ZipArchive::addFile — Adds a file to a ZIP archive from the given path
- ZipArchive::addFromString — Add a file to a ZIP archive using its contents
- ZipArchive::close — Close the active archive (opened or newly created)
- ZipArchive::deleteIndex — delete an entry in the archive using its index
- ZipArchive::deleteName — delete an entry in the archive using its name
- ZipArchive::extractTo — Extract the archive contents
- ZipArchive::getArchiveComment — Returns the Zip archive comment
- ZipArchive::getCommentIndex — Returns the comment of an entry using the entry index
- ZipArchive::getCommentName — Returns the comment of an entry using the entry name
- ZipArchive::getFromIndex — Returns the entry contents using its index
- ZipArchive::getFromName — Returns the entry contents using its name
- ZipArchive::getNameIndex — Returns the name of an entry using its index
- ZipArchive::getStatusString — Returns the status error message, system and/or zip messages
- ZipArchive::getStream — Get a file handler to the entry defined by its name (read only).
- ZipArchive::locateName — Returns the index of the entry in the archive
- ZipArchive::open — Open a ZIP file archive
- ZipArchive::renameIndex — Renames an entry defined by its index
- ZipArchive::renameName — Renames an entry defined by its name
- ZipArchive::setArchiveComment — Set the comment of a ZIP archive
- ZipArchive::setCommentIndex — Set the comment of an entry defined by its index
- ZipArchive::setCommentName — Set the comment of an entry defined by its name
- ZipArchive::statIndex — Get the details of an entry defined by its index.
- ZipArchive::statName — Get the details of an entry defined by its name.
- ZipArchive::unchangeAll — Undo all changes done in the archive
- ZipArchive::unchangeArchive — Revert all global changes done in the archive.
- ZipArchive::unchangeIndex — Revert all changes done to an entry at the given index
- ZipArchive::unchangeName — Revert all changes done to an entry with the given name.
Zip Funkcje
zip_close
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PECL zip >= 1.0.0)
zip_close — Close a ZIP file archive
Opis
$zip
)Closes the given ZIP file archive.
Zwracane wartości
Nie jest zwracana żadna wartość.
zip_entry_close
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PECL zip >= 1.0.0)
zip_entry_close — Close a directory entry
Opis
$zip_entry
)Closes the specified directory entry.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- zip_entry_open() - Open a directory entry for reading
- zip_entry_read() - Read from an open directory entry
zip_entry_compressedsize
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PECL zip >= 1.0.0)
zip_entry_compressedsize — Retrieve the compressed size of a directory entry
Opis
$zip_entry
)Returns the compressed size of the specified directory entry.
Zwracane wartości
The compressed size.
zip_entry_compressionmethod
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PECL zip >= 1.0.0)
zip_entry_compressionmethod — Retrieve the compression method of a directory entry
Opis
$zip_entry
)
Returns the compression method of the directory entry specified
by zip_entry.
Zwracane wartości
The compression method.
zip_entry_filesize
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PECL zip >= 1.0.0)
zip_entry_filesize — Retrieve the actual file size of a directory entry
Opis
$zip_entry
)Returns the actual size of the specified directory entry.
Zwracane wartości
The size of the directory entry.
zip_entry_name
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PECL zip >= 1.0.0)
zip_entry_name — Retrieve the name of a directory entry
Opis
$zip_entry
)Returns the name of the specified directory entry.
Zwracane wartości
The name of the directory entry.
zip_entry_open
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PECL zip >= 1.0.0)
zip_entry_open — Open a directory entry for reading
Opis
$zip
, resource $zip_entry
[, string $mode
] )Opens a directory entry in a zip file for reading.
Parametry
-
zip -
A valid resource handle returned by zip_open().
-
zip_entry -
A directory entry returned by zip_read().
-
mode -
Any of the modes specified in the documentation of fopen().
Informacja:
Currently,
modeis ignored and is always "rb". This is due to the fact that zip support in PHP is read only access.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Informacja:
Unlike fopen() and other similar functions, the return value of zip_entry_open() only indicates the result of the operation and is not needed for reading or closing the directory entry.
Zobacz też:
- zip_entry_close() - Close a directory entry
- zip_entry_read() - Read from an open directory entry
zip_entry_read
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PECL zip >= 1.0.0)
zip_entry_read — Read from an open directory entry
Opis
$zip_entry
[, int $length
] )Reads from an open directory entry.
Parametry
-
zip_entry -
A directory entry returned by zip_read().
-
length -
The number of bytes to return. If not specified, this function will attempt to read 1024 bytes.
Informacja:
This should be the uncompressed length you wish to read.
Zwracane wartości
Returns the data read, or FALSE if the end of the file is
reached.
Zobacz też:
- zip_entry_open() - Open a directory entry for reading
- zip_entry_close() - Close a directory entry
- zip_entry_filesize() - Retrieve the actual file size of a directory entry
zip_open
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PECL zip >= 1.0.0)
zip_open — Open a ZIP file archive
Opis
$filename
)Opens a new zip archive for reading.
Parametry
-
filename -
The file name of the ZIP archive to open.
Zwracane wartości
Returns a resource handle for later use with
zip_read() and zip_close()
or returns the number of error if filename does not
exist or in case of other error.
Zobacz też:
- zip_read() - Read next entry in a ZIP file archive
- zip_close() - Close a ZIP file archive
zip_read
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PECL zip >= 1.0.0)
zip_read — Read next entry in a ZIP file archive
Opis
$zip
)Reads the next entry in a zip file archive.
Zwracane wartości
Returns a directory entry resource for later use with the
zip_entry_... functions, or FALSE if
there are no more entries to read, or an error code if an error
occurred.
Zobacz też:
- zip_open() - Open a ZIP file archive
- zip_close() - Close a ZIP file archive
- zip_entry_open() - Open a directory entry for reading
- zip_entry_read() - Read from an open directory entry
Spis treści
- zip_close — Close a ZIP file archive
- zip_entry_close — Close a directory entry
- zip_entry_compressedsize — Retrieve the compressed size of a directory entry
- zip_entry_compressionmethod — Retrieve the compression method of a directory entry
- zip_entry_filesize — Retrieve the actual file size of a directory entry
- zip_entry_name — Retrieve the name of a directory entry
- zip_entry_open — Open a directory entry for reading
- zip_entry_read — Read from an open directory entry
- zip_open — Open a ZIP file archive
- zip_read — Read next entry in a ZIP file archive
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Przykłady
- ZipArchive — The ZipArchive class
- ZipArchive::addEmptyDir — Add a new directory
- ZipArchive::addFile — Adds a file to a ZIP archive from the given path
- ZipArchive::addFromString — Add a file to a ZIP archive using its contents
- ZipArchive::close — Close the active archive (opened or newly created)
- ZipArchive::deleteIndex — delete an entry in the archive using its index
- ZipArchive::deleteName — delete an entry in the archive using its name
- ZipArchive::extractTo — Extract the archive contents
- ZipArchive::getArchiveComment — Returns the Zip archive comment
- ZipArchive::getCommentIndex — Returns the comment of an entry using the entry index
- ZipArchive::getCommentName — Returns the comment of an entry using the entry name
- ZipArchive::getFromIndex — Returns the entry contents using its index
- ZipArchive::getFromName — Returns the entry contents using its name
- ZipArchive::getNameIndex — Returns the name of an entry using its index
- ZipArchive::getStatusString — Returns the status error message, system and/or zip messages
- ZipArchive::getStream — Get a file handler to the entry defined by its name (read only).
- ZipArchive::locateName — Returns the index of the entry in the archive
- ZipArchive::open — Open a ZIP file archive
- ZipArchive::renameIndex — Renames an entry defined by its index
- ZipArchive::renameName — Renames an entry defined by its name
- ZipArchive::setArchiveComment — Set the comment of a ZIP archive
- ZipArchive::setCommentIndex — Set the comment of an entry defined by its index
- ZipArchive::setCommentName — Set the comment of an entry defined by its name
- ZipArchive::statIndex — Get the details of an entry defined by its index.
- ZipArchive::statName — Get the details of an entry defined by its name.
- ZipArchive::unchangeAll — Undo all changes done in the archive
- ZipArchive::unchangeArchive — Revert all global changes done in the archive.
- ZipArchive::unchangeIndex — Revert all changes done to an entry at the given index
- ZipArchive::unchangeName — Revert all changes done to an entry with the given name.
- Zip Funkcje
- zip_close — Close a ZIP file archive
- zip_entry_close — Close a directory entry
- zip_entry_compressedsize — Retrieve the compressed size of a directory entry
- zip_entry_compressionmethod — Retrieve the compression method of a directory entry
- zip_entry_filesize — Retrieve the actual file size of a directory entry
- zip_entry_name — Retrieve the name of a directory entry
- zip_entry_open — Open a directory entry for reading
- zip_entry_read — Read from an open directory entry
- zip_open — Open a ZIP file archive
- zip_read — Read next entry in a ZIP file archive
Zlib Compression
Wstęp
This module enables you to transparently read and write gzip (.gz) compressed files, through versions of most of the filesystem functions which work with gzip-compressed files (and uncompressed files, too, but not with sockets).
Informacja:
Version 4.0.4 introduced a fopen-wrapper for .gz-files, so that you can use a special zlib: URL to access compressed files transparently using the normal f*() file access functions if you prefix the filename or path with zlib: when calling fopen(). This feature requires a C runtime library that provides the fopencookie() function. Up to now the GNU libc seems to be the only library that provides this feature.
In PHP 4.3.0, zlib: has been changed to compress.zlib:// to prevent ambiguities with filenames containing ':' characters. The fopencookie() function is no longer required. More information is available in the section about zlib://.
Instalacja/Konfiguracja
Spis treści
Wymagania
This module uses the functions of » zlib by Jean-loup Gailly and Mark Adler. You have to use a zlib version >= 1.0.9 with this module.
Instalacja
Zlib support in PHP is not enabled by default. You will need to configure PHP --with-zlib[=DIR]
PHP w wersji dla systemów Windows posiada wbudowaną obsługę dla tego rozszerzenia. Nie trzeba ładować żadnych dodatkowych rozszerzeń, aby używać tych funkcji.
Informacja: Built-in support for zlib on Windows is available with PHP 4.3.0.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
The zlib extension offers the option to transparently compress your pages on-the-fly, if the requesting browser supports this. Therefore there are three options in the configuration file php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| zlib.output_compression | "0" | PHP_INI_ALL | Available since PHP 4.0.5. |
| zlib.output_compression_level | "-1" | PHP_INI_ALL | Available since PHP 4.3.0. |
| zlib.output_handler | "" | PHP_INI_ALL | Available since PHP 4.3.0. |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
zlib.output_compressionboolean/integer -
Whether to transparently compress pages. If this option is set to "On" in php.ini or the Apache configuration, pages are compressed if the browser sends an "Accept-Encoding: gzip" or "deflate" header. "Content-Encoding: gzip" (respectively "deflate") and "Vary: Accept-Encoding" headers are added to the output. In runtime, it can be set only before sending any output.
This option also accepts integer values instead of boolean "On"/"Off", using this you can set the output buffer size (default is 4KB).
Informacja:
output_handler must be empty if this is set 'On' ! Instead you must use zlib.output_handler.
-
zlib.output_compression_levelinteger -
Compression level used for transparent output compression. Specify a value between 0 (no compression) to 9 (most compression). The default value, -1, lets the server decide which level to use.
-
zlib.output_handlerstring -
You cannot specify additional output handlers if zlib.output_compression is activated here. This setting does the same as output_handler but in a different order.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
Przykłady
This example opens a temporary file and writes a test string to it, then it prints out the content of this file twice.
Przykład #1 Small Zlib Example
<?php
$filename = tempnam('/tmp', 'zlibtest') . '.gz';
echo "<html>\n<head></head>\n<body>\n<pre>\n";
$s = "Only a test, test, test, test, test, test, test, test!\n";
// open file for writing with maximum compression
$zp = gzopen($filename, "w9");
// write string to file
gzwrite($zp, $s);
// close file
gzclose($zp);
// open file for reading
$zp = gzopen($filename, "r");
// read 3 char
echo gzread($zp, 3);
// output until end of the file and close it.
gzpassthru($zp);
gzclose($zp);
echo "\n";
// open file and print content (the 2nd time).
if (readgzfile($filename) != strlen($s)) {
echo "Error with zlib functions!";
}
unlink($filename);
echo "</pre>\n</body>\n</html>\n";
?>
Zlib Funkcje
gzclose
(PHP 4, PHP 5)
gzclose — Close an open gz-file pointer
Opis
$zp
)Closes the given gz-file pointer.
Parametry
-
zp -
The gz-file pointer. It must be valid, and must point to a file successfully opened by gzopen().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 gzclose() example
<?php
$gz = gzopen('somefile.gz','w9');
gzputs ($gz, 'I was added to somefile.gz');
gzclose($gz);
?>
gzcompress
(PHP 4 >= 4.0.1, PHP 5)
gzcompress — Compress a string
Opis
$data
[, int $level = -1
] )This function compress the given string using the ZLIB data format.
For details on the ZLIB compression algorithm see the document "» ZLIB Compressed Data Format Specification version 3.3" (RFC 1950).
Informacja:
This is not the same as gzip compression, which includes some header data. See gzencode() for gzip compression.
Parametry
-
data -
The data to compress.
-
level -
The level of compression. Can be given as 0 for no compression up to 9 for maximum compression.
If -1 is used, the default compression of the zlib library is used which is 6.
Zwracane wartości
The compressed string or FALSE if an error occurred.
Przykłady
Przykład #1 gzcompress() example
<?php
$compressed = gzcompress('Compress me', 9);
echo $compressed;
?>
Zobacz też:
- gzdeflate() - Deflate a string
- gzinflate() - Inflate a deflated string
- gzuncompress() - Uncompress a compressed string
- gzencode() - Create a gzip compressed string
gzdecode
(No version information available, might only be in SVN)
gzdecode — Decodes a gzip compressed string
Opis
$data
[, int $length
] )
This function returns a decoded version of the input
data.
Parametry
-
data -
The data to decode, encoded by gzencode().
-
length -
The maximum length of data to decode.
Zwracane wartości
The decoded string, or FALSE if an error occurred.
gzdeflate
(PHP 4 >= 4.0.4, PHP 5)
gzdeflate — Deflate a string
Opis
$data
[, int $level = -1
] )This function compress the given string using the DEFLATE data format.
For details on the DEFLATE compression algorithm see the document "» DEFLATE Compressed Data Format Specification version 1.3" (RFC 1951).
Parametry
-
data -
The data to deflate.
-
level -
The level of compression. Can be given as 0 for no compression up to 9 for maximum compression. If not given, the default compression level will be the default compression level of the zlib library.
Zwracane wartości
The deflated string or FALSE if an error occurred.
Przykłady
Przykład #1 gzdeflate() example
<?php
$compressed = gzdeflate('Compress me', 9);
echo $compressed;
?>
Zobacz też:
- gzinflate() - Inflate a deflated string
- gzcompress() - Compress a string
- gzuncompress() - Uncompress a compressed string
- gzencode() - Create a gzip compressed string
gzencode
(PHP 4 >= 4.0.4, PHP 5)
gzencode — Create a gzip compressed string
Opis
$data
[, int $level = -1
[, int $encoding_mode = FORCE_GZIP
]] )
This function returns a compressed version of the input
data compatible with the output of the
gzip program.
For more information on the GZIP file format, see the document: » GZIP file format specification version 4.3 (RFC 1952).
Parametry
-
data -
The data to encode.
-
level -
The level of compression. Can be given as 0 for no compression up to 9 for maximum compression. If not given, the default compression level will be the default compression level of the zlib library.
-
encoding_mode -
The encoding mode. Can be
FORCE_GZIP(the default) orFORCE_DEFLATE.If you use
FORCE_DEFLATE, you get a standard zlib deflated string (inclusive zlib headers) after the gzip file header but without the trailing crc32 checksum.
Zwracane wartości
The encoded string, or FALSE if an error occurred.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.2.0 |
The encoding_mode parameter was added
|
Przykłady
The resulting data contains the appropriate headers and data structure to make a standard .gz file, e.g.:
Przykład #1 Creating a gzip file
<?php
$data = implode("", file("bigfile.txt"));
$gzdata = gzencode($data, 9);
$fp = fopen("bigfile.txt.gz", "w");
fwrite($fp, $gzdata);
fclose($fp);
?>
Zobacz też:
- gzdecode() - Decodes a gzip compressed string
- gzdeflate() - Deflate a string
- gzinflate() - Inflate a deflated string
- gzuncompress() - Uncompress a compressed string
- gzcompress() - Compress a string
gzeof
(PHP 4, PHP 5)
gzeof — Test for EOF on a gz-file pointer
Opis
$zp
)Tests the given GZ file pointer for EOF.
Parametry
-
zp -
The gz-file pointer. It must be valid, and must point to a file successfully opened by gzopen().
Zwracane wartości
Returns TRUE if the gz-file pointer is at EOF or an error occurs;
otherwise returns FALSE.
Przykłady
Przykład #1 gzeof() example
<?php
$gz = gzopen('somefile.gz', 'r');
while (!gzeof($gz)) {
echo gzgetc($gz);
}
gzclose($gz);
?>
gzfile
(PHP 4, PHP 5)
gzfile — Read entire gz-file into an array
Opis
$filename
[, int $use_include_path = 0
] )This function is identical to readgzfile(), except that it returns the file in an array.
Parametry
-
filename -
The file name.
-
use_include_path -
You can set this optional parameter to 1, if you want to search for the file in the include_path too.
Zwracane wartości
An array containing the file, one line per cell.
Przykłady
Przykład #1 gzfile() example
<?php
$lines = gzfile('somefile.gz');
foreach ($lines as $line) {
echo $line;
}
?>
gzgetc
(PHP 4, PHP 5)
gzgetc — Get character from gz-file pointer
Opis
$zp
)Returns a string containing a single (uncompressed) character read from the given gz-file pointer.
Parametry
-
zp -
The gz-file pointer. It must be valid, and must point to a file successfully opened by gzopen().
Zwracane wartości
The uncompressed character or FALSE on EOF (unlike gzeof()).
Przykłady
Przykład #1 gzgetc() example
<?php
$gz = gzopen('somefile.gz', 'r');
while (!gzeof($gz)) {
echo gzgetc($gz);
}
gzclose($gz);
?>
gzgets
(PHP 4, PHP 5)
gzgets — Get line from file pointer
Opis
$zp
, int $length
)Gets a (uncompressed) string of up to length - 1 bytes read from the given file pointer. Reading ends when length - 1 bytes have been read, on a newline, or on EOF (whichever comes first).
Parametry
-
zp -
The gz-file pointer. It must be valid, and must point to a file successfully opened by gzopen().
-
length -
The length of data to get.
Zwracane wartości
The uncompressed string, or FALSE on error.
Przykłady
Przykład #1 gzgets() example
<?php
$handle = gzopen('somefile.gz', 'r');
while (!gzeof($handle)) {
$buffer = gzgets($handle, 4096);
echo $buffer;
}
gzclose($handle);
?>
gzgetss
(PHP 4, PHP 5)
gzgetss — Get line from gz-file pointer and strip HTML tags
Opis
$zp
, int $length
[, string $allowable_tags
] )Identical to gzgets(), except that gzgetss() attempts to strip any HTML and PHP tags from the text it reads.
Parametry
-
zp -
The gz-file pointer. It must be valid, and must point to a file successfully opened by gzopen().
-
length -
The length of data to get.
-
allowable_tags -
You can use this optional parameter to specify tags which should not be stripped.
Zwracane wartości
The uncompressed and striped string, or FALSE on error.
Przykłady
Przykład #1 gzgetss() example
<?php
$handle = gzopen('somefile.gz', 'r');
while (!gzeof($handle)) {
$buffer = gzgetss($handle, 4096);
echo $buffer;
}
gzclose($handle);
?>
Zobacz też:
- gzopen() - Open gz-file
- gzgets() - Get line from file pointer
- strip_tags() - Strip HTML and PHP tags from a string
gzinflate
(PHP 4 >= 4.0.4, PHP 5)
gzinflate — Inflate a deflated string
Opis
$data
[, int $length = 0
] )This function inflate a deflated string.
Zwracane wartości
The original uncompressed data or FALSE on error.
The function will return an error if the uncompressed data is more than
32768 times the length of the compressed input data
or more than the optional parameter length.
Przykłady
Przykład #1 gzinflate() example
<?php
$compressed = gzdeflate('Compress me', 9);
$uncompressed = gzinflate($compressed);
echo $uncompressed;
?>
Zobacz też:
- gzdeflate() - Deflate a string
- gzcompress() - Compress a string
- gzuncompress() - Uncompress a compressed string
- gzencode() - Create a gzip compressed string
gzopen
(PHP 4, PHP 5)
gzopen — Open gz-file
Opis
$filename
, string $mode
[, int $use_include_path = 0
] )Opens a gzip (.gz) file for reading or writing.
gzopen() can be used to read a file which is not in gzip format; in this case gzread() will directly read from the file without decompression.
Parametry
-
filename -
The file name.
-
mode -
As in fopen() (rb or wb) but can also include a compression level (wb9) or a strategy: f for filtered data as in wb6f, h for Huffman only compression as in wb1h. (See the description of deflateInit2 in zlib.h for more information about the strategy parameter.)
-
use_include_path -
You can set this optional parameter to 1, if you want to search for the file in the include_path too.
Zwracane wartości
Returns a file pointer to the file opened, after that, everything you read from this file descriptor will be transparently decompressed and what you write gets compressed.
If the open fails, the function returns FALSE.
Przykłady
Przykład #1 gzopen() Example
<?php
$fp = gzopen("/tmp/file.gz", "r");
?>
gzpassthru
(PHP 4, PHP 5)
gzpassthru — Output all remaining data on a gz-file pointer
Opis
$zp
)Reads to EOF on the given gz-file pointer from the current position and writes the (uncompressed) results to standard output.
Informacja:
You may need to call gzrewind() to reset the file pointer to the beginning of the file if you have already written data to it.
If you just want to dump the contents of a file to the output buffer, without first modifying it or seeking to a particular offset, you may want to use the readgzfile() function, which saves you the gzopen() call.
Parametry
-
zp -
The gz-file pointer. It must be valid, and must point to a file successfully opened by gzopen().
Zwracane wartości
The number of uncompressed characters read from gz
and passed through to the input, or FALSE on error.
Przykłady
Przykład #1 gzpassthru() example
<?php
$fp = gzopen('file.gz', 'r');
gzpassthru($fp);
gzclose($fp);
?>
gzread
(PHP 4, PHP 5)
gzread — Binary-safe gz-file read
Opis
$zp
, int $length
)
gzread() reads up to length bytes
from the given gz-file pointer. Reading stops when
length (uncompressed) bytes have been read
or EOF is reached, whichever comes first.
Parametry
-
zp -
The gz-file pointer. It must be valid, and must point to a file successfully opened by gzopen().
-
length -
The number of bytes to read.
Zwracane wartości
The data that have been read.
Przykłady
Przykład #1 gzread() example
<?php
// get contents of a gz-file into a string
$filename = "/usr/local/something.txt.gz";
$zd = gzopen($filename, "r");
$contents = gzread($zd, 10000);
gzclose($zd);
?>
gzrewind
(PHP 4, PHP 5)
gzrewind — Rewind the position of a gz-file pointer
Opis
$zp
)Sets the file position indicator of the given gz-file pointer to the beginning of the file stream.
Parametry
-
zp -
The gz-file pointer. It must be valid, and must point to a file successfully opened by gzopen().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
gzseek
(PHP 4, PHP 5)
gzseek — Seek on a gz-file pointer
Opis
$zp
, int $offset
[, int $whence = SEEK_SET
] )Sets the file position indicator for the given file pointer to the given offset byte into the file stream. Equivalent to calling (in C) gzseek(zp, offset, SEEK_SET).
If the file is opened for reading, this function is emulated but can be extremely slow. If the file is opened for writing, only forward seeks are supported; gzseek() then compresses a sequence of zeroes up to the new starting position.
Parametry
-
zp -
The gz-file pointer. It must be valid, and must point to a file successfully opened by gzopen().
-
offset -
The seeked offset.
-
whence -
whencevalues are:SEEK_SET- Set position equal tooffsetbytes.SEEK_CUR- Set position to current location plusoffset.
If
whenceis not specified, it is assumed to beSEEK_SET.
Zwracane wartości
Upon success, returns 0; otherwise, returns -1. Note that seeking past EOF is not considered an error.
Przykłady
Przykład #1 gzseek() example
<?php
$gz = gzopen('somefile.gz', 'r');
gzseek($gz,2);
echo gzgetc($gz);
gzclose($gz);
?>
Zobacz też:
- gztell() - Tell gz-file pointer read/write position
- gzrewind() - Rewind the position of a gz-file pointer
gztell
(PHP 4, PHP 5)
gztell — Tell gz-file pointer read/write position
Opis
$zp
)Gets the position of the given file pointer; i.e., its offset into the uncompressed file stream.
Parametry
-
zp -
The gz-file pointer. It must be valid, and must point to a file successfully opened by gzopen().
Zwracane wartości
The position of the file pointer or FALSE if an error occurs.
Zobacz też:
- gzopen() - Open gz-file
- gzseek() - Seek on a gz-file pointer
- gzrewind() - Rewind the position of a gz-file pointer
gzuncompress
(PHP 4 >= 4.0.1, PHP 5)
gzuncompress — Uncompress a compressed string
Opis
$data
[, int $length = 0
] )This function uncompress a compressed string.
Zwracane wartości
The original uncompressed data or FALSE on error.
The function will return an error if the uncompressed data is more than
32768 times the length of the compressed input data
or more than the optional parameter length.
Przykłady
Przykład #1 gzuncompress() example
<?php
$compressed = gzcompress('Compress me', 9);
$uncompressed = gzuncompress($compressed);
echo $uncompressed;
?>
Zobacz też:
- gzcompress() - Compress a string
- gzinflate() - Inflate a deflated string
- gzdeflate() - Deflate a string
- gzencode() - Create a gzip compressed string
gzwrite
(PHP 4, PHP 5)
gzwrite — Binary-safe gz-file write
Opis
$zp
, string $string
[, int $length
] )
gzwrite() writes the contents of
string to the given gz-file.
Parametry
-
zp -
The gz-file pointer. It must be valid, and must point to a file successfully opened by gzopen().
-
string -
The string to write.
-
length -
The number of uncompressed bytes to write. If supplied, writing will stop after
length(uncompressed) bytes have been written or the end ofstringis reached, whichever comes first.Informacja:
Note that if the
lengthargument is given, then the magic_quotes_runtime configuration option will be ignored and no slashes will be stripped fromstring.
Zwracane wartości
Returns the number of (uncompressed) bytes written to the given gz-file stream.
Przykłady
Przykład #1 gzwrite() example
<?php
$string = 'Some information to compress';
$gz = gzopen('somefile.gz','w9');
gzwrite($gz, $string);
gzclose($gz);
?>
readgzfile
(PHP 4, PHP 5)
readgzfile — Output a gz-file
Opis
$filename
[, int $use_include_path = 0
] )Reads a file, decompresses it and writes it to standard output.
readgzfile() can be used to read a file which is not in gzip format; in this case readgzfile() will directly read from the file without decompression.
Parametry
-
filename -
The file name. This file will be opened from the filesystem and its contents written to standard output.
-
use_include_path -
You can set this optional parameter to 1, if you want to search for the file in the include_path too.
Zwracane wartości
Returns the number of (uncompressed) bytes read from the file. If
an error occurs, FALSE is returned and unless the function was
called as @readgzfile, an error message is
printed.
Zobacz też:
- gzpassthru() - Output all remaining data on a gz-file pointer
- gzfile() - Read entire gz-file into an array
- gzopen() - Open gz-file
zlib_decode
(PHP 5 >= 5.4.0)
zlib_decode — Uncompress any raw/gzip/zlib encoded data
Opis
$data
[, string $max_decoded_len
] )Uncompress any raw/gzip/zlib encoded data.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
data -
-
max_decoded_len -
Zwracane wartości
Zobacz też:
- zlib_encode() - Compress data with the specified encoding
zlib_encode
(PHP 5 >= 5.4.0)
zlib_encode — Compress data with the specified encoding
Opis
$data
, string $encoding
[, string $level = -1
] )Compress data with the specified encoding.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
data -
-
encoding -
-
level -
Zwracane wartości
Zobacz też:
- zlib_decode() - Uncompress any raw/gzip/zlib encoded data
zlib_get_coding_type
(PHP 4 >= 4.3.2, PHP 5)
zlib_get_coding_type — Returns the coding type used for output compression
Opis
Returns the coding type used for output compression.
Zwracane wartości
Possible return values are gzip, deflate,
or FALSE.
Spis treści
- gzclose — Close an open gz-file pointer
- gzcompress — Compress a string
- gzdecode — Decodes a gzip compressed string
- gzdeflate — Deflate a string
- gzencode — Create a gzip compressed string
- gzeof — Test for EOF on a gz-file pointer
- gzfile — Read entire gz-file into an array
- gzgetc — Get character from gz-file pointer
- gzgets — Get line from file pointer
- gzgetss — Get line from gz-file pointer and strip HTML tags
- gzinflate — Inflate a deflated string
- gzopen — Open gz-file
- gzpassthru — Output all remaining data on a gz-file pointer
- gzputs — Alias dla gzwrite
- gzread — Binary-safe gz-file read
- gzrewind — Rewind the position of a gz-file pointer
- gzseek — Seek on a gz-file pointer
- gztell — Tell gz-file pointer read/write position
- gzuncompress — Uncompress a compressed string
- gzwrite — Binary-safe gz-file write
- readgzfile — Output a gz-file
- zlib_decode — Uncompress any raw/gzip/zlib encoded data
- zlib_encode — Compress data with the specified encoding
- zlib_get_coding_type — Returns the coding type used for output compression
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Przykłady
- Zlib Funkcje
- gzclose — Close an open gz-file pointer
- gzcompress — Compress a string
- gzdecode — Decodes a gzip compressed string
- gzdeflate — Deflate a string
- gzencode — Create a gzip compressed string
- gzeof — Test for EOF on a gz-file pointer
- gzfile — Read entire gz-file into an array
- gzgetc — Get character from gz-file pointer
- gzgets — Get line from file pointer
- gzgetss — Get line from gz-file pointer and strip HTML tags
- gzinflate — Inflate a deflated string
- gzopen — Open gz-file
- gzpassthru — Output all remaining data on a gz-file pointer
- gzputs — Alias dla gzwrite
- gzread — Binary-safe gz-file read
- gzrewind — Rewind the position of a gz-file pointer
- gzseek — Seek on a gz-file pointer
- gztell — Tell gz-file pointer read/write position
- gzuncompress — Uncompress a compressed string
- gzwrite — Binary-safe gz-file write
- readgzfile — Output a gz-file
- zlib_decode — Uncompress any raw/gzip/zlib encoded data
- zlib_encode — Compress data with the specified encoding
- zlib_get_coding_type — Returns the coding type used for output compression
- Bzip2
- LZF
- Phar
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Using Phar Archives
- Creating Phar Archives
- What makes a phar a phar and not a tar or a zip?
- Phar — The Phar class
- PharData — The PharData class
- PharFileInfo — The PharFileInfo class
- PharException — The PharException class
- Rar — Rar Archiving
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Przykłady
- Rar Funkcje
- RarArchive — The RarArchive class
- RarEntry — The RarEntry class
- RarException — The RarException class
- Zip
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Przykłady
- ZipArchive — The ZipArchive class
- Zip Funkcje
- Zlib — Zlib Compression
Przetwarzanie transakcji kartami płatniczymi
MCVE (Monetra) Payment
Wstęp
These functions interface the MCVE (Monetra) API (libmonetra, formerly known as libmcve), allowing you to work directly with MCVE/Monetra from your PHP scripts. MCVE/Monetra is Main Street Softworks' solution to direct credit/debit/gift card processing for Linux/Unix/MacOSX/Windows ( » http://www.mainstreetsoftworks.com/ ). It lets you directly address the credit card clearing houses via your *nix box, modem and/or internet connection (bypassing the need for an additional service such as Authorize.Net or Pay Flow Pro). Using the MCVE/Monetra module for PHP, you can process credit cards directly through MCVE/Monetra via your PHP scripts. The following references will outline the process.
Informacja:
MCVE/Monetra is the replacement for RedHat's CCVS. They contracted with RedHat in late 2001 to migrate all existing clientele to the MCVE platform.
Informacja:
To rozszerzenie zostało przeniesione do repozytorium » PECL i nie jest rozprowadzane z PHP od wersji 5.1.0.
Informacja: To rozszerzenie nie jest dostępne na platformie Windows.
Instalacja/Konfiguracja
Spis treści
Wymagania
The LibMonetra (formerly libmcve) library.
Instalacja
To rozszerzenie » PECL nie jest dołączane do PHP.
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/mcve.
DLL z tym rozszerzeniem PECL można pobrać zarówno ze strony » PHP Downloads lub z » http://pecl4win.php.net/
If installing without specifying the libmonetra path, PHP will attempt to look in the default LibMonetra Install location (/usr/local). If Monetra (MCVE) is in a non-standard location, run configure with: --with-mcve=$mcve_path , where $mcve_path is the path to your MCVE/Monetra installation. Please note that MCVE/Monetra support requires that $mcve_path/lib and $mcve_path/include exist, and include mcve.h or monetra.h under the include directory and libmcve.so and/or libmcve.a and/or libmonetra.so and/or libmonetra.a under the lib directory.
Since MCVE/Monetra has true server/client separation, there are no additional requirements for running PHP with MCVE support. To test your MCVE/Monetra extension in PHP, you may connect to testbox.monetra.com on port 8333 for IP, or port 8444 for SSL using the MCVE/Monetra PHP API. Use 'vitale' for your username, and 'test' for your password. Additional information about test facilities are available at » http://www.mainstreetsoftworks.com/.
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
MCVE Funkcje
Zobacz też:
Additional documentation about MCVE/Monetra's PHP API can be found at » http://www.mainstreetsoftworks.com/documentation.html. Main Street's documentation is complete and should be the primary reference for functions.
m_checkstatus
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_checkstatus — Check to see if a transaction has completed
Opis
$conn
, int $identifier
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_connect
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_connect — Establish the connection to MCVE
Opis
$conn
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_connectionerror
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_connectionerror — Get a textual representation of why a connection failed
Opis
$conn
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_deletetrans
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_deletetrans — Delete specified transaction from MCVE_CONN structure
Opis
$conn
, int $identifier
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_destroyconn
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_destroyconn — Destroy the connection and MCVE_CONN structure
Opis
$conn
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Returns TRUE.
m_destroyengine
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_destroyengine — Free memory associated with IP/SSL connectivity
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
Zwracane wartości
Nie jest zwracana żadna wartość.
m_getcell
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_getcell — Get a specific cell from a comma delimited response by column name
Opis
$conn
, int $identifier
, string $column
, int $row
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_getcellbynum
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_getcellbynum — Get a specific cell from a comma delimited response by column number
Opis
$conn
, int $identifier
, int $column
, int $row
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_getcommadelimited
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_getcommadelimited — Get the RAW comma delimited data returned from MCVE
Opis
$conn
, int $identifier
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_getheader
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_getheader — Get the name of the column in a comma-delimited response
Opis
$conn
, int $identifier
, int $column_num
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_initconn
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_initconn — Create and initialize an MCVE_CONN structure
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Returns an MCVE_CONN resource.
m_initengine
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_initengine — Ready the client for IP/SSL Communication
Opis
$location
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
location -
Zwracane wartości
m_iscommadelimited
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_iscommadelimited — Checks to see if response is comma delimited
Opis
$conn
, int $identifier
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_maxconntimeout
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_maxconntimeout — The maximum amount of time the API will attempt a connection to MCVE
Opis
$conn
, int $secs
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_monitor
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_monitor — Perform communication with MCVE (send/receive data) Non-blocking
Opis
$conn
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_numcolumns
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_numcolumns — Number of columns returned in a comma delimited response
Opis
$conn
, int $identifier
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_numrows
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_numrows — Number of rows returned in a comma delimited response
Opis
$conn
, int $identifier
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_parsecommadelimited
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_parsecommadelimited — Parse the comma delimited response so m_getcell, etc will work
Opis
$conn
, int $identifier
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_responsekeys
(PHP 5 >= 5.0.5, PECL mcve >= 1.0.0)
m_responsekeys — Returns array of strings which represents the keys that can be used for response parameters on this transaction
Opis
$conn
, int $identifier
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_responseparam
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_responseparam — Get a custom response parameter
Opis
$conn
, int $identifier
, string $key
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_returnstatus
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_returnstatus — Check to see if the transaction was successful
Opis
$conn
, int $identifier
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_setblocking
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_setblocking — Set blocking/non-blocking mode for connection
Opis
$conn
, int $tf
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_setdropfile
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_setdropfile — Set the connection method to Drop-File
Opis
$conn
, string $directory
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_setip
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_setip — Set the connection method to IP
Opis
$conn
, string $host
, int $port
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_setssl_cafile
(PHP 5 >= 5.0.5, PECL mcve >= 1.0.0)
m_setssl_cafile — Set SSL CA (Certificate Authority) file for verification of server certificate
Opis
$conn
, string $cafile
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_setssl_files
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_setssl_files — Set certificate key files and certificates if server requires client certificate verification
Opis
$conn
, string $sslkeyfile
, string $sslcertfile
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_setssl
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_setssl — Set the connection method to SSL
Opis
$conn
, string $host
, int $port
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_settimeout
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_settimeout — Set maximum transaction time (per trans)
Opis
$conn
, int $seconds
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_sslcert_gen_hash
(PECL mcve >= 5.2.0)
m_sslcert_gen_hash — Generate hash for SSL client certificate verification
Opis
$filename
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
filename -
Zwracane wartości
m_transactionssent
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_transactionssent — Check to see if outgoing buffer is clear
Opis
$conn
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_transinqueue
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_transinqueue — Number of transactions in client-queue
Opis
$conn
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_transkeyval
(PHP 5 >= 5.0.5, PECL mcve >= 1.0.0)
m_transkeyval — Add key/value pair to a transaction. Replaces deprecated transparam()
Opis
$conn
, int $identifier
, string $key
, string $value
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_transnew
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_transnew — Start a new transaction
Opis
$conn
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_transsend
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_transsend — Finalize and send the transaction
Opis
$conn
, int $identifier
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_uwait
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_uwait — Wait x microsecs
Opis
$microsecs
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
microsecs -
Zwracane wartości
m_validateidentifier
(PHP 5 >= 5.0.5, PECL mcve >= 1.0.0)
m_validateidentifier — Whether or not to validate the passed identifier on any transaction it is passed to
Opis
$conn
, int $tf
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_verifyconnection
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_verifyconnection — Set whether or not to PING upon connect to verify connection
Opis
$conn
, int $tf
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
m_verifysslcert
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_verifysslcert — Set whether or not to verify the server ssl certificate
Opis
$conn
, int $tf
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Spis treści
- m_checkstatus — Check to see if a transaction has completed
- m_completeauthorizations — Number of complete authorizations in queue, returning an array of their identifiers
- m_connect — Establish the connection to MCVE
- m_connectionerror — Get a textual representation of why a connection failed
- m_deletetrans — Delete specified transaction from MCVE_CONN structure
- m_destroyconn — Destroy the connection and MCVE_CONN structure
- m_destroyengine — Free memory associated with IP/SSL connectivity
- m_getcell — Get a specific cell from a comma delimited response by column name
- m_getcellbynum — Get a specific cell from a comma delimited response by column number
- m_getcommadelimited — Get the RAW comma delimited data returned from MCVE
- m_getheader — Get the name of the column in a comma-delimited response
- m_initconn — Create and initialize an MCVE_CONN structure
- m_initengine — Ready the client for IP/SSL Communication
- m_iscommadelimited — Checks to see if response is comma delimited
- m_maxconntimeout — The maximum amount of time the API will attempt a connection to MCVE
- m_monitor — Perform communication with MCVE (send/receive data) Non-blocking
- m_numcolumns — Number of columns returned in a comma delimited response
- m_numrows — Number of rows returned in a comma delimited response
- m_parsecommadelimited — Parse the comma delimited response so m_getcell, etc will work
- m_responsekeys — Returns array of strings which represents the keys that can be used for response parameters on this transaction
- m_responseparam — Get a custom response parameter
- m_returnstatus — Check to see if the transaction was successful
- m_setblocking — Set blocking/non-blocking mode for connection
- m_setdropfile — Set the connection method to Drop-File
- m_setip — Set the connection method to IP
- m_setssl_cafile — Set SSL CA (Certificate Authority) file for verification of server certificate
- m_setssl_files — Set certificate key files and certificates if server requires client certificate verification
- m_setssl — Set the connection method to SSL
- m_settimeout — Set maximum transaction time (per trans)
- m_sslcert_gen_hash — Generate hash for SSL client certificate verification
- m_transactionssent — Check to see if outgoing buffer is clear
- m_transinqueue — Number of transactions in client-queue
- m_transkeyval — Add key/value pair to a transaction. Replaces deprecated transparam()
- m_transnew — Start a new transaction
- m_transsend — Finalize and send the transaction
- m_uwait — Wait x microsecs
- m_validateidentifier — Whether or not to validate the passed identifier on any transaction it is passed to
- m_verifyconnection — Set whether or not to PING upon connect to verify connection
- m_verifysslcert — Set whether or not to verify the server ssl certificate
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- MCVE Funkcje
- m_checkstatus — Check to see if a transaction has completed
- m_completeauthorizations — Number of complete authorizations in queue, returning an array of their identifiers
- m_connect — Establish the connection to MCVE
- m_connectionerror — Get a textual representation of why a connection failed
- m_deletetrans — Delete specified transaction from MCVE_CONN structure
- m_destroyconn — Destroy the connection and MCVE_CONN structure
- m_destroyengine — Free memory associated with IP/SSL connectivity
- m_getcell — Get a specific cell from a comma delimited response by column name
- m_getcellbynum — Get a specific cell from a comma delimited response by column number
- m_getcommadelimited — Get the RAW comma delimited data returned from MCVE
- m_getheader — Get the name of the column in a comma-delimited response
- m_initconn — Create and initialize an MCVE_CONN structure
- m_initengine — Ready the client for IP/SSL Communication
- m_iscommadelimited — Checks to see if response is comma delimited
- m_maxconntimeout — The maximum amount of time the API will attempt a connection to MCVE
- m_monitor — Perform communication with MCVE (send/receive data) Non-blocking
- m_numcolumns — Number of columns returned in a comma delimited response
- m_numrows — Number of rows returned in a comma delimited response
- m_parsecommadelimited — Parse the comma delimited response so m_getcell, etc will work
- m_responsekeys — Returns array of strings which represents the keys that can be used for response parameters on this transaction
- m_responseparam — Get a custom response parameter
- m_returnstatus — Check to see if the transaction was successful
- m_setblocking — Set blocking/non-blocking mode for connection
- m_setdropfile — Set the connection method to Drop-File
- m_setip — Set the connection method to IP
- m_setssl_cafile — Set SSL CA (Certificate Authority) file for verification of server certificate
- m_setssl_files — Set certificate key files and certificates if server requires client certificate verification
- m_setssl — Set the connection method to SSL
- m_settimeout — Set maximum transaction time (per trans)
- m_sslcert_gen_hash — Generate hash for SSL client certificate verification
- m_transactionssent — Check to see if outgoing buffer is clear
- m_transinqueue — Number of transactions in client-queue
- m_transkeyval — Add key/value pair to a transaction. Replaces deprecated transparam()
- m_transnew — Start a new transaction
- m_transsend — Finalize and send the transaction
- m_uwait — Wait x microsecs
- m_validateidentifier — Whether or not to validate the passed identifier on any transaction it is passed to
- m_verifyconnection — Set whether or not to PING upon connect to verify connection
- m_verifysslcert — Set whether or not to verify the server ssl certificate
SPPLUS Payment System
Wstęp
This extension gives you the possibility to use the » SPPLUS Payment System of the Caisse d'Epargne (a French Bank).
Informacja: To rozszerzenie nie jest dostępne na platformie Windows.
Refer to the README files in kit_php's source distribution for configuration details.
Instalacja/Konfiguracja
Spis treści
Wymagania
Informacja: You need at least PHP 4.1.0 and SPPLUS v.3
Informacja: You will need to get the new kit_php for spplus. Feel free to contact the maintainer if you can't get it.
Instalacja
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/spplus.
DLL z tym rozszerzeniem PECL można pobrać zarówno ze strony » PHP Downloads lub z » http://pecl4win.php.net/
Informacja:
PHP 4.3.0 or greater is required for the compression to work.
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
To rozszerzenie nie posiada żadnych stałych.
SPPLUS Funkcje
calcul_hmac
(PECL spplus >= 1.0.0)
calcul_hmac — Obtain a hmac key (needs 8 arguments)
Opis
$clent
, string $siretcode
, string $price
, string $reference
, string $validity
, string $taxation
, string $devise
, string $language
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
calculhmac
(PECL spplus >= 1.0.0)
calculhmac — Obtain a hmac key (needs 2 arguments)
Opis
$clent
, string $data
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
nthmac
(PECL spplus >= 1.0.0)
nthmac — Obtain a nthmac key (needs 2 arguments)
Opis
$clent
, string $data
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
signeurlpaiement
(PECL spplus >= 1.0.0)
signeurlpaiement — Obtain the payment url (needs 2 arguments)
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Spis treści
- calcul_hmac — Obtain a hmac key (needs 8 arguments)
- calculhmac — Obtain a hmac key (needs 2 arguments)
- nthmac — Obtain a nthmac key (needs 2 arguments)
- signeurlpaiement — Obtain the payment url (needs 2 arguments)
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- SPPLUS Funkcje
- calcul_hmac — Obtain a hmac key (needs 8 arguments)
- calculhmac — Obtain a hmac key (needs 2 arguments)
- nthmac — Obtain a nthmac key (needs 2 arguments)
- signeurlpaiement — Obtain the payment url (needs 2 arguments)
Rozszerzenia kryptograficzne
Cracklib
Wstęp
These functions allow you to use the CrackLib library to test the 'strength' of a password. The 'strength' of a password is tested by that checks length, use of upper and lower case and checked against the specified CrackLib dictionary. CrackLib will also give helpful diagnostic messages that will help 'strengthen' the password.
Informacja:
To rozszerzenie zostało przeniesione do repozytorium » PECL i nie jest rozprowadzane z PHP od wersji 5.0.0.
Instalacja/Konfiguracja
Spis treści
Wymagania
More information regarding CrackLib along with the library can be found at » http://sourceforge.net/projects/cracklib.
Instalacja
To rozszerzenie » PECL nie jest dołączane do PHP. Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/crack.
W PHP 4 to rozszerzenie PECL można znaleźć w podkatalogu ext/ źródeł PHP lub pod znajdującym się wyżej odnośnikiem PECL. Aby zbudować PHP z obsługą Crack należy podać opcję --with-crack[=DIR] wywołania configure.
Użytkownicy Windows mogą włączyć obsługe funkcji Crack, poprzez dodanie php_crack.dll w pliku php.ini. W PHP 4 ten DLL znajduje się w podkatalogu extensions/ binarnej dystrybucji PHP dla Windows. DLL z tym rozszerzeniem PECL można pobrać zarówno ze strony » PHP Downloads lub z » http://pecl4win.php.net/
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślna wartość | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| crack.default_dictionary | NULL | PHP_INI_PERDIR | PHP_INI_SYSTEM w crack <= 0.2. Dostępne od PHP 4.0.5. Usunięte w PHP 5.0.0. |
Typy zasobów
The CrackLib extension defines a dictionary resource identifier returned by crack_opendict().
Stałe predefiniowane
To rozszerzenie nie posiada żadnych stałych.
Przykłady
This example shows how to open a CrackLib dictionary, test a given password, retrieve any diagnostic messages, and close the dictionary.
Przykład #1 CrackLib example
<?php
// Open CrackLib Dictionary
$dictionary = crack_opendict('/usr/local/lib/pw_dict')
or die('Unable to open CrackLib dictionary');
// Perform password check
$check = crack_check($dictionary, 'gx9A2s0x');
// Retrieve messages
$diag = crack_getlastmessage();
echo $diag; // 'strong password'
// Close dictionary
crack_closedict($dictionary);
?>
Informacja:
If crack_check() returns
TRUE, crack_getlastmessage() will return 'strong password'.
Funkcje Crack
crack_check
(PECL crack >= 0.1)
crack_check — Rozpoczyna sprawdzanie podanego hasła
Opis
$dictionary
, string $password
)$password
)Rozpoczyna sprawdzanie podanego hasła według zadanego słownika.
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Parametry
-
dictionary -
Biblioteka słownika. Jeśli nie podana, zostanie wykorzystana ostatnio użyta.
-
password -
Sprawdzane hasło.
Zwracane wartości
Zwraca TRUE jeśli password jest 'silne', lub
FALSE w przypadku 'słabego' hasła.
crack_closedict
(PECL crack >= 0.1)
crack_closedict — Zamyka otwarty słownik CrackLib
Opis
$dictionary
] )
crack_closedict() zamyka wskaźnik
dictionary słownika.
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Parametry
-
dictionary -
Słownik do zamknięcia. Jeśli parametr ten nie zostanie podany zamyka aktualnie wykorzystywany słownik.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
crack_getlastmessage
(PECL crack >= 0.1)
crack_getlastmessage — Zwraca wiadomość ostatniego wykonanego testu hasła
Opis
crack_getlastmessage() zwraca wiadomość ostatniego wykonanego testu hasła.
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Zwracane wartości
Wiadomość ostatniego testu lub FALSE jeśli żaden test nie został
wykonany do tej pory.
Zwracana wiadoość jest jedną z:
- it's WAY too short (jest zdecydowanie za krótkie)
- it is too short (jest za krótkie)
- it does not contain enough DIFFERENT characters (nie zawiera wystarczająco różnych znaków)
- it is all whitespace (zawiera same białe znaki)
- it is too simplistic/systematic (jest zbyt proste/systematyczne)
- it looks like a National Insurance number. (wygląda jak numer ubezpieczenia w USA)
- it is based on a dictionary word (bazuje na słowie ze słownika)
- it is based on a (reversed) dictionary word (bazuje na odwróconym słowie ze słownika)
- strong password (mocne/dobre hasło)
crack_opendict
(PECL crack >= 0.1)
crack_opendict — Otwiera nowy słownik CrackLib
Opis
$dictionary
)
crack_opendict() otwiera słownik
dictionary do użytku przez
crack_check().
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Informacja:
Tylko jeden słownik może być otwarty w tej samej chwili.
Parametry
-
dictionary -
Ścieżka do słownika CrackLib
Zwracane wartości
Zwraca wskaźnik zasobów słownika w przypadku sukcesu lub FALSE w przypadku niepowodzenia.
Zobacz też:
- crack_check() - Rozpoczyna sprawdzanie podanego hasła
- crack_closedict() - Zamyka otwarty słownik CrackLib
Spis treści
- crack_check — Rozpoczyna sprawdzanie podanego hasła
- crack_closedict — Zamyka otwarty słownik CrackLib
- crack_getlastmessage — Zwraca wiadomość ostatniego wykonanego testu hasła
- crack_opendict — Otwiera nowy słownik CrackLib
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Przykłady
- Funkcje Crack
- crack_check — Rozpoczyna sprawdzanie podanego hasła
- crack_closedict — Zamyka otwarty słownik CrackLib
- crack_getlastmessage — Zwraca wiadomość ostatniego wykonanego testu hasła
- crack_opendict — Otwiera nowy słownik CrackLib
HASH Message Digest Framework
Wstęp
Message Digest (hash) engine. Allows direct or incremental processing of arbitrary length messages using a variety of hashing algorithms.
Instalacja/Konfiguracja
Spis treści
Wymagania
The Hash extension requires no external libraries and is enabled by default as of PHP 5.1.2. It may be explicitly disabled by using the --disable-hash switch to configure. Earlier versions of PHP may incorporate the Hash extension by installing the » PECL module.
Instalacja
By używać tych funkcji, nie trzeba niczego instalować. Są one częścią jądra PHP.
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
-
HASH_HMAC(integer) - Optional flag for hash_init(). Indicates that the HMAC digest-keying algorithm should be applied to the current hashing context.
Hash Funkcje
hash_algos
(PHP 5 >= 5.1.2, PECL hash >= 1.1)
hash_algos — Return a list of registered hashing algorithms
Opis
Zwracane wartości
Returns a numerically indexed array containing the list of supported hashing algorithms.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.4.0 | Support for joaat, fnv132 and fnv164 was added. Support for Salsa10 and Salsa20 was removed. |
| 5.3.0 | Support for md2, ripemd256, ripemd320, salsa10, salsa20, snefru256 and sha224 was added |
Przykłady
Przykład #1 hash_algos() example
As of PHP 5.3.0, hash_algos() will return the following list of algorithm names.
<?php
print_r(hash_algos());
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[0] => md2
[1] => md4
[2] => md5
[3] => sha1
[4] => sha224
[5] => sha256
[6] => sha384
[7] => sha512
[8] => ripemd128
[9] => ripemd160
[10] => ripemd256
[11] => ripemd320
[12] => whirlpool
[13] => tiger128,3
[14] => tiger160,3
[15] => tiger192,3
[16] => tiger128,4
[17] => tiger160,4
[18] => tiger192,4
[19] => snefru
[20] => snefru256
[21] => gost
[22] => adler32
[23] => crc32
[24] => crc32b
[25] => salsa10
[26] => salsa20
[27] => haval128,3
[28] => haval160,3
[29] => haval192,3
[30] => haval224,3
[31] => haval256,3
[32] => haval128,4
[33] => haval160,4
[34] => haval192,4
[35] => haval224,4
[36] => haval256,4
[37] => haval128,5
[38] => haval160,5
[39] => haval192,5
[40] => haval224,5
[41] => haval256,5
)
hash_copy
(PHP 5 >= 5.3.0)
hash_copy — Copy hashing context
Opis
$context
)Zwracane wartości
Returns a copy of Hashing Context resource.
Przykłady
Przykład #1 hash_copy() example
<?php
$context = hash_init("md5");
hash_update($context, "data");
/* copy context to be able to continue using it */
$copy_context = hash_copy($context);
echo hash_final($context), "\n";
hash_update($copy_context, "data");
echo hash_final($copy_context), "\n";
?>
Powyższy przykład wyświetli:
8d777f385d3dfec8815d20f7496026dc 511ae0b1c13f95e5f08f1a0dd3da3d93
hash_file
(PHP 5 >= 5.1.2, PECL hash >= 1.1)
hash_file — Generate a hash value using the contents of a given file
Opis
$algo
, string $filename
[, bool $raw_output = false
] )Parametry
-
algo -
Name of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..)
-
filename -
URL describing location of file to be hashed; Supports fopen wrappers.
-
raw_output -
When set to
TRUE, outputs raw binary data.FALSEoutputs lowercase hexits.
Zwracane wartości
Returns a string containing the calculated message digest as lowercase hexits
unless raw_output is set to true in which case the raw
binary representation of the message digest is returned.
Przykłady
Przykład #1 Using hash_file()
<?php
/* Create a file to calculate hash of */
file_put_contents('example.txt', 'The quick brown fox jumped over the lazy dog.');
echo hash_file('md5', 'example.txt');
?>
Powyższy przykład wyświetli:
5c6ffbdd40d9556b73a21e63c3e0e904
Zobacz też:
- hash() - Generate a hash value (message digest)
- hash_hmac_file() - Generate a keyed hash value using the HMAC method and the contents of a given file
- hash_update_file() - Pump data into an active hashing context from a file
- md5_file() - Calculates the md5 hash of a given file
- sha1_file() - Calculate the sha1 hash of a file
hash_final
(PHP 5 >= 5.1.2, PECL hash >= 1.1)
hash_final — Finalize an incremental hash and return resulting digest
Opis
$context
[, bool $raw_output = false
] )Parametry
-
context -
Hashing context returned by hash_init().
-
raw_output -
When set to
TRUE, outputs raw binary data.FALSEoutputs lowercase hexits.
Zwracane wartości
Returns a string containing the calculated message digest as lowercase hexits
unless raw_output is set to true in which case the raw
binary representation of the message digest is returned.
Przykłady
Przykład #1 hash_final() example
<?php
$ctx = hash_init('sha1');
hash_update($ctx, 'The quick brown fox jumped over the lazy dog.');
echo hash_final($ctx);
?>
Powyższy przykład wyświetli:
c0854fb9fb03c41cce3802cb0d220529e6eef94e
Zobacz też:
- hash_init() - Initialize an incremental hashing context
- hash_update() - Pump data into an active hashing context
- hash_update_stream() - Pump data into an active hashing context from an open stream
- hash_update_file() - Pump data into an active hashing context from a file
hash_hmac_file
(PHP 5 >= 5.1.2, PECL hash >= 1.1)
hash_hmac_file — Generate a keyed hash value using the HMAC method and the contents of a given file
Opis
$algo
, string $filename
, string $key
[, bool $raw_output = false
] )Parametry
-
algo -
Name of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..) See hash_algos() for a list of supported algorithms.
-
filename -
URL describing location of file to be hashed; Supports fopen wrappers.
-
key -
Shared secret key used for generating the HMAC variant of the message digest.
-
raw_output -
When set to
TRUE, outputs raw binary data.FALSEoutputs lowercase hexits.
Zwracane wartości
Returns a string containing the calculated message digest as lowercase hexits
unless raw_output is set to true in which case the raw
binary representation of the message digest is returned.
Przykłady
Przykład #1 hash_hmac_file() example
<?php
/* Create a file to calculate hash of */
file_put_contents('example.txt', 'The quick brown fox jumped over the lazy dog.');
echo hash_hmac_file('md5', 'example.txt', 'secret');
?>
Powyższy przykład wyświetli:
7eb2b5c37443418fc77c136dd20e859c
Zobacz też:
- hash_algos() - Return a list of registered hashing algorithms
- hash_hmac() - Generate a keyed hash value using the HMAC method
- hash_file() - Generate a hash value using the contents of a given file
hash_hmac
(PHP 5 >= 5.1.2, PECL hash >= 1.1)
hash_hmac — Generate a keyed hash value using the HMAC method
Opis
$algo
, string $data
, string $key
[, bool $raw_output = false
] )Parametry
-
algo -
Name of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..) See hash_algos() for a list of supported algorithms.
-
data -
Message to be hashed.
-
key -
Shared secret key used for generating the HMAC variant of the message digest.
-
raw_output -
When set to
TRUE, outputs raw binary data.FALSEoutputs lowercase hexits.
Zwracane wartości
Returns a string containing the calculated message digest as lowercase hexits
unless raw_output is set to true in which case the raw
binary representation of the message digest is returned.
Przykłady
Przykład #1 hash_hmac() example
<?php
echo hash_hmac('ripemd160', 'The quick brown fox jumped over the lazy dog.', 'secret');
?>
Powyższy przykład wyświetli:
b8e7ae12510bdfb1812e463a7f086122cf37e4f7
Zobacz też:
- hash() - Generate a hash value (message digest)
- hash_algos() - Return a list of registered hashing algorithms
- hash_init() - Initialize an incremental hashing context
- hash_hmac_file() - Generate a keyed hash value using the HMAC method and the contents of a given file
hash_init
(PHP 5 >= 5.1.2, PECL hash >= 1.1)
hash_init — Initialize an incremental hashing context
Opis
$algo
[, int $options = 0
[, string $key = NULL
]] )Parametry
-
algo -
Name of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..)
-
options -
Optional settings for hash generation, currently supports only one option:
HASH_HMAC. When specified, thekeymust be specified. -
key -
When
HASH_HMACis specified foroptions, a shared secret key to be used with the HMAC hashing method must be supplied in this parameter.
Zwracane wartości
Returns a Hashing Context resource for use with hash_update(), hash_update_stream(), hash_update_file(), and hash_final().
Przykłady
Przykład #1 Incremental hashing example
<?php
$ctx = hash_init('md5');
hash_update($ctx, 'The quick brown fox ');
hash_update($ctx, 'jumped over the lazy dog.');
echo hash_final($ctx);
?>
Powyższy przykład wyświetli:
5c6ffbdd40d9556b73a21e63c3e0e904
Zobacz też:
- hash() - Generate a hash value (message digest)
- hash_file() - Generate a hash value using the contents of a given file
- hash_hmac() - Generate a keyed hash value using the HMAC method
- hash_hmac_file() - Generate a keyed hash value using the HMAC method and the contents of a given file
hash_update_file
(PHP 5 >= 5.1.2, PECL hash >= 1.1)
hash_update_file — Pump data into an active hashing context from a file
Opis
$context
, string $filename
[, resource $context = NULL
] )Parametry
-
context -
Hashing context returned by hash_init().
-
filename -
URL describing location of file to be hashed; Supports fopen wrappers.
-
context -
Stream context as returned by stream_context_create().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- hash_init() - Initialize an incremental hashing context
- hash_update() - Pump data into an active hashing context
- hash_update_stream() - Pump data into an active hashing context from an open stream
- hash_final() - Finalize an incremental hash and return resulting digest
- hash() - Generate a hash value (message digest)
- hash_file() - Generate a hash value using the contents of a given file
hash_update_stream
(PHP 5 >= 5.1.2, PECL hash >= 1.1)
hash_update_stream — Pump data into an active hashing context from an open stream
Opis
$context
, resource $handle
[, int $length = -1
] )Parametry
-
context -
Hashing context returned by hash_init().
-
handle -
Open file handle as returned by any stream creation function.
-
length -
Maximum number of characters to copy from
handleinto the hashing context.
Zwracane wartości
Actual number of bytes added to the hashing context from handle.
Przykłady
Przykład #1 hash_update_stream() example
<?php
$fp = tmpfile();
fwrite($fp, 'The quick brown fox jumped over the lazy dog.');
rewind($fp);
$ctx = hash_init('md5');
hash_update_stream($ctx, $fp);
echo hash_final($ctx);
?>
Powyższy przykład wyświetli:
5c6ffbdd40d9556b73a21e63c3e0e904
Zobacz też:
- hash_init() - Initialize an incremental hashing context
- hash_update() - Pump data into an active hashing context
- hash_final() - Finalize an incremental hash and return resulting digest
- hash() - Generate a hash value (message digest)
- hash_file() - Generate a hash value using the contents of a given file
hash_update
(PHP 5 >= 5.1.2, PECL hash >= 1.1)
hash_update — Pump data into an active hashing context
Opis
$context
, string $data
)Parametry
-
context -
Hashing context returned by hash_init().
-
data -
Message to be included in the hash digest.
Zwracane wartości
Returns TRUE.
Zobacz też:
- hash_init() - Initialize an incremental hashing context
- hash_update_file() - Pump data into an active hashing context from a file
- hash_update_stream() - Pump data into an active hashing context from an open stream
- hash_final() - Finalize an incremental hash and return resulting digest
hash
(PHP 5 >= 5.1.2, PECL hash >= 1.1)
hash — Generate a hash value (message digest)
Opis
$algo
, string $data
[, bool $raw_output = false
] )Parametry
-
algo -
Name of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..)
-
data -
Message to be hashed.
-
raw_output -
When set to
TRUE, outputs raw binary data.FALSEoutputs lowercase hexits.
Zwracane wartości
Returns a string containing the calculated message digest as lowercase hexits
unless raw_output is set to true in which case the raw
binary representation of the message digest is returned.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.4.0 | The tiger algorithm now uses big-endian byte ordering. |
Przykłady
Przykład #1 A hash() example
<?php
echo hash('ripemd160', 'The quick brown fox jumped over the lazy dog.');
?>
Powyższy przykład wyświetli:
ec457d0a974c48d5685a7efa03d137dc8bbde7e3
Zobacz też:
- hash_file() - Generate a hash value using the contents of a given file
- hash_hmac() - Generate a keyed hash value using the HMAC method
- hash_init() - Initialize an incremental hashing context
- md5() - Calculate the md5 hash of a string
- sha1() - Calculate the sha1 hash of a string
Spis treści
- hash_algos — Return a list of registered hashing algorithms
- hash_copy — Copy hashing context
- hash_file — Generate a hash value using the contents of a given file
- hash_final — Finalize an incremental hash and return resulting digest
- hash_hmac_file — Generate a keyed hash value using the HMAC method and the contents of a given file
- hash_hmac — Generate a keyed hash value using the HMAC method
- hash_init — Initialize an incremental hashing context
- hash_update_file — Pump data into an active hashing context from a file
- hash_update_stream — Pump data into an active hashing context from an open stream
- hash_update — Pump data into an active hashing context
- hash — Generate a hash value (message digest)
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Hash Funkcje
- hash_algos — Return a list of registered hashing algorithms
- hash_copy — Copy hashing context
- hash_file — Generate a hash value using the contents of a given file
- hash_final — Finalize an incremental hash and return resulting digest
- hash_hmac_file — Generate a keyed hash value using the HMAC method and the contents of a given file
- hash_hmac — Generate a keyed hash value using the HMAC method
- hash_init — Initialize an incremental hashing context
- hash_update_file — Pump data into an active hashing context from a file
- hash_update_stream — Pump data into an active hashing context from an open stream
- hash_update — Pump data into an active hashing context
- hash — Generate a hash value (message digest)
Mcrypt
Wstęp
This is an interface to the mcrypt library, which supports a wide variety of block algorithms such as DES, TripleDES, Blowfish (default), 3-WAY, SAFER-SK64, SAFER-SK128, TWOFISH, TEA, RC2 and GOST in CBC, OFB, CFB and ECB cipher modes. Additionally, it supports RC6 and IDEA which are considered "non-free". CFB/OFB are 8bit by default.
Instalacja/Konfiguracja
Spis treści
Wymagania
These functions work using » mcrypt. To use it, download libmcrypt-x.x.tar.gz from » http://mcrypt.sourceforge.net/ and follow the included installation instructions.
As of PHP 5.0.0 you will need libmcrypt Version 2.5.6 or greater.
Windows users will find the library is the PHP 5.2 Windows binaries release. PHP 5.3 Windows binaries uses the static version of the MCrypt library, no DLL are needed.
If you linked against libmcrypt 2.4.x or higher, the following additional block algorithms are supported: CAST, LOKI97, RIJNDAEL, SAFERPLUS, SERPENT and the following stream ciphers: ENIGMA (crypt), PANAMA, RC4 and WAKE. With libmcrypt 2.4.x or higher another cipher mode is also available; nOFB.
Instalacja
You need to compile PHP with the --with-mcrypt[=DIR] parameter to enable this extension. DIR is the mcrypt install directory. Make sure you compile libmcrypt with the option --disable-posix-threads .
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| mcrypt.algorithms_dir | NULL |
PHP_INI_ALL | |
| mcrypt.modes_dir | NULL |
PHP_INI_ALL |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
mcrypt.algorithms_dirstring -
The directory that contains the algorithms. Defaults to the directories compiled within libmcrypt, which is typically /usr/local/lib/libmcrypt. See mcrypt_list_algorithms() for additional details.
-
mcrypt.modes_dirstring -
The directory that contains the modes. Defaults to the directories compiled within libmcrypt, which is typically /usr/local/lib/libmcrypt. See mcrypt_list_modes() for additional details.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
Mcrypt can operate in four block cipher modes (CBC, OFB, CFB, and ECB). If linked against libmcrypt-2.4.x or higher the functions can also operate in the block cipher mode nOFB and in STREAM mode. Below you find a list with all supported encryption modes together with the constants that are defines for the encryption mode. For a more complete reference and discussion see Applied Cryptography by Schneier (ISBN 0-471-11709-9).
-
MCRYPT_MODE_ECB(electronic codebook) is suitable for random data, such as encrypting other keys. Since data there is short and random, the disadvantages of ECB have a favorable negative effect. -
MCRYPT_MODE_CBC(cipher block chaining) is especially suitable for encrypting files where the security is increased over ECB significantly. -
MCRYPT_MODE_CFB(cipher feedback) is the best mode for encrypting byte streams where single bytes must be encrypted. -
MCRYPT_MODE_OFB(output feedback, in 8bit) is comparable to CFB, but can be used in applications where error propagation cannot be tolerated. It's insecure (because it operates in 8bit mode) so it is not recommended to use it. -
MCRYPT_MODE_NOFB(output feedback, in nbit) is comparable to OFB, but more secure because it operates on the block size of the algorithm. -
MCRYPT_MODE_STREAMis an extra mode to include some stream algorithms like "WAKE" or "RC4".
Some other mode and random device constants:
Mcrypt ciphers
Here is a list of ciphers which are currently supported by the mcrypt extension. For a complete list of supported ciphers, see the defines at the end of mcrypt.h. The general rule with the mcrypt-2.2.x API is that you can access the cipher from PHP with MCRYPT_ciphername. With the libmcrypt-2.4.x and libmcrypt-2.5.x API these constants also work, but it is possible to specify the name of the cipher as a string with a call to mcrypt_module_open().
- MCRYPT_3DES
- MCRYPT_ARCFOUR_IV (libmcrypt > 2.4.x only)
- MCRYPT_ARCFOUR (libmcrypt > 2.4.x only)
- MCRYPT_BLOWFISH
- MCRYPT_CAST_128
- MCRYPT_CAST_256
- MCRYPT_CRYPT
- MCRYPT_DES
- MCRYPT_DES_COMPAT (libmcrypt 2.2.x only)
- MCRYPT_ENIGMA (libmcrypt > 2.4.x only, alias for MCRYPT_CRYPT)
- MCRYPT_GOST
- MCRYPT_IDEA (non-free)
- MCRYPT_LOKI97 (libmcrypt > 2.4.x only)
- MCRYPT_MARS (libmcrypt > 2.4.x only, non-free)
- MCRYPT_PANAMA (libmcrypt > 2.4.x only)
- MCRYPT_RIJNDAEL_128 (libmcrypt > 2.4.x only)
- MCRYPT_RIJNDAEL_192 (libmcrypt > 2.4.x only)
- MCRYPT_RIJNDAEL_256 (libmcrypt > 2.4.x only)
- MCRYPT_RC2
- MCRYPT_RC4 (libmcrypt 2.2.x only)
- MCRYPT_RC6 (libmcrypt > 2.4.x only)
- MCRYPT_RC6_128 (libmcrypt 2.2.x only)
- MCRYPT_RC6_192 (libmcrypt 2.2.x only)
- MCRYPT_RC6_256 (libmcrypt 2.2.x only)
- MCRYPT_SAFER64
- MCRYPT_SAFER128
- MCRYPT_SAFERPLUS (libmcrypt > 2.4.x only)
- MCRYPT_SERPENT(libmcrypt > 2.4.x only)
- MCRYPT_SERPENT_128 (libmcrypt 2.2.x only)
- MCRYPT_SERPENT_192 (libmcrypt 2.2.x only)
- MCRYPT_SERPENT_256 (libmcrypt 2.2.x only)
- MCRYPT_SKIPJACK (libmcrypt > 2.4.x only)
- MCRYPT_TEAN (libmcrypt 2.2.x only)
- MCRYPT_THREEWAY
- MCRYPT_TRIPLEDES (libmcrypt > 2.4.x only)
- MCRYPT_TWOFISH (for older mcrypt 2.x versions, or mcrypt > 2.4.x )
- MCRYPT_TWOFISH128 (TWOFISHxxx are available in newer 2.x versions, but not in the 2.4.x versions)
- MCRYPT_TWOFISH192
- MCRYPT_TWOFISH256
- MCRYPT_WAKE (libmcrypt > 2.4.x only)
- MCRYPT_XTEA (libmcrypt > 2.4.x only)
You must (in CFB and OFB mode)
or can (in CBC mode) supply an
initialization vector (IV) to the respective cipher function. The
IV must be unique and must be the same when
decrypting/encrypting. With data which is stored encrypted, you
can take the output of a function of the index under which the
data is stored (e.g. the MD5 key of the filename).
Alternatively, you can transmit the IV together with the encrypted
data (see chapter 9.3 of Applied Cryptography by Schneier (ISBN 0-471-11709-9) for a
discussion of this topic).
Przykłady
Mcrypt can be used to encrypt and decrypt using the above
mentioned ciphers. If you linked against libmcrypt-2.2.x, the
four important mcrypt commands (mcrypt_cfb(),
mcrypt_cbc(), mcrypt_ecb(),
and mcrypt_ofb()) can operate in both modes
which are named MCRYPT_ENCRYPT and
MCRYPT_DECRYPT, respectively.
Przykład #1 Encrypt an input value with TripleDES under 2.2.x in ECB mode
<?php
$key = "this is a secret key";
$input = "Let us meet at 9 o'clock at the secret place.";
$encrypted_data = mcrypt_ecb (MCRYPT_3DES, $key, $input, MCRYPT_ENCRYPT);
?>
If you linked against libmcrypt 2.4.x or 2.5.x, these functions are still available, but it is recommended that you use the advanced functions.
Przykład #2 Encrypt an input value with TripleDES under 2.4.x and higher in ECB mode
<?php
$key = "this is a secret key";
$input = "Let us meet at 9 o'clock at the secret place.";
$td = mcrypt_module_open('tripledes', '', 'ecb', '');
$iv = mcrypt_create_iv (mcrypt_enc_get_iv_size($td), MCRYPT_RAND);
mcrypt_generic_init($td, $key, $iv);
$encrypted_data = mcrypt_generic($td, $input);
mcrypt_generic_deinit($td);
mcrypt_module_close($td);
?>
Mcrypt Funkcje
mcrypt_cbc
(PHP 4, PHP 5)
mcrypt_cbc — Encrypts/decrypts data in CBC mode
Opis
$cipher
, string $key
, string $data
, int $mode
[, string $iv
] )$cipher
, string $key
, string $data
, int $mode
[, string $iv
] )
The first prototype is when linked against libmcrypt 2.2.x, the
second when linked against libmcrypt 2.4.x or higher. The
mode should be either
MCRYPT_ENCRYPT or
MCRYPT_DECRYPT.
This function should not be used anymore, see mcrypt_generic() and mdecrypt_generic() for replacements.
mcrypt_cfb
(PHP 4, PHP 5)
mcrypt_cfb — Encrypts/decrypts data in CFB mode
Opis
$cipher
, string $key
, string $data
, int $mode
, string $iv
)$cipher
, string $key
, string $data
, int $mode
[, string $iv
] )
The first prototype is when linked against libmcrypt 2.2.x, the
second when linked against libmcrypt 2.4.x or higher. The
mode should be either
MCRYPT_ENCRYPT or
MCRYPT_DECRYPT.
This function should not be used anymore, see mcrypt_generic() and mdecrypt_generic() for replacements.
mcrypt_create_iv
(PHP 4, PHP 5)
mcrypt_create_iv — Creates an initialization vector (IV) from a random source
Opis
$size
[, int $source = MCRYPT_DEV_RANDOM
] )Creates an initialization vector (IV) from a random source.
The IV is only meant to give an alternative seed to the encryption routines. This IV does not need to be secret at all, though it can be desirable. You even can send it along with your ciphertext without losing security.
Parametry
-
size -
The size of the IV.
-
source -
The source of the IV. The source can be
MCRYPT_RAND(system random number generator),MCRYPT_DEV_RANDOM(read data from /dev/random) andMCRYPT_DEV_URANDOM(read data from /dev/urandom). Prior to 5.3.0,MCRYPT_RANDwas the only one supported on Windows.
Zwracane wartości
Returns the initialization vector, or FALSE on error.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.0 |
MCRYPT_DEV_RANDOM and
MCRYPT_DEV_URANDOM became available on Windows
platforms.
|
| 5.3.0 | It is no longer required to call srand() first. This is now done automatically. |
Przykłady
Przykład #1 mcrypt_create_iv() Example
<?php
$size = mcrypt_get_iv_size(MCRYPT_CAST_256, MCRYPT_MODE_CFB);
$iv = mcrypt_create_iv($size, MCRYPT_DEV_RANDOM);
?>
Zobacz też:
- » http://www.ciphersbyritter.com/GLOSSARY.HTM#IV
- » http://www.quadibloc.com/crypto/co0409.htm
- Chapter 9.3 of Applied Cryptography by Schneier (ISBN 0-471-11709-9)
mcrypt_decrypt
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_decrypt — Decrypts crypttext with given parameters
Opis
$cipher
, string $key
, string $data
, string $mode
[, string $iv
] )
Decrypts the data and returns the unencrypted data.
Parametry
-
cipher -
One of the
MCRYPT_ciphernameconstants, or the name of the algorithm as string. -
key -
The key with which the data was encrypted. If it's smaller than the required keysize, it is padded with '\0'.
-
data -
The data that will be decrypted with the given
cipherandmode. If the size of the data is not n * blocksize, the data will be padded with '\0'. -
mode -
One of the
MCRYPT_MODE_modenameconstants, or one of the following strings: "ecb", "cbc", "cfb", "ofb", "nofb" or "stream". -
iv -
The
ivparameter is used for the initialization in CBC, CFB, OFB modes, and in some algorithms in STREAM mode. If you do not supply an IV, while it is needed for an algorithm, the function issues a warning and uses an IV with all its bytes set to '\0'.
Zwracane wartości
Returns the decrypted data as a string.
mcrypt_ecb
(PHP 4, PHP 5)
mcrypt_ecb — Deprecated: Encrypts/decrypts data in ECB mode
Opis
$cipher
, string $key
, string $data
, int $mode
)$cipher
, string $key
, string $data
, int $mode
[, string $iv
] )
The first prototype is when linked against libmcrypt 2.2.x, the
second when linked against libmcrypt 2.4.x or higher. The
mode should be either
MCRYPT_ENCRYPT or
MCRYPT_DECRYPT.
This function is deprecated and should not be used anymore, see mcrypt_generic() and mdecrypt_generic() for replacements.
mcrypt_enc_get_algorithms_name
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_enc_get_algorithms_name — Returns the name of the opened algorithm
Opis
$td
)This function returns the name of the algorithm.
Parametry
-
td -
The encryption descriptor.
Zwracane wartości
Returns the name of the opened algorithm as a string.
Przykłady
Przykład #1 mcrypt_enc_get_algorithms_name() example
<?php
$td = mcrypt_module_open(MCRYPT_CAST_256, '', MCRYPT_MODE_CFB, '');
echo mcrypt_enc_get_algorithms_name($td). "\n";
$td = mcrypt_module_open('cast-256', '', MCRYPT_MODE_CFB, '');
echo mcrypt_enc_get_algorithms_name($td). "\n";
?>
Powyższy przykład wyświetli:
CAST-256 CAST-256
mcrypt_enc_get_block_size
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_enc_get_block_size — Returns the blocksize of the opened algorithm
Opis
$td
)Gets the blocksize of the opened algorithm.
Parametry
-
td -
The encryption descriptor.
Zwracane wartości
Returns the block size of the specified algorithm in bytes.
mcrypt_enc_get_iv_size
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_enc_get_iv_size — Returns the size of the IV of the opened algorithm
Opis
$td
)This function returns the size of the IV of the algorithm specified by the encryption descriptor in bytes. An IV is used in cbc, cfb and ofb modes, and in some algorithms in stream mode.
Parametry
-
td -
The encryption descriptor.
Zwracane wartości
Returns the size of the IV, or 0 if the IV is ignored by the algorithm.
mcrypt_enc_get_key_size
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_enc_get_key_size — Returns the maximum supported keysize of the opened mode
Opis
$td
)Gets the maximum supported key size of the algorithm in bytes.
Parametry
-
td -
The encryption descriptor.
Zwracane wartości
Returns the maximum supported key size of the algorithm in bytes.
mcrypt_enc_get_modes_name
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_enc_get_modes_name — Returns the name of the opened mode
Opis
$td
)This function returns the name of the mode.
Parametry
-
td -
The encryption descriptor.
Zwracane wartości
Returns the name as a string.
Przykłady
Przykład #1 mcrypt_enc_get_modes_name() example
<?php
$td = mcrypt_module_open (MCRYPT_CAST_256, '', MCRYPT_MODE_CFB, '');
echo mcrypt_enc_get_modes_name($td). "\n";
$td = mcrypt_module_open ('cast-256', '', 'ecb', '');
echo mcrypt_enc_get_modes_name($td). "\n";
?>
Powyższy przykład wyświetli:
CFB ECB
mcrypt_enc_get_supported_key_sizes
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_enc_get_supported_key_sizes — Returns an array with the supported keysizes of the opened algorithm
Opis
$td
)Gets the supported key sizes of the opened algorithm.
Parametry
-
td -
The encryption descriptor.
Zwracane wartości
Returns an array with the key sizes supported by the algorithm specified by the encryption descriptor. If it returns an empty array then all key sizes between 1 and mcrypt_enc_get_key_size() are supported by the algorithm.
Przykłady
Przykład #1 mcrypt_enc_get_supported_key_sizes() example
<?php
$td = mcrypt_module_open('rijndael-256', '', 'ecb', '');
var_dump(mcrypt_enc_get_supported_key_sizes($td));
?>
Powyższy przykład wyświetli:
array(3) {
[0]=>
int(16)
[1]=>
int(24)
[2]=>
int(32)
}
mcrypt_enc_is_block_algorithm_mode
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_enc_is_block_algorithm_mode — Checks whether the encryption of the opened mode works on blocks
Opis
$td
)
Tells whether the algorithm of the opened mode works on blocks (e.g.
FALSE for stream, and TRUE for cbc, cfb, ofb)..
Parametry
-
td -
The encryption descriptor.
Zwracane wartości
Returns TRUE if the mode is for use with block algorithms, otherwise it
returns FALSE.
mcrypt_enc_is_block_algorithm
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_enc_is_block_algorithm — Checks whether the algorithm of the opened mode is a block algorithm
Opis
$td
)Tells whether the algorithm of the opened mode is a block algorithm.
Parametry
-
td -
The encryption descriptor.
Zwracane wartości
Returns TRUE if the algorithm is a block algorithm or FALSE if it is
a stream one.
mcrypt_enc_is_block_mode
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_enc_is_block_mode — Checks whether the opened mode outputs blocks
Opis
$td
)
Tells whether the opened mode outputs blocks (e.g. TRUE for cbc and ecb,
and FALSE for cfb and stream).
Parametry
-
td -
The encryption descriptor.
Zwracane wartości
Returns TRUE if the mode outputs blocks of bytes,
or FALSE if it outputs just bytes.
mcrypt_enc_self_test
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_enc_self_test — Runs a self test on the opened module
Opis
$td
)
This function runs the self test on the algorithm specified by the
descriptor td.
Parametry
-
td -
The encryption descriptor.
Zwracane wartości
If the self test succeeds it returns FALSE. In case of an error, it
returns TRUE.
mcrypt_encrypt
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_encrypt — Encrypts plaintext with given parameters
Opis
$cipher
, string $key
, string $data
, string $mode
[, string $iv
] )Encrypts the data and returns it.
Parametry
-
cipher -
One of the
MCRYPT_ciphernameconstants, or the name of the algorithm as string. -
key -
The key with which the data will be encrypted. If it's smaller than the required keysize, it is padded with '\0'. It is better not to use ASCII strings for keys.
It is recommended to use the mhash functions to create a key from a string.
-
data -
The data that will be encrypted with the given
cipherandmode. If the size of the data is not n * blocksize, the data will be padded with '\0'.The returned crypttext can be larger than the size of the data that was given by
data. -
mode -
One of the
MCRYPT_MODE_modenameconstants, or one of the following strings: "ecb", "cbc", "cfb", "ofb", "nofb" or "stream". -
iv -
Used for the initialization in CBC, CFB, OFB modes, and in some algorithms in STREAM mode. If you do not supply an IV, while it is needed for an algorithm, the function issues a warning and uses an IV with all its bytes set to '\0'.
Zwracane wartości
Returns the encrypted data, as a string.
Przykłady
Przykład #1 mcrypt_encrypt() Example
<?php
$iv_size = mcrypt_get_iv_size(MCRYPT_RIJNDAEL_256, MCRYPT_MODE_ECB);
$iv = mcrypt_create_iv($iv_size, MCRYPT_RAND);
$key = "This is a very secret key";
$text = "Meet me at 11 o'clock behind the monument.";
echo strlen($text) . "\n";
$crypttext = mcrypt_encrypt(MCRYPT_RIJNDAEL_256, $key, $text, MCRYPT_MODE_ECB, $iv);
echo strlen($crypttext) . "\n";
?>
Powyższy przykład wyświetli:
42 64
See also mcrypt_module_open() for a more advanced API and an example.
mcrypt_generic_deinit
(PHP 4 >= 4.0.7, PHP 5)
mcrypt_generic_deinit — This function deinitializes an encryption module
Opis
$td
)
This function terminates encryption specified by the encryption
descriptor (td). It clears all buffers, but does
not close the module. You need to call
mcrypt_module_close() yourself. (But PHP does this for
you at the end of the script.)
Parametry
-
td -
The encryption descriptor.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- mcrypt_module_open() - Opens the module of the algorithm and the mode to be used
- mcrypt_generic_init() - This function initializes all buffers needed for encryption
mcrypt_generic_end
(PHP 4 >= 4.0.2, PHP 5 <= 5.1.6)
mcrypt_generic_end — This function terminates encryption
Opis
$td
)
This function is deprecated, use mcrypt_generic_deinit() instead. It can cause crashes when used with mcrypt_module_close() due to multiple buffer frees.
This function terminates encryption specified by the encryption
descriptor (td). Actually it clears all buffers,
and closes all the modules used. Returns FALSE on error, or TRUE on
success.
mcrypt_generic_init
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_generic_init — This function initializes all buffers needed for encryption
Opis
$td
, string $key
, string $iv
)You need to call this function before every call to mcrypt_generic() or mdecrypt_generic().
Parametry
-
td -
The encryption descriptor.
-
key -
The maximum length of the key should be the one obtained by calling mcrypt_enc_get_key_size() and every value smaller than this is legal.
-
iv -
The IV should normally have the size of the algorithms block size, but you must obtain the size by calling mcrypt_enc_get_iv_size(). IV is ignored in ECB. IV MUST exist in CFB, CBC, STREAM, nOFB and OFB modes. It needs to be random and unique (but not secret). The same IV must be used for encryption/decryption. If you do not want to use it you should set it to zeros, but this is not recommended.
Zwracane wartości
The function returns a negative value on error: -3 when the key length
was incorrect, -4 when there was a memory allocation problem and any
other return value is an unknown error. If an error occurs a warning will
be displayed accordingly. FALSE is returned if incorrect parameters
were passed.
mcrypt_generic
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_generic — This function encrypts data
Opis
$td
, string $data
)This function encrypts data. The data is padded with "\0" to make sure the length of the data is n * blocksize. This function returns the encrypted data. Note that the length of the returned string can in fact be longer than the input, due to the padding of the data.
If you want to store the encrypted data in a database make sure to store the entire string as returned by mcrypt_generic, or the string will not entirely decrypt properly. If your original string is 10 characters long and the block size is 8 (use mcrypt_enc_get_block_size() to determine the blocksize), you would need at least 16 characters in your database field. Note the string returned by mdecrypt_generic() will be 16 characters as well...use rtrim($str, "\0") to remove the padding.
If you are for example storing the data in a MySQL database remember that varchar fields automatically have trailing spaces removed during insertion. As encrypted data can end in a space (ASCII 32), the data will be damaged by this removal. Store data in a tinyblob/tinytext (or larger) field instead.
Parametry
-
td -
The encryption descriptor.
The encryption handle should always be initialized with mcrypt_generic_init() with a key and an IV before calling this function. Where the encryption is done, you should free the encryption buffers by calling mcrypt_generic_deinit(). See mcrypt_module_open() for an example.
-
data -
The data to encrypt.
Zwracane wartości
Returns the encrypted data.
Zobacz też:
- mdecrypt_generic() - Decrypts data
- mcrypt_generic_init() - This function initializes all buffers needed for encryption
- mcrypt_generic_deinit() - This function deinitializes an encryption module
mcrypt_get_block_size
(PHP 4, PHP 5)
mcrypt_get_block_size — Gets the block size of the specified cipher
Opis
$cipher
)$cipher
, string $module
)The first prototype is when linked against libmcrypt 2.2.x, the second when linked against libmcrypt 2.4.x or 2.5.x.
mcrypt_get_block_size() is used to get the
size of a block of the specified cipher (in
combination with an encryption mode).
It is more useful to use the mcrypt_enc_get_block_size() function as this uses the resource returned by mcrypt_module_open().
Parametry
-
cipher -
One of the MCRYPT_ciphername constants or the name of the algorithm as string.
-
module -
The module.
Zwracane wartości
Gets the block size, as an integer.
Przykłady
Przykład #1 mcrypt_get_block_size() example
This example shows how to use this function when linked against libmcrypt 2.4.x and 2.5.x.
<?php
echo mcrypt_get_block_size('tripledes', 'ecb'); // 8
?>
Zobacz też:
- mcrypt_get_key_size() - Gets the key size of the specified cipher
- mcrypt_enc_get_block_size() - Returns the blocksize of the opened algorithm
- mcrypt_encrypt() - Encrypts plaintext with given parameters
mcrypt_get_cipher_name
(PHP 4, PHP 5)
mcrypt_get_cipher_name — Gets the name of the specified cipher
Opis
$cipher
)$cipher
)mcrypt_get_cipher_name() is used to get the name of the specified cipher.
mcrypt_get_cipher_name() takes the cipher
number as an argument (libmcrypt 2.2.x) or takes the cipher name
as an argument (libmcrypt 2.4.x or higher) and returns the name of the cipher
or FALSE, if the cipher does not exist.
Parametry
-
cipher -
One of the MCRYPT_ciphername constants or the name of the algorithm as string.
Zwracane wartości
This function returns the name of the cipher or FALSE, if the cipher does
not exist.
Przykłady
Przykład #1 mcrypt_get_cipher_name() Example
<?php
$cipher = MCRYPT_TripleDES;
echo mcrypt_get_cipher_name($cipher);
?>
Powyższy przykład wyświetli:
3DES
mcrypt_get_iv_size
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_get_iv_size — Returns the size of the IV belonging to a specific cipher/mode combination
Opis
$cipher
, string $mode
)
Gets the size of the IV belonging to a specific
cipher/mode combination.
It is more useful to use the mcrypt_enc_get_iv_size() function as this uses the resource returned by mcrypt_module_open().
Parametry
-
cipher -
One of the
MCRYPT_ciphernameconstants, or the name of the algorithm as string. -
mode -
One of the
MCRYPT_MODE_modenameconstants, or one of the following strings: "ecb", "cbc", "cfb", "ofb", "nofb" or "stream". The IV is ignored in ECB mode as this mode does not require it. You will need to have the same IV (think: starting point) both at encryption and decryption stages, otherwise your encryption will fail.
Zwracane wartości
Returns the size of the Initialization Vector (IV) in bytes. On error the
function returns FALSE. If the IV is ignored in the specified cipher/mode
combination zero is returned.
Przykłady
Przykład #1 mcrypt_get_iv_size() Example
<?php
echo mcrypt_get_iv_size(MCRYPT_CAST_256, MCRYPT_MODE_CFB) . "\n";
echo mcrypt_get_iv_size('des', 'ecb') . "\n";
?>
Zobacz też:
- mcrypt_get_block_size() - Gets the block size of the specified cipher
- mcrypt_enc_get_iv_size() - Returns the size of the IV of the opened algorithm
- mcrypt_create_iv() - Creates an initialization vector (IV) from a random source
mcrypt_get_key_size
(PHP 4, PHP 5)
mcrypt_get_key_size — Gets the key size of the specified cipher
Opis
$cipher
)$cipher
, string $module
)The first prototype is when linked against libmcrypt 2.2.x, the second when linked against libmcrypt 2.4.x or 2.5.x.
mcrypt_get_key_size() is used to get the size
of a key of the specified cipher (in
combination with an encryption mode).
It is more useful to use the mcrypt_enc_get_key_size() function as this uses the resource returned by mcrypt_module_open().
Przykłady
Przykład #1 mcrypt_get_key_size() Example
<?php
echo mcrypt_get_key_size('tripledes', 'ecb');
?>
The example above shows how to use this function when linked against libmcrypt 2.4.x or 2.5.x.
Powyższy przykład wyświetli:
24
Zobacz też:
- mcrypt_get_block_size() - Gets the block size of the specified cipher
- mcrypt_enc_get_key_size() - Returns the maximum supported keysize of the opened mode
- mcrypt_encrypt() - Encrypts plaintext with given parameters
mcrypt_list_algorithms
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_list_algorithms — Gets an array of all supported ciphers
Opis
$lib_dir = ini_get("mcrypt.algorithms_dir")
] )
Gets the list of all supported algorithms in the
lib_dir parameter.
Parametry
-
lib_dir -
Specifies the directory where all algorithms are located. If not specified, the value of the mcrypt.algorithms_dir php.ini directive is used.
Zwracane wartości
Returns an array with all the supported algorithms.
Przykłady
Przykład #1 mcrypt_list_algorithms() Example
<?php
$algorithms = mcrypt_list_algorithms("/usr/local/lib/libmcrypt");
foreach ($algorithms as $cipher) {
echo "$cipher<br />\n";
}
?>
The example above will produce a list with all supported algorithms in the "/usr/local/lib/libmcrypt" directory.
mcrypt_list_modes
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_list_modes — Gets an array of all supported modes
Opis
$lib_dir = ini_get("mcrypt.modes_dir")
] )
Gets the list of all supported modes in the
lib_dir parameter.
Parametry
-
lib_dir -
Specifies the directory where all modes are located. If not specified, the value of the mcrypt.modes_dir php.ini directive is used.
Zwracane wartości
Returns an array with all the supported modes.
Przykłady
Przykład #1 mcrypt_list_modes() Example
<?php
$modes = mcrypt_list_modes();
foreach ($modes as $mode) {
echo "$mode <br />\n";
}
?>
The example above will produce a list with all supported algorithms in the default mode directory. If it is not set with the mcrypt.modes_dir php.ini directive, the default directory of mcrypt is used (which is /usr/local/lib/libmcrypt).
mcrypt_module_close
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_module_close — Closes the mcrypt module
Opis
$td
)Closes the specified encryption handle.
Parametry
-
td -
The encryption descriptor.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
mcrypt_module_get_algo_block_size
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_module_get_algo_block_size — Returns the blocksize of the specified algorithm
Opis
$algorithm
[, string $lib_dir
] )Gets the blocksize of the specified algorithm.
Parametry
-
algorithm -
The algorithm name.
-
lib_dir -
This optional parameter can contain the location where the mode module is on the system.
Zwracane wartości
Returns the block size of the algorithm specified in bytes.
mcrypt_module_get_algo_key_size
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_module_get_algo_key_size — Returns the maximum supported keysize of the opened mode
Opis
$algorithm
[, string $lib_dir
] )Gets the maximum supported keysize of the opened mode.
Parametry
-
algorithm -
The algorithm name.
-
lib_dir -
This optional parameter can contain the location where the mode module is on the system.
Zwracane wartości
This function returns the maximum supported key size of the algorithm specified in bytes.
mcrypt_module_get_supported_key_sizes
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_module_get_supported_key_sizes — Returns an array with the supported keysizes of the opened algorithm
Opis
$algorithm
[, string $lib_dir
] )Returns an array with the key sizes supported by the specified algorithm. If it returns an empty array then all key sizes between 1 and mcrypt_module_get_algo_key_size() are supported by the algorithm.
Parametry
-
algorithm -
The algorithm to be used.
-
lib_dir -
The optional
lib_dirparameter can contain the location where the algorithm module is on the system.
Zwracane wartości
Returns an array with the key sizes supported by the specified algorithm. If it returns an empty array then all key sizes between 1 and mcrypt_module_get_algo_key_size() are supported by the algorithm.
Zobacz też:
- mcrypt_enc_get_supported_key_sizes() - Returns an array with the supported keysizes of the opened algorithm
mcrypt_module_is_block_algorithm_mode
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_module_is_block_algorithm_mode — Returns if the specified module is a block algorithm or not
Opis
$mode
[, string $lib_dir
] )
This function returns TRUE if the mode is for use with block
algorithms, otherwise it returns FALSE. (e.g. FALSE for stream, and
TRUE for cbc, cfb, ofb).
Parametry
-
mode -
The mode to check.
-
lib_dir -
The optional
lib_dirparameter can contain the location where the algorithm module is on the system.
Zwracane wartości
This function returns TRUE if the mode is for use with block
algorithms, otherwise it returns FALSE. (e.g. FALSE for stream, and
TRUE for cbc, cfb, ofb).
mcrypt_module_is_block_algorithm
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_module_is_block_algorithm — This function checks whether the specified algorithm is a block algorithm
Opis
$algorithm
[, string $lib_dir
] )
This function returns TRUE if the specified algorithm is a block
algorithm, or FALSE if it is a stream one.
Parametry
-
algorithm -
The algorithm to check.
-
lib_dir -
The optional
lib_dirparameter can contain the location where the algorithm module is on the system.
Zwracane wartości
This function returns TRUE if the specified algorithm is a block
algorithm, or FALSE if it is a stream one.
mcrypt_module_is_block_mode
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_module_is_block_mode — Returns if the specified mode outputs blocks or not
Opis
$mode
[, string $lib_dir
] )
This function returns TRUE if the mode outputs blocks of bytes or
FALSE if it outputs just bytes. (e.g. TRUE for cbc and ecb, and
FALSE for cfb and stream).
Parametry
-
mode -
The mode to check.
-
lib_dir -
The optional
lib_dirparameter can contain the location where the algorithm module is on the system.
Zwracane wartości
This function returns TRUE if the mode outputs blocks of bytes or
FALSE if it outputs just bytes. (e.g. TRUE for cbc and ecb, and
FALSE for cfb and stream).
mcrypt_module_open
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_module_open — Opens the module of the algorithm and the mode to be used
Opis
$algorithm
, string $algorithm_directory
, string $mode
, string $mode_directory
)
This function opens the module of the algorithm and the mode to be used.
The name of the algorithm is specified in algorithm, e.g. "twofish" or is
one of the MCRYPT_ciphername constants. The module is closed by calling
mcrypt_module_close().
Parametry
-
algorithm -
The algorithm to be used.
-
algorithm_directory -
The
algorithm_directoryparameter is used to locate the encryption module. When you supply a directory name, it is used. When you set it to an empty string (""), the value set by the mcrypt.algorithms_dir php.ini directive is used. When it is not set, the default directory that is used is the one that was compiled into libmcrypt (usually /usr/local/lib/libmcrypt). -
mode -
The mode to be used.
-
mode_directory -
The
mode_directoryparameter is used to locate the encryption module. When you supply a directory name, it is used. When you set it to an empty string (""), the value set by the mcrypt.modes_dir php.ini directive is used. When it is not set, the default directory that is used is the one that was compiled-in into libmcrypt (usually /usr/local/lib/libmcrypt).
Zwracane wartości
Normally it returns an encryption descriptor, or FALSE on error.
Przykłady
Przykład #1 mcrypt_module_open() Examples
<?php
$td = mcrypt_module_open(MCRYPT_DES, '',
MCRYPT_MODE_ECB, '/usr/lib/mcrypt-modes');
$td = mcrypt_module_open('rijndael-256', '', 'ofb', '');
?>
The first line in the example above will try to open the DES cipher from the default directory and the EBC mode from the directory /usr/lib/mcrypt-modes. The second example uses strings as name for the cipher and mode, this only works when the extension is linked against libmcrypt 2.4.x or 2.5.x.
Przykład #2 Using mcrypt_module_open() in encryption
<?php
/* Open the cipher */
$td = mcrypt_module_open('rijndael-256', '', 'ofb', '');
/* Create the IV and determine the keysize length, use MCRYPT_RAND
* on Windows instead */
$iv = mcrypt_create_iv(mcrypt_enc_get_iv_size($td), MCRYPT_DEV_RANDOM);
$ks = mcrypt_enc_get_key_size($td);
/* Create key */
$key = substr(md5('very secret key'), 0, $ks);
/* Intialize encryption */
mcrypt_generic_init($td, $key, $iv);
/* Encrypt data */
$encrypted = mcrypt_generic($td, 'This is very important data');
/* Terminate encryption handler */
mcrypt_generic_deinit($td);
/* Initialize encryption module for decryption */
mcrypt_generic_init($td, $key, $iv);
/* Decrypt encrypted string */
$decrypted = mdecrypt_generic($td, $encrypted);
/* Terminate decryption handle and close module */
mcrypt_generic_deinit($td);
mcrypt_module_close($td);
/* Show string */
echo trim($decrypted) . "\n";
?>
Zobacz też:
- mcrypt_module_close() - Closes the mcrypt module
- mcrypt_generic() - This function encrypts data
- mdecrypt_generic() - Decrypts data
- mcrypt_generic_init() - This function initializes all buffers needed for encryption
- mcrypt_generic_deinit() - This function deinitializes an encryption module
mcrypt_module_self_test
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_module_self_test — This function runs a self test on the specified module
Opis
$algorithm
[, string $lib_dir
] )This function runs the self test on the algorithm specified.
Parametry
-
algorithm -
The algorithm to test.
-
lib_dir -
The optional
lib_dirparameter can contain the location where the algorithm module is on the system.
Zwracane wartości
The function returns TRUE if the self test succeeds, or FALSE when it
fails.
Przykłady
Przykład #1 mcrypt_module_self_test() example
<?php
var_dump(mcrypt_module_self_test(MCRYPT_RIJNDAEL_128)) . "\n";
var_dump(mcrypt_module_self_test(MCRYPT_BOGUS_CYPHER));
?>
Powyższy przykład wyświetli:
bool(true) bool(false)
mcrypt_ofb
(PHP 4, PHP 5)
mcrypt_ofb — Encrypts/decrypts data in OFB mode
Opis
$cipher
, string $key
, string $data
, int $mode
, string $iv
)$cipher
, string $key
, string $data
, int $mode
[, string $iv
] )
The first prototype is when linked against libmcrypt 2.2.x, the
second when linked against libmcrypt 2.4.x or higher. The
mode should be either
MCRYPT_ENCRYPT or
MCRYPT_DECRYPT.
This function should not be used anymore, see mcrypt_generic() and mdecrypt_generic() for replacements.
mdecrypt_generic
(PHP 4 >= 4.0.2, PHP 5)
mdecrypt_generic — Decrypts data
Opis
$td
, string $data
)This function decrypts data. Note that the length of the returned string can in fact be longer than the unencrypted string, due to the padding of the data.
Przykłady
Przykład #1 mdecrypt_generic() Example
<?php
/* Data */
$key = 'this is a very long key, even too long for the cipher';
$plain_text = 'very important data';
/* Open module, and create IV */
$td = mcrypt_module_open('des', '', 'ecb', '');
$key = substr($key, 0, mcrypt_enc_get_key_size($td));
$iv_size = mcrypt_enc_get_iv_size($td);
$iv = mcrypt_create_iv($iv_size, MCRYPT_RAND);
/* Initialize encryption handle */
if (mcrypt_generic_init($td, $key, $iv) != -1) {
/* Encrypt data */
$c_t = mcrypt_generic($td, $plain_text);
mcrypt_generic_deinit($td);
/* Reinitialize buffers for decryption */
mcrypt_generic_init($td, $key, $iv);
$p_t = mdecrypt_generic($td, $c_t);
/* Clean up */
mcrypt_generic_deinit($td);
mcrypt_module_close($td);
}
if (strncmp($p_t, $plain_text, strlen($plain_text)) == 0) {
echo "ok\n";
} else {
echo "error\n";
}
?>
The example above shows how to check if the data before the encryption is the same as the data after the decryption. It is very important to reinitialize the encryption buffer with mcrypt_generic_init() before you try to decrypt the data.
The decryption handle should always be initialized with mcrypt_generic_init() with a key and an IV before calling this function. Where the encryption is done, you should free the encryption buffers by calling mcrypt_generic_deinit(). See mcrypt_module_open() for an example.
Zobacz też:
- mcrypt_generic() - This function encrypts data
- mcrypt_generic_init() - This function initializes all buffers needed for encryption
- mcrypt_generic_deinit() - This function deinitializes an encryption module
Spis treści
- mcrypt_cbc — Encrypts/decrypts data in CBC mode
- mcrypt_cfb — Encrypts/decrypts data in CFB mode
- mcrypt_create_iv — Creates an initialization vector (IV) from a random source
- mcrypt_decrypt — Decrypts crypttext with given parameters
- mcrypt_ecb — Deprecated: Encrypts/decrypts data in ECB mode
- mcrypt_enc_get_algorithms_name — Returns the name of the opened algorithm
- mcrypt_enc_get_block_size — Returns the blocksize of the opened algorithm
- mcrypt_enc_get_iv_size — Returns the size of the IV of the opened algorithm
- mcrypt_enc_get_key_size — Returns the maximum supported keysize of the opened mode
- mcrypt_enc_get_modes_name — Returns the name of the opened mode
- mcrypt_enc_get_supported_key_sizes — Returns an array with the supported keysizes of the opened algorithm
- mcrypt_enc_is_block_algorithm_mode — Checks whether the encryption of the opened mode works on blocks
- mcrypt_enc_is_block_algorithm — Checks whether the algorithm of the opened mode is a block algorithm
- mcrypt_enc_is_block_mode — Checks whether the opened mode outputs blocks
- mcrypt_enc_self_test — Runs a self test on the opened module
- mcrypt_encrypt — Encrypts plaintext with given parameters
- mcrypt_generic_deinit — This function deinitializes an encryption module
- mcrypt_generic_end — This function terminates encryption
- mcrypt_generic_init — This function initializes all buffers needed for encryption
- mcrypt_generic — This function encrypts data
- mcrypt_get_block_size — Gets the block size of the specified cipher
- mcrypt_get_cipher_name — Gets the name of the specified cipher
- mcrypt_get_iv_size — Returns the size of the IV belonging to a specific cipher/mode combination
- mcrypt_get_key_size — Gets the key size of the specified cipher
- mcrypt_list_algorithms — Gets an array of all supported ciphers
- mcrypt_list_modes — Gets an array of all supported modes
- mcrypt_module_close — Closes the mcrypt module
- mcrypt_module_get_algo_block_size — Returns the blocksize of the specified algorithm
- mcrypt_module_get_algo_key_size — Returns the maximum supported keysize of the opened mode
- mcrypt_module_get_supported_key_sizes — Returns an array with the supported keysizes of the opened algorithm
- mcrypt_module_is_block_algorithm_mode — Returns if the specified module is a block algorithm or not
- mcrypt_module_is_block_algorithm — This function checks whether the specified algorithm is a block algorithm
- mcrypt_module_is_block_mode — Returns if the specified mode outputs blocks or not
- mcrypt_module_open — Opens the module of the algorithm and the mode to be used
- mcrypt_module_self_test — This function runs a self test on the specified module
- mcrypt_ofb — Encrypts/decrypts data in OFB mode
- mdecrypt_generic — Decrypts data
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Mcrypt ciphers
- Przykłady
- Mcrypt Funkcje
- mcrypt_cbc — Encrypts/decrypts data in CBC mode
- mcrypt_cfb — Encrypts/decrypts data in CFB mode
- mcrypt_create_iv — Creates an initialization vector (IV) from a random source
- mcrypt_decrypt — Decrypts crypttext with given parameters
- mcrypt_ecb — Deprecated: Encrypts/decrypts data in ECB mode
- mcrypt_enc_get_algorithms_name — Returns the name of the opened algorithm
- mcrypt_enc_get_block_size — Returns the blocksize of the opened algorithm
- mcrypt_enc_get_iv_size — Returns the size of the IV of the opened algorithm
- mcrypt_enc_get_key_size — Returns the maximum supported keysize of the opened mode
- mcrypt_enc_get_modes_name — Returns the name of the opened mode
- mcrypt_enc_get_supported_key_sizes — Returns an array with the supported keysizes of the opened algorithm
- mcrypt_enc_is_block_algorithm_mode — Checks whether the encryption of the opened mode works on blocks
- mcrypt_enc_is_block_algorithm — Checks whether the algorithm of the opened mode is a block algorithm
- mcrypt_enc_is_block_mode — Checks whether the opened mode outputs blocks
- mcrypt_enc_self_test — Runs a self test on the opened module
- mcrypt_encrypt — Encrypts plaintext with given parameters
- mcrypt_generic_deinit — This function deinitializes an encryption module
- mcrypt_generic_end — This function terminates encryption
- mcrypt_generic_init — This function initializes all buffers needed for encryption
- mcrypt_generic — This function encrypts data
- mcrypt_get_block_size — Gets the block size of the specified cipher
- mcrypt_get_cipher_name — Gets the name of the specified cipher
- mcrypt_get_iv_size — Returns the size of the IV belonging to a specific cipher/mode combination
- mcrypt_get_key_size — Gets the key size of the specified cipher
- mcrypt_list_algorithms — Gets an array of all supported ciphers
- mcrypt_list_modes — Gets an array of all supported modes
- mcrypt_module_close — Closes the mcrypt module
- mcrypt_module_get_algo_block_size — Returns the blocksize of the specified algorithm
- mcrypt_module_get_algo_key_size — Returns the maximum supported keysize of the opened mode
- mcrypt_module_get_supported_key_sizes — Returns an array with the supported keysizes of the opened algorithm
- mcrypt_module_is_block_algorithm_mode — Returns if the specified module is a block algorithm or not
- mcrypt_module_is_block_algorithm — This function checks whether the specified algorithm is a block algorithm
- mcrypt_module_is_block_mode — Returns if the specified mode outputs blocks or not
- mcrypt_module_open — Opens the module of the algorithm and the mode to be used
- mcrypt_module_self_test — This function runs a self test on the specified module
- mcrypt_ofb — Encrypts/decrypts data in OFB mode
- mdecrypt_generic — Decrypts data
Mhash
Wstęp
These functions are intended to work with » mhash. Mhash can be used to create checksums, message digests, message authentication codes, and more.
This is an interface to the mhash library. Mhash supports a wide
variety of hash algorithms such as MD5, SHA1, GOST, and many
others. For a complete list of supported hashes, refer to the
constants page. The general rule is that you can access
the hash algorithm from PHP with MHASH_hashname. For example, to
access TIGER you use the PHP constant MHASH_TIGER.
Informacja:
This extension is obsoleted by Hash.
Instalacja/Konfiguracja
Spis treści
Wymagania
To use it, download the mhash distribution from » its web site and follow the included installation instructions.
Instalacja
You need to compile PHP with the --with-mhash[=DIR] parameter to enable this extension. DIR is the mhash installation directory.
As of PHP 5.3.0, the mhash extension is emulated thru the Hash extension. This makes the mhash installation directory have no effect, and requires the hash extension enabled to make the mhash support available.
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
Here is a list of hashes which are currently supported by mhash. If a hash is not listed here, but it is listed in the mhash documentation as supported, you can safely assume that this documentation is outdated.
-
MHASH_ADLER32 -
MHASH_CRC32 -
MHASH_CRC32B -
MHASH_GOST -
MHASH_HAVAL128 -
MHASH_HAVAL160 -
MHASH_HAVAL192 -
MHASH_HAVAL224 -
MHASH_HAVAL256 -
MHASH_MD2 -
MHASH_MD4 -
MHASH_MD5 -
MHASH_RIPEMD128 -
MHASH_RIPEMD256 -
MHASH_RIPEMD320 -
MHASH_SHA1 -
MHASH_SHA192 -
MHASH_SHA224 -
MHASH_SHA256 -
MHASH_SHA384 -
MHASH_SHA512 -
MHASH_SNEFRU128 -
MHASH_SNEFRU256 -
MHASH_TIGER -
MHASH_TIGER128 -
MHASH_TIGER160 -
MHASH_WHIRLPOOL
Przykłady
Przykład #1 Computes the MD5 digest and hmac and print it out as hex
<?php
$input = "what do ya want for nothing?";
$hash = mhash(MHASH_MD5, $input);
echo "The hash is " . bin2hex($hash) . "<br />\n";
$hash = mhash(MHASH_MD5, $input, "Jefe");
echo "The hmac is " . bin2hex($hash) . "<br />\n";
?>
Powyższy przykład wyświetli:
The hash is d03cb659cbf9192dcd066272249f8412 The hmac is 750c783e6ab0b503eaa86e310a5db738
Mhash Funkcje
mhash_count
(PHP 4, PHP 5)
mhash_count — Gets the highest available hash ID
Opis
Gets the highest available hash ID.
Zwracane wartości
Returns the highest available hash ID. Hashes are numbered from 0 to this hash ID.
Przykłady
Przykład #1 Traversing all hashes
<?php
$nr = mhash_count();
for ($i = 0; $i <= $nr; $i++) {
echo sprintf("The blocksize of %s is %d\n",
mhash_get_hash_name($i),
mhash_get_block_size($i));
}
?>
mhash_get_block_size
(PHP 4, PHP 5)
mhash_get_block_size — Gets the block size of the specified hash
Opis
$hash
)
Gets the size of a block of the specified hash.
Parametry
-
hash -
The hash ID. One of the
MHASH_hashnameconstants.
Zwracane wartości
Returns the size in bytes or FALSE, if the hash
does not exist.
Przykłady
Przykład #1 mhash_get_block_size() Example
<?php
echo mhash_get_block_size(MHASH_MD5); // 16
?>
mhash_get_hash_name
(PHP 4, PHP 5)
mhash_get_hash_name — Gets the name of the specified hash
Opis
$hash
)
Gets the name of the specified hash.
Parametry
-
hash -
The hash ID. One of the
MHASH_hashnameconstants.
Zwracane wartości
Returns the name of the hash or FALSE, if the hash does not exist.
Przykłady
Przykład #1 mhash_get_hash_name() Example
<?php
echo mhash_get_hash_name(MHASH_MD5); // MD5
?>
mhash_keygen_s2k
(PHP 4 >= 4.0.4, PHP 5)
mhash_keygen_s2k — Generates a key
Opis
$hash
, string $password
, string $salt
, int $bytes
)
Generates a key according to the given hash, using an user
provided password.
This is the Salted S2K algorithm as specified in the OpenPGP document (» RFC 2440).
Keep in mind that user supplied passwords are not really suitable to be used as keys in cryptographic algorithms, since users normally choose keys they can write on keyboard. These passwords use only 6 to 7 bits per character (or less). It is highly recommended to use some kind of transformation (like this function) to the user supplied key.
Parametry
-
hash -
The hash ID used to create the key. One of the
MHASH_hashnameconstants. -
password -
An user supplied password.
-
salt -
Must be different and random enough for every key you generate in order to create different keys. Because
saltmust be known when you check the keys, it is a good idea to append the key to it. Salt has a fixed length of 8 bytes and will be padded with zeros if you supply less bytes. -
bytes -
The key length, in bytes.
Zwracane wartości
Returns the generated key as a string, or FALSE on error.
mhash
(PHP 4, PHP 5)
mhash — Computes hash
Opis
$hash
, string $data
[, string $key
] )
mhash() applies a hash function specified by
hash to the data.
Parametry
-
hash -
The hash ID. One of the
MHASH_hashnameconstants. -
data -
The user input, as a string.
-
key -
If specified, the function will return the resulting HMAC instead. HMAC is keyed hashing for message authentication, or simply a message digest that depends on the specified key. Not all algorithms supported in mhash can be used in HMAC mode.
Zwracane wartości
Returns the resulting hash (also called digest) or HMAC as a string, or
FALSE on error.
Spis treści
- mhash_count — Gets the highest available hash ID
- mhash_get_block_size — Gets the block size of the specified hash
- mhash_get_hash_name — Gets the name of the specified hash
- mhash_keygen_s2k — Generates a key
- mhash — Computes hash
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Przykłady
- Mhash Funkcje
- mhash_count — Gets the highest available hash ID
- mhash_get_block_size — Gets the block size of the specified hash
- mhash_get_hash_name — Gets the name of the specified hash
- mhash_keygen_s2k — Generates a key
- mhash — Computes hash
OpenSSL
Wstęp
This module uses the functions of » OpenSSL for generation and verification of signatures and for sealing (encrypting) and opening (decrypting) data. OpenSSL offers many features that this module currently doesn't support. Some of these may be added in the future.
Instalacja/Konfiguracja
Spis treści
Wymagania
In order to use the OpenSSL functions you need to install the » OpenSSL package. PHP between versions 4.0.5 and 4.3.1 will work with OpenSSL >= 0.9.5. Other versions (PHP <=4.0.4 and >= 4.3.2) require OpenSSL >= 0.9.6.
You are strongly encouraged to use the most recent OpenSSL version, otherwise your web server could be vulnerable to attack.
Instalacja
To use PHP's OpenSSL support you must also compile PHP --with-openssl[=DIR] .
The OpenSSL library also has additional requirements for normal operation at run-time. Most notably, OpenSSL requires access to a random or pseudo-random number generator; on most Unix and Unix-like platforms (including Linux), this means that it must have access to a /dev/urandom or /dev/random device.
Informacja: Note to Win32 Users
Aby poprawnie działało rozszerzenie, pliki DLL muszą znajdować się w miejscu wskazanym przez PATH systemu Windows. Aby uzyskać więcej informacji zobacz FAQ zatytułowane "Jak mam dodać mój katalog PHP do PATH w Windows". Chociaż skopiowanie plików DLL z folderu PHP do systemowego katalogu Windows także zadziała (ponieważ katalog systemowy jest domyślnie w PATH systemu), ale nie jest to wymagane. To rozszerzenie wymaga następujących plików znajdujących się w PATH: libeay32.dll
Additionally, if you are planning to use the key generation and certificate signing functions, you will need to install a valid openssl.cnf file on your system. As of PHP 4.3.0, we include a sample configuration file in our win32 binary distributions. PHP 4.3.x and 4.4.x has the file in the openssl directory. PHP 5.x and 6.x has the file in the extras/openssl directory. If you are either using PHP 4.2.x or missing the file, you can obtain it from » the OpenSSL binaries page or by downloading a recent PHP release. Be aware that Windows Explorer hides the .cnf extension by default and says the file Type is SpeedDial.
PHP will search for the openssl.cnf using the following logic:
In your installation, you need to decide whether to install the configuration file at c:\usr\local\ssl\openssl.cnf or whether to install it someplace else and use environmental variables (possibly on a per-virtual-host basis) to locate the configuration file. Note that it is possible to override the default path from the script using the
- the OPENSSL_CONF environmental variable, if set, will be used as the path (including filename) of the configuration file.
- the SSLEAY_CONF environmental variable, if set, will be used as the path (including filename) of the configuration file.
- The file openssl.cnf will be assumed to be found in the default certificate area, as configured at the time that the openssl DLL was compiled. This is usually means that the default filename is c:\usr\local\ssl\openssl.cnf.
configargsof the functions that require a configuration file.
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
Spis treści
- Purpose checking flags
- Padding flags for asymmetric encryption
- Key types
- PKCS7 Flags/Constants
- Signature Algorithms
- Ciphers
- Version constants
- Server Name Indication constants
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
Purpose checking flags
Padding flags for asymmetric encryption
PKCS7 Flags/Constants
The S/MIME functions make use of flags which are specified using a bitfield which can include one or more of the following values:
| Constant | Description |
|---|---|
PKCS7_TEXT |
Adds text/plain content type headers to encrypted/signed message. If decrypting or verifying, it strips those headers from the output - if the decrypted or verified message is not of MIME type text/plain then an error will occur. |
PKCS7_BINARY |
Normally the input message is converted to "canonical" format which is effectively using CR and LF as end of line: as required by the S/MIME specification. When this option is present, no translation occurs. This is useful when handling binary data which may not be in MIME format. |
PKCS7_NOINTERN |
When verifying a message, certificates (if
any) included in the message are normally searched for the
signing certificate. With this option only the
certificates specified in the extracerts
parameter of openssl_pkcs7_verify() are
used. The supplied certificates can still be used as
untrusted CAs however.
|
PKCS7_NOVERIFY |
Do not verify the signers certificate of a signed message. |
PKCS7_NOCHAIN |
Do not chain verification of signers certificates: that is don't use the certificates in the signed message as untrusted CAs. |
PKCS7_NOCERTS |
When signing a message the signer's certificate is normally
included - with this option it is excluded. This will reduce the
size of the signed message but the verifier must have a copy of the
signers certificate available locally (passed using the
extracerts to
openssl_pkcs7_verify() for example).
|
PKCS7_NOATTR |
Normally when a message is signed, a set of attributes are included which include the signing time and the supported symmetric algorithms. With this option they are not included. |
PKCS7_DETACHED |
When signing a message, use cleartext signing with the MIME
type "multipart/signed". This is the default
if you do not specify any flags to
openssl_pkcs7_sign().
If you turn this option off, the message will be signed using
opaque signing, which is more resistant to translation by mail relays
but cannot be read by mail agents that do not support S/MIME. |
PKCS7_NOSIGS |
Don't try and verify the signatures on a message |
Informacja:
These constants were added in 4.0.6.
Signature Algorithms
-
OPENSSL_ALGO_DSS1(integer) -
OPENSSL_ALGO_SHA1(integer) - Used as default algorithm by openssl_sign() and openssl_verify().
-
OPENSSL_ALGO_MD5(integer) -
OPENSSL_ALGO_MD4(integer) -
OPENSSL_ALGO_MD2(integer)
Informacja:
These constants were added in 5.0.0.
Ciphers
-
OPENSSL_CIPHER_RC2_40(integer) -
OPENSSL_CIPHER_RC2_128(integer) -
OPENSSL_CIPHER_RC2_64(integer) -
OPENSSL_CIPHER_DES(integer) -
OPENSSL_CIPHER_3DES(integer)
Informacja:
These constants were added in 4.3.0.
-
OPENSSL_CIPHER_AES_128_CBC(integer) -
OPENSSL_CIPHER_AES_192_CBC(integer) -
OPENSSL_CIPHER_AES_256_CBC(integer)
Informacja:
These constants were added in 5.4.0.
Version constants
Informacja:
These constants were added in 5.2.0.
Server Name Indication constants
-
OPENSSL_TLSEXT_SERVER_NAME(string) - Whether SNI support is available or not.
Informacja:
This constant were added in 5.3.2 and requires PHP to be built with OpenSSL 0.9.8j or greater.
Key/Certificate parameters
Quite a few of the openssl functions require a key or a certificate parameter. PHP 4.0.5 and earlier have to use a key or certificate resource returned by one of the openssl_get_xxx() functions. Later versions may use one of the following methods:
-
Certificates
- An X.509 resource returned from openssl_x509_read()
- A string having the format file://path/to/cert.pem; the named file must contain a PEM encoded certificate
- A string containing the content of a certificate, PEM encoded
-
Public/Private Keys
- A key resource returned from openssl_get_publickey() or openssl_get_privatekey()
- For public keys only: an X.509 resource
- A string having the format file://path/to/file.pem - the named file must contain a PEM encoded certificate/private key (it may contain both)
- A string containing the content of a certificate/key, PEM encoded
- For private keys, you may also use the syntax array($key, $passphrase) where $key represents a key specified using the file:// or textual content notation above, and $passphrase represents a string containing the passphrase for that private key
Certificate Verification
When calling a function that will verify a signature/certificate, the
cainfo parameter is an array containing file and
directory names that specify the locations of trusted CA files. If a
directory is specified, then it must be a correctly formed hashed
directory as the openssl command would use.
OpenSSL Funkcje
openssl_cipher_iv_length
(PHP 5 >= PHP 5.3.3)
openssl_cipher_iv_length — Gets the cipher iv length
Opis
$method
)Gets the cipher iv length.
Parametry
-
method -
The method.
Zwracane wartości
Returns the cipher length on success, or FALSE on failure.
Błędy/Wyjątki
Emits an E_WARNING level error when the cipher algorithm
is unknown.
Przykłady
Przykład #1 openssl_cipher_iv_length() example
<?php
$method = 'AES-128-CBC';
$ivlen = openssl_cipher_iv_length($method);
echo $ivlen;
?>
Powyższy przykład wyświetli coś podobnego do:
16
openssl_csr_export_to_file
(PHP 4 >= 4.2.0, PHP 5)
openssl_csr_export_to_file — Exports a CSR to a file
Opis
$csr
, string $outfilename
[, bool $notext = true
] )
openssl_csr_export_to_file() takes the Certificate
Signing Request represented by csr and saves it
as ascii-armoured text into the file named by outfilename.
Parametry
-
csr -
-
outfilename -
Path to the output file.
-
notext -
Opcjonalny parametr
notextwpływa na szczegółowość komunikatów wyjścia. Jeśli wynosiFALSE, wówczas do wyjścia dołączane są dodatkowe informacje zrozumiałe dla ludzi. Wartość domyślna parametrunotextwynosi:TRUE.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- openssl_csr_export() - Exports a CSR as a string
- openssl_csr_new() - Generates a CSR
- openssl_csr_sign() - Sign a CSR with another certificate (or itself) and generate a certificate
openssl_csr_export
(PHP 4 >= 4.2.0, PHP 5)
openssl_csr_export — Exports a CSR as a string
Opis
$csr
, string &$out
[, bool $notext = true
] )
openssl_csr_export() takes the Certificate Signing
Request represented by csr and stores it as
ascii-armoured text into out, which is passed by
reference.
Parametry
-
csr -
-
out -
-
notext -
Opcjonalny parametr
notextwpływa na szczegółowość komunikatów wyjścia. Jeśli wynosiFALSE, wówczas do wyjścia dołączane są dodatkowe informacje zrozumiałe dla ludzi. Wartość domyślna parametrunotextwynosi:TRUE.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- openssl_csr_export_to_file() - Exports a CSR to a file
- openssl_csr_new() - Generates a CSR
- openssl_csr_sign() - Sign a CSR with another certificate (or itself) and generate a certificate
openssl_csr_get_public_key
(PHP 5 >= 5.2.0)
openssl_csr_get_public_key — Returns the public key of a CERT
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
openssl_csr_get_subject
(PHP 5 >= 5.2.0)
openssl_csr_get_subject — Returns the subject of a CERT
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
openssl_csr_new
(PHP 4 >= 4.2.0, PHP 5)
openssl_csr_new — Generates a CSR
Opis
$dn
, resource &$privkey
[, array $configargs
[, array $extraattribs
]] )
openssl_csr_new() generates a new CSR (Certificate Signing Request)
based on the information provided by dn, which represents the
Distinguished Name to be used in the certificate.
Informacja: Aby ta funkcja prawidłowo działała wymaga poprawnie zainstalowanego openssl.cnf. Aby uzyskać więcej informacji przeczytaj rozdział instalacja openssl.
Parametry
-
dn -
The Distinguished Name to be used in the certificate.
-
privkey -
privkeyshould be set to a private key that was previously generated by openssl_pkey_new() (or otherwise obtained from the other openssl_pkey family of functions). The corresponding public portion of the key will be used to sign the CSR. -
configargs -
By default, the information in your system openssl.conf is used to initialize the request; you can specify a configuration file section by setting the config_section_section key of
configargs. You can also specify an alternative openssl configuration file by setting the value of the config key to the path of the file you want to use. The following keys, if present inconfigargsbehave as their equivalents in the openssl.conf, as listed in the table below.Configuration overrides configargskeytype openssl.conf equivalent description digest_alg string default_md Selects which digest method to use x509_extensions string x509_extensions Selects which extensions should be used when creating an x509 certificate req_extensions string req_extensions Selects which extensions should be used when creating a CSR private_key_bits integer default_bits Specifies how many bits should be used to generate a private key private_key_type integer none Specifies the type of private key to create. This can be one of OPENSSL_KEYTYPE_DSA,OPENSSL_KEYTYPE_DHorOPENSSL_KEYTYPE_RSA. The default value isOPENSSL_KEYTYPE_RSAwhich is currently the only supported key type.encrypt_key boolean encrypt_key Should an exported key (with passphrase) be encrypted? encrypt_key_cipher integer none One of cipher constants. -
extraattribs -
extraattribsis used to specify additional configuration options for the CSR. Bothdnandextraattribsare associative arrays whose keys are converted to OIDs and applied to the relevant part of the request.
Zwracane wartości
Returns the CSR.
Przykłady
Przykład #1 Creating a self-signed-certificate
<?php
// Fill in data for the distinguished name to be used in the cert
// You must change the values of these keys to match your name and
// company, or more precisely, the name and company of the person/site
// that you are generating the certificate for.
// For SSL certificates, the commonName is usually the domain name of
// that will be using the certificate, but for S/MIME certificates,
// the commonName will be the name of the individual who will use the
// certificate.
$dn = array(
"countryName" => "UK",
"stateOrProvinceName" => "Somerset",
"localityName" => "Glastonbury",
"organizationName" => "The Brain Room Limited",
"organizationalUnitName" => "PHP Documentation Team",
"commonName" => "Wez Furlong",
"emailAddress" => "wez@example.com"
);
// Generate a new private (and public) key pair
$privkey = openssl_pkey_new();
// Generate a certificate signing request
$csr = openssl_csr_new($dn, $privkey);
// You will usually want to create a self-signed certificate at this
// point until your CA fulfills your request.
// This creates a self-signed cert that is valid for 365 days
$sscert = openssl_csr_sign($csr, null, $privkey, 365);
// Now you will want to preserve your private key, CSR and self-signed
// cert so that they can be installed into your web server, mail server
// or mail client (depending on the intended use of the certificate).
// This example shows how to get those things into variables, but you
// can also store them directly into files.
// Typically, you will send the CSR on to your CA who will then issue
// you with the "real" certificate.
openssl_csr_export($csr, $csrout) and var_dump($csrout);
openssl_x509_export($sscert, $certout) and var_dump($certout);
openssl_pkey_export($privkey, $pkeyout, "mypassword") and var_dump($pkeyout);
// Show any errors that occurred here
while (($e = openssl_error_string()) !== false) {
echo $e . "\n";
}
?>
openssl_csr_sign
(PHP 4 >= 4.2.0, PHP 5)
openssl_csr_sign — Sign a CSR with another certificate (or itself) and generate a certificate
Opis
$csr
, mixed $cacert
, mixed $priv_key
, int $days
[, array $configargs
[, int $serial = 0
]] )openssl_csr_sign() generates an x509 certificate resource from the given CSR.
Informacja: Aby ta funkcja prawidłowo działała wymaga poprawnie zainstalowanego openssl.cnf. Aby uzyskać więcej informacji przeczytaj rozdział instalacja openssl.
Parametry
-
csr -
A CSR previously generated by openssl_csr_new(). It can also be the path to a PEM encoded CSR when specified as file://path/to/csr or an exported string generated by openssl_csr_export().
-
cacert -
The generated certificate will be signed by
cacert. IfcacertisNULL, the generated certificate will be a self-signed certificate. -
priv_key -
priv_keyis the private key that corresponds tocacert. -
days -
daysspecifies the length of time for which the generated certificate will be valid, in days. -
configargs -
You can finetune the CSR signing by
configargs. See openssl_csr_new() for more information aboutconfigargs. -
serial -
An optional the serial number of issued certificate. If not specified it will default to 0.
Zwracane wartości
Returns an x509 certificate resource on success, FALSE on failure.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.3.3 |
The serial parameter was added.
|
Przykłady
Przykład #1 openssl_csr_sign() example - signing a CSR (how to implement your own CA)
<?php
// Let's assume that this script is set to receive a CSR that has
// been pasted into a textarea from another page
$csrdata = $_POST["CSR"];
// We will sign the request using our own "certificate authority"
// certificate. You can use any certificate to sign another, but
// the process is worthless unless the signing certificate is trusted
// by the software/users that will deal with the newly signed certificate
// We need our CA cert and its private key
$cacert = "file://path/to/ca.crt";
$privkey = array("file://path/to/ca.key", "your_ca_key_passphrase");
$usercert = openssl_csr_sign($csrdata, $cacert, $privkey, 365);
// Now display the generated certificate so that the user can
// copy and paste it into their local configuration (such as a file
// to hold the certificate for their SSL server)
openssl_x509_export($usercert, $certout);
echo $certout;
// Show any errors that occurred here
while (($e = openssl_error_string()) !== false) {
echo $e . "\n";
}
?>
openssl_decrypt
(PHP 5 >= 5.3.0)
openssl_decrypt — Decrypts data
Opis
$data
, string $method
, string $password
[, bool $raw_input = false
[, string $iv = ""
]] )Takes a raw or base64 encoded string and decrypts it using a given method and key.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
data -
The data.
-
method -
The cipher method.
-
password -
The password.
-
raw_input -
Setting to
TRUEwill take a raw encoded string, otherwise a base64 string is assumed for thedataparameter. -
iv -
A non-NULL Initialization Vector.
Zwracane wartości
The decrypted string on success lub FALSE w przypadku niepowodzenia.
Błędy/Wyjątki
Emits an E_WARNING level error if an unknown cipher algorithm
is passed via the method parameter.
Emits an E_WARNING level error if an empty value is passed
in via the iv parameter.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.3 |
The iv parameter was added.
|
openssl_dh_compute_key
(No version information available, might only be in SVN)
openssl_dh_compute_key — Computes shared secret for public value of remote DH key and local DH key
Opis
$pub_key
, resource $dh_key
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
pub_key -
Public key
-
dh_key -
DH key
Zwracane wartości
Returns computed key on success lub FALSE w przypadku niepowodzenia.
openssl_digest
(PHP 5 >= 5.3.0)
openssl_digest — Computes a digest
Opis
$data
, string $method
[, bool $raw_output = false
] )Computes a digest hash value for the given data using a given method, and returns a raw or binhex encoded string.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
data -
The data.
-
method -
The digest method.
-
raw_output -
Setting to
TRUEwill return as raw output data, otherwise the return value is binhex encoded.
Zwracane wartości
Returns the digested hash value on success lub FALSE w przypadku niepowodzenia.
Błędy/Wyjątki
Emits an E_WARNING level error if an unknown signature algorithm
is passed via the method parameter.
openssl_encrypt
(PHP 5 >= 5.3.0)
openssl_encrypt — Encrypts data
Opis
$data
, string $method
, string $password
[, bool $raw_output = false
[, string $iv = ""
]] )Encrypts given data with given method and key, returns a raw or base64 encoded string
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
data -
The data.
-
method -
The cipher method.
-
password -
The password.
-
raw_output -
Setting to
TRUEwill return as raw output data, otherwise the return value is base64 encoded. -
iv -
A non-NULL Initialization Vector.
Zwracane wartości
Returns the encrypted string on success lub FALSE w przypadku niepowodzenia.
Błędy/Wyjątki
Emits an E_WARNING level error if an unknown cipher
algorithm is passed in via the method parameter.
Emits an E_WARNING level error if an empty value is passed
in via the iv parameter.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.3 |
The iv parameter was added.
|
openssl_error_string
(PHP 4 >= 4.0.6, PHP 5)
openssl_error_string — Return openSSL error message
Opis
openssl_error_string() returns the last error from the openSSL library. Error messages are queued, so this function should be called multiple times to collect all of the information. The last error will be the most recent one.
Zwracane wartości
Returns an error message string, or FALSE if there are no more error
messages to return.
Przykłady
Przykład #1 openssl_error_string() example
<?php
// lets assume you just called an openssl function that failed
while ($msg = openssl_error_string())
echo $msg . "<br />\n";
?>
openssl_free_key
(PHP 4 >= 4.0.4, PHP 5)
openssl_free_key — Free key resource
Opis
$key_identifier
)
openssl_free_key() frees the key associated with
the specified key_identifier from memory.
Parametry
-
key_identifier -
Zwracane wartości
Nie jest zwracana żadna wartość.
openssl_get_cipher_methods
(PHP 5 >= 5.3.0)
openssl_get_cipher_methods — Gets available cipher methods
Opis
$aliases = false
] )Gets a list of available cipher methods.
Zwracane wartości
An array of available cipher methods.
Przykłady
Przykład #1 openssl_get_cipher_methods() example
Shows how the available ciphers might look, and also which aliases might be available.
<?php
$ciphers = openssl_get_cipher_methods();
$ciphers_and_aliases = openssl_get_cipher_methods(true);
$cipher_aliases = array_diff($ciphers_and_aliases, $ciphers);
print_r($ciphers);
print_r($cipher_aliases);
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[0] => AES-128-CBC
[1] => AES-128-CFB
[2] => AES-128-CFB1
[3] => AES-128-CFB8
[4] => AES-128-ECB
[5] => AES-128-OFB
[6] => AES-192-CBC
[7] => AES-192-CFB
[8] => AES-192-CFB1
[9] => AES-192-CFB8
[10] => AES-192-ECB
[11] => AES-192-OFB
[12] => AES-256-CBC
[13] => AES-256-CFB
[14] => AES-256-CFB1
[15] => AES-256-CFB8
[16] => AES-256-ECB
[17] => AES-256-OFB
[18] => BF-CBC
[19] => BF-CFB
[20] => BF-ECB
[21] => BF-OFB
[22] => CAST5-CBC
[23] => CAST5-CFB
[24] => CAST5-ECB
[25] => CAST5-OFB
[26] => DES-CBC
[27] => DES-CFB
[28] => DES-CFB1
[29] => DES-CFB8
[30] => DES-ECB
[31] => DES-EDE
[32] => DES-EDE-CBC
[33] => DES-EDE-CFB
[34] => DES-EDE-OFB
[35] => DES-EDE3
[36] => DES-EDE3-CBC
[37] => DES-EDE3-CFB
[38] => DES-EDE3-OFB
[39] => DES-OFB
[40] => DESX-CBC
[41] => IDEA-CBC
[42] => IDEA-CFB
[43] => IDEA-ECB
[44] => IDEA-OFB
[45] => RC2-40-CBC
[46] => RC2-64-CBC
[47] => RC2-CBC
[48] => RC2-CFB
[49] => RC2-ECB
[50] => RC2-OFB
[51] => RC4
[52] => RC4-40
[53] => aes-128-cbc
[54] => aes-128-cfb
[55] => aes-128-cfb1
[56] => aes-128-cfb8
[57] => aes-128-ecb
[58] => aes-128-ofb
[59] => aes-192-cbc
[60] => aes-192-cfb
[61] => aes-192-cfb1
[62] => aes-192-cfb8
[63] => aes-192-ecb
[64] => aes-192-ofb
[65] => aes-256-cbc
[66] => aes-256-cfb
[67] => aes-256-cfb1
[68] => aes-256-cfb8
[69] => aes-256-ecb
[70] => aes-256-ofb
[71] => bf-cbc
[72] => bf-cfb
[73] => bf-ecb
[74] => bf-ofb
[75] => cast5-cbc
[76] => cast5-cfb
[77] => cast5-ecb
[78] => cast5-ofb
[79] => des-cbc
[80] => des-cfb
[81] => des-cfb1
[82] => des-cfb8
[83] => des-ecb
[84] => des-ede
[85] => des-ede-cbc
[86] => des-ede-cfb
[87] => des-ede-ofb
[88] => des-ede3
[89] => des-ede3-cbc
[90] => des-ede3-cfb
[91] => des-ede3-ofb
[92] => des-ofb
[93] => desx-cbc
[94] => idea-cbc
[95] => idea-cfb
[96] => idea-ecb
[97] => idea-ofb
[98] => rc2-40-cbc
[99] => rc2-64-cbc
[100] => rc2-cbc
[101] => rc2-cfb
[102] => rc2-ecb
[103] => rc2-ofb
[104] => rc4
[105] => rc4-40
)
Array
(
[18] => AES128
[19] => AES192
[20] => AES256
[21] => BF
[26] => CAST
[27] => CAST-cbc
[32] => DES
[47] => DES3
[48] => DESX
[50] => IDEA
[55] => RC2
[82] => aes128
[83] => aes192
[84] => aes256
[85] => bf
[90] => blowfish
[91] => cast
[92] => cast-cbc
[97] => des
[112] => des3
[113] => desx
[115] => idea
[120] => rc2
)
openssl_get_md_methods
(PHP 5 >= 5.3.0)
openssl_get_md_methods — Gets available digest methods
Opis
$aliases = false
] )Gets a list of available digest methods.
Zwracane wartości
An array of available digest methods.
Przykłady
Przykład #1 openssl_get_md_methods() example
Shows how the available digests might look, and also which aliases might be available.
<?php
$digests = openssl_get_md_methods();
$digests_and_aliases = openssl_get_md_methods(true);
$digest_aliases = array_diff($digests_and_aliases, $digests);
print_r($digests);
print_r($digest_aliases);
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[0] => DSA
[1] => DSA-SHA
[2] => MD2
[3] => MD4
[4] => MD5
[5] => RIPEMD160
[6] => SHA
[7] => SHA1
[8] => SHA224
[9] => SHA256
[10] => SHA384
[11] => SHA512
[12] => dsaEncryption
[13] => dsaWithSHA
[14] => ecdsa-with-SHA1
[15] => md2
[16] => md4
[17] => md5
[18] => ripemd160
[19] => sha
[20] => sha1
[21] => sha224
[22] => sha256
[23] => sha384
[24] => sha512
)
Array
(
[2] => DSA-SHA1
[3] => DSA-SHA1-old
[4] => DSS1
[9] => RSA-MD2
[10] => RSA-MD4
[11] => RSA-MD5
[12] => RSA-RIPEMD160
[13] => RSA-SHA
[14] => RSA-SHA1
[15] => RSA-SHA1-2
[16] => RSA-SHA224
[17] => RSA-SHA256
[18] => RSA-SHA384
[19] => RSA-SHA512
[28] => dsaWithSHA1
[29] => dss1
[32] => md2WithRSAEncryption
[34] => md4WithRSAEncryption
[36] => md5WithRSAEncryption
[37] => ripemd
[39] => ripemd160WithRSA
[40] => rmd160
[43] => sha1WithRSAEncryption
[45] => sha224WithRSAEncryption
[47] => sha256WithRSAEncryption
[49] => sha384WithRSAEncryption
[51] => sha512WithRSAEncryption
[52] => shaWithRSAEncryption
[53] => ssl2-md5
[54] => ssl3-md5
[55] => ssl3-sha1
)
Zobacz też:
- openssl_digest() - Computes a digest
- openssl_get_cipher_methods() - Gets available cipher methods
openssl_get_privatekey
(PHP 4 >= 4.0.4, PHP 5)
openssl_get_privatekey — Alias dla openssl_pkey_get_private()
Opis
Ta funkcja jest aliasem dla: openssl_pkey_get_private().
openssl_get_publickey
(PHP 4 >= 4.0.4, PHP 5)
openssl_get_publickey — Alias dla openssl_pkey_get_public()
Opis
Ta funkcja jest aliasem dla: openssl_pkey_get_public().
openssl_open
(PHP 4 >= 4.0.4, PHP 5)
openssl_open — Open sealed data
Opis
$sealed_data
, string &$open_data
, string $env_key
, mixed $priv_key_id
[, string $method
] )
openssl_open() opens (decrypts)
sealed_data using the private key associated with
the key identifier priv_key_id and the envelope key
env_key, and fills
open_data with the decrypted data.
The envelope key is generated when the
data are sealed and can only be used by one specific private key. See
openssl_seal() for more information.
Parametry
-
sealed_data -
-
open_data -
If the call is successful the opened data is returned in this parameter.
-
env_key -
-
priv_key_id -
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 openssl_open() example
<?php
// $sealed and $env_key are assumed to contain the sealed data
// and our envelope key, both given to us by the sealer.
// fetch private key from file and ready it
$fp = fopen("/src/openssl-0.9.6/demos/sign/key.pem", "r");
$priv_key = fread($fp, 8192);
fclose($fp);
$pkeyid = openssl_get_privatekey($priv_key);
// decrypt the data and store it in $open
if (openssl_open($sealed, $open, $env_key, $pkeyid)) {
echo "here is the opened data: ", $open;
} else {
echo "failed to open data";
}
// free the private key from memory
openssl_free_key($pkeyid);
?>
openssl_pkcs12_export_to_file
(PHP 5 >= 5.2.2)
openssl_pkcs12_export_to_file — Exports a PKCS#12 Compatible Certificate Store File
Opis
$x509
, string $filename
, mixed $priv_key
, string $pass
[, array $args
] )
openssl_pkcs12_export_to_file() stores
x509 into a file named by
filename in a PKCS#12 file format.
Parametry
-
x509 -
Zobacz Parametry Klucza/Certyfikatu, aby zapoznać się z prawidłowymi wartościami.
-
filename -
Path to the output file.
-
priv_key -
Private key component of PKCS#12 file.
-
pass -
Encryption password for unlocking the PKCS#12 file.
-
args -
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
openssl_pkcs12_export
(PHP 5 >= 5.2.2)
openssl_pkcs12_export — Exports a PKCS#12 Compatible Certificate Store File to variable.
Opis
$x509
, string &$out
, mixed $priv_key
, string $pass
[, array $args
] )
openssl_pkcs12_export() stores
x509 into a string named by
out in a PKCS#12 file format.
Parametry
-
x509 -
Zobacz Parametry Klucza/Certyfikatu, aby zapoznać się z prawidłowymi wartościami.
-
out -
On success, this will hold the PKCS#12.
-
priv_key -
Private key component of PKCS#12 file.
-
pass -
Encryption password for unlocking the PKCS#12 file.
-
args -
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
openssl_pkcs12_read
(PHP 5 >= 5.2.2)
openssl_pkcs12_read — Parse a PKCS#12 Certificate Store into an array
Opis
$pkcs12
, array &$certs
, string $pass
)
openssl_pkcs12_read() parses the PKCS#12 certificate store supplied by
pkcs12 into a array named
certs.
Parametry
-
pkcs12 -
-
certs -
On success, this will hold the Certificate Store Data.
-
pass -
Encryption password for unlocking the PKCS#12 file.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
openssl_pkcs7_decrypt
(PHP 4 >= 4.0.6, PHP 5)
openssl_pkcs7_decrypt — Decrypts an S/MIME encrypted message
Opis
$infilename
, string $outfilename
, mixed $recipcert
[, mixed $recipkey
] )
Decrypts the S/MIME encrypted message contained in the file specified by
infilename using the certificate and its
associated private key specified by recipcert and
recipkey.
Parametry
-
infilename -
-
outfilename -
The decrypted message is written to the file specified by
outfilename. -
recipcert -
-
recipkey -
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 openssl_pkcs7_decrypt() example
<?php
// $cert and $key are assumed to contain your personal certificate and private
// key pair, and that you are the recipient of an S/MIME message
$infilename = "encrypted.msg"; // this file holds your encrypted message
$outfilename = "decrypted.msg"; // make sure you can write to this file
if (openssl_pkcs7_decrypt($infilename, $outfilename, $cert, $key)) {
echo "decrypted!";
} else {
echo "failed to decrypt!";
}
?>
openssl_pkcs7_encrypt
(PHP 4 >= 4.0.6, PHP 5)
openssl_pkcs7_encrypt — Encrypt an S/MIME message
Opis
$infile
, string $outfile
, mixed $recipcerts
, array $headers
[, int $flags = 0
[, int $cipherid = OPENSSL_CIPHER_RC2_40
]] )
openssl_pkcs7_encrypt() takes the contents of the
file named infile and encrypts them using an RC2
40-bit cipher so that they can only be read by the intended recipients
specified by recipcerts.
Parametry
-
infile -
-
outfile -
-
recipcerts -
Either a lone X.509 certificate, or an array of X.509 certificates.
-
headers -
headersis an array of headers that will be prepended to the data after it has been encrypted.headerscan be either an associative array keyed by header name, or an indexed array, where each element contains a single header line. -
flags -
flagscan be used to specify options that affect the encoding process - see PKCS7 constants. -
cipherid -
One of cipher constants.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.0.0 |
The cipherid parameter was added.
|
Przykłady
Przykład #1 openssl_pkcs7_encrypt() example
<?php
// the message you want to encrypt and send to your secret agent
// in the field, known as nighthawk. You have his certificate
// in the file nighthawk.pem
$data = <<<EOD
Nighthawk,
Top secret, for your eyes only!
The enemy is closing in! Meet me at the cafe at 8.30am
to collect your forged passport!
HQ
EOD;
// load key
$key = file_get_contents("nighthawk.pem");
// save message to file
$fp = fopen("msg.txt", "w");
fwrite($fp, $data);
fclose($fp);
// encrypt it
if (openssl_pkcs7_encrypt("msg.txt", "enc.txt", $key,
array("To" => "nighthawk@example.com", // keyed syntax
"From: HQ <hq@example.com>", // indexed syntax
"Subject" => "Eyes only"))) {
// message encrypted - send it!
exec(ini_get("sendmail_path") . " < enc.txt");
}
?>
openssl_pkcs7_sign
(PHP 4 >= 4.0.6, PHP 5)
openssl_pkcs7_sign — Sign an S/MIME message
Opis
$infilename
, string $outfilename
, mixed $signcert
, mixed $privkey
, array $headers
[, int $flags = PKCS7_DETACHED
[, string $extracerts
]] )
openssl_pkcs7_sign() takes the contents of the file
named infilename and signs them using the
certificate and its matching private key specified by
signcert and privkey
parameters.
Parametry
-
infilename -
-
outfilename -
-
signcert -
-
privkey -
-
headers -
headersis an array of headers that will be prepended to the data after it has been signed (see openssl_pkcs7_encrypt() for more information about the format of this parameter). -
flags -
flagscan be used to alter the output - see PKCS7 constants. -
extracerts -
extracertsspecifies the name of a file containing a bunch of extra certificates to include in the signature which can for example be used to help the recipient to verify the certificate that you used.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 openssl_pkcs7_sign() example
<?php
// the message you want to sign so that recipient can be sure it was you that
// sent it
$data = <<<EOD
You have my authorization to spend $10,000 on dinner expenses.
The CEO
EOD;
// save message to file
$fp = fopen("msg.txt", "w");
fwrite($fp, $data);
fclose($fp);
// encrypt it
if (openssl_pkcs7_sign("msg.txt", "signed.txt", "mycert.pem",
array("file://mycert.pem", "mypassphrase"),
array("To" => "joes@example.com", // keyed syntax
"From: HQ <ceo@example.com>", // indexed syntax
"Subject" => "Eyes only")
)) {
// message signed - send it!
exec(ini_get("sendmail_path") . " < signed.txt");
}
?>
openssl_pkcs7_verify
(PHP 4 >= 4.0.6, PHP 5)
openssl_pkcs7_verify — Verifies the signature of an S/MIME signed message
Opis
$filename
, int $flags
[, string $outfilename
[, array $cainfo
[, string $extracerts
[, string $content
]]]] )openssl_pkcs7_verify() reads the S/MIME message contained in the given file and examines the digital signature.
Parametry
-
filename -
Path to the message.
-
flags -
flagscan be used to affect how the signature is verified - see PKCS7 constants for more information. -
outfilename -
If the
outfilenameis specified, it should be a string holding the name of a file into which the certificates of the persons that signed the messages will be stored in PEM format. -
cainfo -
If the
cainfois specified, it should hold information about the trusted CA certificates to use in the verification process - see certificate verification for more information about this parameter. -
extracerts -
If the
extracertsis specified, it is the filename of a file containing a bunch of certificates to use as untrusted CAs. -
content -
You can specify a filename with
contentthat will be filled with the verified data, but with the signature information stripped.
Zwracane wartości
Returns TRUE if the signature is verified, FALSE if it is not correct
(the message has been tampered with, or the signing certificate is invalid),
or -1 on error.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.1.0 |
The content parameter was added.
|
Notatki
Informacja: As specified in RFC 2045, lines may not be longer than 76 characters in the
filenameparameter.
openssl_pkey_export_to_file
(PHP 4 >= 4.2.0, PHP 5)
openssl_pkey_export_to_file — Gets an exportable representation of a key into a file
Opis
$key
, string $outfilename
[, string $passphrase
[, array $configargs
]] )
openssl_pkey_export_to_file() saves an ascii-armoured
(PEM encoded) rendition of key into the file named
by outfilename.
Informacja: Aby ta funkcja prawidłowo działała wymaga poprawnie zainstalowanego openssl.cnf. Aby uzyskać więcej informacji przeczytaj rozdział instalacja openssl.
Parametry
-
key -
-
outfilename -
Path to the output file.
-
passphrase -
The key can be optionally protected by a
passphrase. -
configargs -
configargscan be used to fine-tune the export process by specifying and/or overriding options for the openssl configuration file. See openssl_csr_new() for more information aboutconfigargs.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
openssl_pkey_export
(PHP 4 >= 4.2.0, PHP 5)
openssl_pkey_export — Gets an exportable representation of a key into a string
Opis
$key
, string &$out
[, string $passphrase
[, array $configargs
]] )
openssl_pkey_export() exports
key as a PEM encoded string and stores it into
out (which is passed by reference).
Informacja: Aby ta funkcja prawidłowo działała wymaga poprawnie zainstalowanego openssl.cnf. Aby uzyskać więcej informacji przeczytaj rozdział instalacja openssl.
Parametry
-
key -
-
out -
-
passphrase -
The key is optionally protected by
passphrase. -
configargs -
configargscan be used to fine-tune the export process by specifying and/or overriding options for the openssl configuration file. See openssl_csr_new() for more information aboutconfigargs.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
openssl_pkey_free
(PHP 4 >= 4.2.0, PHP 5)
openssl_pkey_free — Frees a private key
Opis
$key
)This function frees a private key created by openssl_pkey_new().
Parametry
-
key -
Resource holding the key.
Zwracane wartości
Nie jest zwracana żadna wartość.
openssl_pkey_get_details
(PHP 5 >= 5.2.0)
openssl_pkey_get_details — Returns an array with the key details
Opis
$key
)This function returns the key details (bits, key, type).
Parametry
-
key -
Resource holding the key.
Zwracane wartości
Returns an array with the key details in success or FALSE in failure.
Returned array has indexes bits (number of bits),
key (string representation of the public key) and
type (type of the key which is one of
OPENSSL_KEYTYPE_RSA,
OPENSSL_KEYTYPE_DSA,
OPENSSL_KEYTYPE_DH,
OPENSSL_KEYTYPE_EC or -1 meaning unknown).
Depending on the key type used, additional details may be returned. Note that some elements may not always be available.
-
OPENSSL_KEYTYPE_RSA, an additional array key named "rsa", containing the key data is returned.Key Opis "n" "e" "d" "p" "q" "dmp1" "dmq1" "iqmp" -
OPENSSL_KEYTYPE_DSA, an additional array key named "dsa", containing the key data is returned.Key Opis "p" "q" "g" "priv_key" "pub_key" -
OPENSSL_KEYTYPE_DH, an additional array key named "dh", containing the key data is returned.Key Opis "p" "g" "priv_key" "pub_key"
openssl_pkey_get_private
(PHP 4 >= 4.2.0, PHP 5)
openssl_pkey_get_private — Get a private key
Opis
openssl_get_privatekey() parses
key and prepares it for use by other functions.
Parametry
-
key -
keycan be one of the following:- a string having the format file://path/to/file.pem. The named file must contain a PEM encoded certificate/private key (it may contain both).
- A PEM formatted private key.
-
passphrase -
The optional parameter
passphrasemust be used if the specified key is encrypted (protected by a passphrase).
Zwracane wartości
Returns a positive key resource identifier on success, or FALSE on error.
openssl_pkey_get_public
(PHP 4 >= 4.2.0, PHP 5)
openssl_pkey_get_public — Extract public key from certificate and prepare it for use
Opis
openssl_get_publickey() extracts the public key from
certificate and prepares it for use by other
functions.
Parametry
-
certificate -
certificatecan be one of the following:- an X.509 certificate resource
- a string having the format file://path/to/file.pem. The named file must contain a PEM encoded certificate/private key (it may contain both).
- A PEM formatted private key.
Zwracane wartości
Returns a positive key resource identifier on success, or FALSE on error.
openssl_pkey_new
(PHP 4 >= 4.2.0, PHP 5)
openssl_pkey_new — Generates a new private key
Opis
$configargs
] )openssl_pkey_new() generates a new private and public key pair. The public component of the key can be obtained using openssl_pkey_get_public().
Informacja: Aby ta funkcja prawidłowo działała wymaga poprawnie zainstalowanego openssl.cnf. Aby uzyskać więcej informacji przeczytaj rozdział instalacja openssl.
Parametry
-
configargs -
You can finetune the key generation (such as specifying the number of bits) using
configargs. See openssl_csr_new() for more information aboutconfigargs.
Zwracane wartości
Returns a resource identifier for the pkey on success, or FALSE on
error.
openssl_private_decrypt
(PHP 4 >= 4.0.6, PHP 5)
openssl_private_decrypt — Decrypts data with private key
Opis
$data
, string &$decrypted
, mixed $key
[, int $padding = OPENSSL_PKCS1_PADDING
] )
openssl_private_decrypt() decrypts
data that was previous encrypted via
openssl_public_encrypt() and stores the result into
decrypted.
You can use this function e.g. to decrypt data which were supposed only to you.
Parametry
-
data -
-
decrypted -
-
key -
keymust be the private key corresponding that was used to encrypt the data. -
padding -
paddingcan be one ofOPENSSL_PKCS1_PADDING,OPENSSL_SSLV23_PADDING,OPENSSL_PKCS1_OAEP_PADDING,OPENSSL_NO_PADDING.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- openssl_public_encrypt() - Encrypts data with public key
- openssl_public_decrypt() - Decrypts data with public key
openssl_private_encrypt
(PHP 4 >= 4.0.6, PHP 5)
openssl_private_encrypt — Encrypts data with private key
Opis
$data
, string &$crypted
, mixed $key
[, int $padding = OPENSSL_PKCS1_PADDING
] )
openssl_private_encrypt() encrypts data
with private key and stores the result into
crypted. Encrypted data can be decrypted via
openssl_public_decrypt().
This function can be used e.g. to sign data (or its hash) to prove that it is not written by someone else.
Parametry
-
data -
-
crypted -
-
key -
-
padding -
paddingcan be one ofOPENSSL_PKCS1_PADDING,OPENSSL_NO_PADDING.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- openssl_public_encrypt() - Encrypts data with public key
- openssl_public_decrypt() - Decrypts data with public key
openssl_public_decrypt
(PHP 4 >= 4.0.6, PHP 5)
openssl_public_decrypt — Decrypts data with public key
Opis
$data
, string &$decrypted
, mixed $key
[, int $padding = OPENSSL_PKCS1_PADDING
] )
openssl_public_decrypt() decrypts
data that was previous encrypted via
openssl_private_encrypt() and stores the result into
decrypted.
You can use this function e.g. to check if the message was written by the owner of the private key.
Parametry
-
data -
-
decrypted -
-
key -
keymust be the public key corresponding that was used to encrypt the data. -
padding -
paddingcan be one ofOPENSSL_PKCS1_PADDING,OPENSSL_NO_PADDING.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- openssl_private_encrypt() - Encrypts data with private key
- openssl_private_decrypt() - Decrypts data with private key
openssl_public_encrypt
(PHP 4 >= 4.0.6, PHP 5)
openssl_public_encrypt — Encrypts data with public key
Opis
$data
, string &$crypted
, mixed $key
[, int $padding = OPENSSL_PKCS1_PADDING
] )
openssl_public_encrypt() encrypts data
with public key and stores the result into
crypted. Encrypted data can be decrypted via
openssl_private_decrypt().
This function can be used e.g. to encrypt message which can be then read only by owner of the private key. It can be also used to store secure data in database.
Parametry
-
data -
-
crypted -
This will hold the result of the encryption.
-
key -
The public key.
-
padding -
paddingcan be one ofOPENSSL_PKCS1_PADDING,OPENSSL_SSLV23_PADDING,OPENSSL_PKCS1_OAEP_PADDING,OPENSSL_NO_PADDING.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- openssl_private_encrypt() - Encrypts data with private key
- openssl_private_decrypt() - Decrypts data with private key
openssl_random_pseudo_bytes
(PHP 5 >= 5.3.0)
openssl_random_pseudo_bytes — Generate a pseudo-random string of bytes
Opis
$length
[, bool &$crypto_strong
] )
Generates a string of pseudo-random bytes, with the number of bytes
determined by the length parameter.
It also indicates if a cryptographically strong algorithm was used to produce the
pseudo-random bytes, and does this via the optional crypto_strong
parameter. It's rare for this to be FALSE, but some systems may be broken or old.
Parametry
-
length -
The length of the desired string of bytes. Must be a positive integer. PHP will try to cast this parameter to a non-null integer to use it.
-
crypto_strong -
If passed into the function, this will hold a boolean value that determines if the algorithm used was "cryptographically strong", e.g., safe for usage with GPG, passwords, etc.
TRUEif it did, otherwiseFALSE
Zwracane wartości
Returns the generated string of bytes on success, lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 openssl_random_pseudo_bytes() example
<?php
for ($i = -1; $i <= 4; $i++) {
$bytes = openssl_random_pseudo_bytes($i, $cstrong);
$hex = bin2hex($bytes);
echo "Lengths: Bytes: $i and Hex: " . strlen($hex) . PHP_EOL;
var_dump($hex);
var_dump($cstrong);
echo PHP_EOL;
}
?>
Powyższy przykład wyświetli coś podobnego do:
Lengths: Bytes: -1 and Hex: 0 string(0) "" NULL Lengths: Bytes: 0 and Hex: 0 string(0) "" NULL Lengths: Bytes: 1 and Hex: 2 string(2) "42" bool(true) Lengths: Bytes: 2 and Hex: 4 string(4) "dc6e" bool(true) Lengths: Bytes: 3 and Hex: 6 string(6) "288591" bool(true) Lengths: Bytes: 4 and Hex: 8 string(8) "ab86d144" bool(true)
openssl_seal
(PHP 4 >= 4.0.4, PHP 5)
openssl_seal — Seal (encrypt) data
Opis
$data
, string &$sealed_data
, array &$env_keys
, array $pub_key_ids
[, string $method
] )
openssl_seal() seals (encrypts)
data by using RC4 with a randomly generated
secret key. The key is encrypted with each of the public keys
associated with the identifiers in pub_key_ids
and each encrypted key is returned
in env_keys. This means that one can send
sealed data to multiple recipients (provided one has obtained their
public keys). Each recipient must receive both the sealed data and
the envelope key that was encrypted with the recipient's public key.
Parametry
-
data -
-
sealed_data -
-
env_keys -
-
pub_key_ids -
Zwracane wartości
Returns the length of the sealed data on success, or FALSE on error.
If successful the sealed data is returned in
sealed_data, and the envelope keys in
env_keys.
Przykłady
Przykład #1 openssl_seal() example
<?php
// $data is assumed to contain the data to be sealed
// fetch public keys for our recipients, and ready them
$fp = fopen("/src/openssl-0.9.6/demos/maurice/cert.pem", "r");
$cert = fread($fp, 8192);
fclose($fp);
$pk1 = openssl_get_publickey($cert);
// Repeat for second recipient
$fp = fopen("/src/openssl-0.9.6/demos/sign/cert.pem", "r");
$cert = fread($fp, 8192);
fclose($fp);
$pk2 = openssl_get_publickey($cert);
// seal message, only owners of $pk1 and $pk2 can decrypt $sealed with keys
// $ekeys[0] and $ekeys[1] respectively.
openssl_seal($data, $sealed, $ekeys, array($pk1, $pk2));
// free the keys from memory
openssl_free_key($pk1);
openssl_free_key($pk2);
?>
openssl_sign
(PHP 4 >= 4.0.4, PHP 5)
openssl_sign — Generate signature
Opis
$data
, string &$signature
, mixed $priv_key_id
[, int $signature_alg = OPENSSL_ALGO_SHA1
] )
openssl_sign() computes a signature for the
specified data by using SHA1 for hashing
followed by encryption using the private key associated with
priv_key_id. Note that the data itself is
not encrypted.
Parametry
-
data -
-
signature -
If the call was successful the signature is returned in
signature. -
priv_key_id -
-
signature_alg -
For more information see the list of Signature Algorithms.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.0.0 |
The signature_alg parameter was added.
|
Przykłady
Przykład #1 openssl_sign() example
<?php
// $data is assumed to contain the data to be signed
// fetch private key from file and ready it
$fp = fopen("/src/openssl-0.9.6/demos/sign/key.pem", "r");
$priv_key = fread($fp, 8192);
fclose($fp);
$pkeyid = openssl_get_privatekey($priv_key);
// compute signature
openssl_sign($data, $signature, $pkeyid);
// free the key from memory
openssl_free_key($pkeyid);
?>
openssl_verify
(PHP 4 >= 4.0.4, PHP 5)
openssl_verify — Verify signature
Opis
$data
, string $signature
, mixed $pub_key_id
[, int $signature_alg = OPENSSL_ALGO_SHA1
] )
openssl_verify() verifies that the
signature is correct for the specified
data using the public key associated with
pub_key_id. This must be the public key
corresponding to the private key used for signing.
Parametry
-
data -
-
signature -
-
pub_key_id -
-
signature_alg -
For more information see the list of Signature Algorithms.
Zwracane wartości
Returns 1 if the signature is correct, 0 if it is incorrect, and -1 on error.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.2.0 |
The signature_alg parameter was added.
|
Przykłady
Przykład #1 openssl_verify() example
<?php
// $data and $signature are assumed to contain the data and the signature
// fetch public key from certificate and ready it
$fp = fopen("/src/openssl-0.9.6/demos/sign/cert.pem", "r");
$cert = fread($fp, 8192);
fclose($fp);
$pubkeyid = openssl_get_publickey($cert);
// state whether signature is okay or not
$ok = openssl_verify($data, $signature, $pubkeyid);
if ($ok == 1) {
echo "good";
} elseif ($ok == 0) {
echo "bad";
} else {
echo "ugly, error checking signature";
}
// free the key from memory
openssl_free_key($pubkeyid);
?>
openssl_x509_check_private_key
(PHP 4 >= 4.2.0, PHP 5)
openssl_x509_check_private_key — Checks if a private key corresponds to a certificate
Opis
Checks whether the given key is the private key
that corresponds to cert.
Parametry
-
cert -
The certificate.
-
key -
The private key.
Zwracane wartości
Returns TRUE if key is the private key that
corresponds to cert, or FALSE otherwise.
openssl_x509_checkpurpose
(PHP 4 >= 4.0.6, PHP 5)
openssl_x509_checkpurpose — Verifies if a certificate can be used for a particular purpose
Opis
$x509cert
, int $purpose
[, array $cainfo = array()
[, string $untrustedfile
]] )
openssl_x509_checkpurpose() examines a certificate to
see if it can be used for the specified purpose.
Parametry
-
x509cert -
The examined certificate.
-
purpose -
These options are not bitfields - you may specify one only!openssl_x509_checkpurpose() purposes Constant Description X509_PURPOSE_SSL_CLIENT Can the certificate be used for the client side of an SSL connection? X509_PURPOSE_SSL_SERVER Can the certificate be used for the server side of an SSL connection? X509_PURPOSE_NS_SSL_SERVER Can the cert be used for Netscape SSL server? X509_PURPOSE_SMIME_SIGN Can the cert be used to sign S/MIME email? X509_PURPOSE_SMIME_ENCRYPT Can the cert be used to encrypt S/MIME email? X509_PURPOSE_CRL_SIGN Can the cert be used to sign a certificate revocation list (CRL)? X509_PURPOSE_ANY Can the cert be used for Any/All purposes? -
cainfo -
cainfoshould be an array of trusted CA files/dirs as described in Certificate Verification. -
untrustedfile -
If specified, this should be the name of a PEM encoded file holding certificates that can be used to help verify the certificate, although no trust is placed in the certificates that come from that file.
Zwracane wartości
Returns TRUE if the certificate can be used for the intended purpose,
FALSE if it cannot, or -1 on error.
openssl_x509_export_to_file
(PHP 4 >= 4.2.0, PHP 5)
openssl_x509_export_to_file — Exports a certificate to file
Opis
openssl_x509_export_to_file() stores
x509 into a file named by
outfilename in a PEM encoded format.
Parametry
-
x509 -
Zobacz Parametry Klucza/Certyfikatu, aby zapoznać się z prawidłowymi wartościami.
-
outfilename -
Path to the output file.
-
notext -
Opcjonalny parametr
notextwpływa na szczegółowość komunikatów wyjścia. Jeśli wynosiFALSE, wówczas do wyjścia dołączane są dodatkowe informacje zrozumiałe dla ludzi. Wartość domyślna parametrunotextwynosi:TRUE.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
openssl_x509_export
(PHP 4 >= 4.2.0, PHP 5)
openssl_x509_export — Exports a certificate as a string
Opis
openssl_x509_export() stores
x509 into a string named by
output in a PEM encoded format.
Parametry
-
x509 -
Zobacz Parametry Klucza/Certyfikatu, aby zapoznać się z prawidłowymi wartościami.
-
output -
On success, this will hold the PEM.
-
notext -
Opcjonalny parametr
notextwpływa na szczegółowość komunikatów wyjścia. Jeśli wynosiFALSE, wówczas do wyjścia dołączane są dodatkowe informacje zrozumiałe dla ludzi. Wartość domyślna parametrunotextwynosi:TRUE.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
openssl_x509_free
(PHP 4 >= 4.0.6, PHP 5)
openssl_x509_free — Free certificate resource
Opis
$x509cert
)
openssl_x509_free() frees the certificate associated
with the specified x509cert resource from memory.
Parametry
-
x509cert -
Zwracane wartości
Nie jest zwracana żadna wartość.
openssl_x509_parse
(PHP 4 >= 4.0.6, PHP 5)
openssl_x509_parse — Parse an X509 certificate and return the information as an array
Opis
openssl_x509_parse() returns information about the
supplied x509cert, including fields such as subject
name, issuer name, purposes, valid from and valid to dates etc.
Parametry
-
x509cert -
-
shortnames -
shortnamescontrols how the data is indexed in the array - ifshortnamesisTRUE(the default) then fields will be indexed with the short name form, otherwise, the long name form will be used - e.g.: CN is the shortname form of commonName.
Zwracane wartości
The structure of the returned data is (deliberately) not yet documented, as it is still subject to change.
openssl_x509_read
(PHP 4 >= 4.0.6, PHP 5)
openssl_x509_read — Parse an X.509 certificate and return a resource identifier for it
Opis
openssl_x509_read() parses the certificate supplied by
x509certdata and returns a resource identifier for
it.
Parametry
-
x509certdata -
Zwracane wartości
Returns a resource identifier on success lub FALSE w przypadku niepowodzenia.
Spis treści
- openssl_cipher_iv_length — Gets the cipher iv length
- openssl_csr_export_to_file — Exports a CSR to a file
- openssl_csr_export — Exports a CSR as a string
- openssl_csr_get_public_key — Returns the public key of a CERT
- openssl_csr_get_subject — Returns the subject of a CERT
- openssl_csr_new — Generates a CSR
- openssl_csr_sign — Sign a CSR with another certificate (or itself) and generate a certificate
- openssl_decrypt — Decrypts data
- openssl_dh_compute_key — Computes shared secret for public value of remote DH key and local DH key
- openssl_digest — Computes a digest
- openssl_encrypt — Encrypts data
- openssl_error_string — Return openSSL error message
- openssl_free_key — Free key resource
- openssl_get_cipher_methods — Gets available cipher methods
- openssl_get_md_methods — Gets available digest methods
- openssl_get_privatekey — Alias dla openssl_pkey_get_private
- openssl_get_publickey — Alias dla openssl_pkey_get_public
- openssl_open — Open sealed data
- openssl_pkcs12_export_to_file — Exports a PKCS#12 Compatible Certificate Store File
- openssl_pkcs12_export — Exports a PKCS#12 Compatible Certificate Store File to variable.
- openssl_pkcs12_read — Parse a PKCS#12 Certificate Store into an array
- openssl_pkcs7_decrypt — Decrypts an S/MIME encrypted message
- openssl_pkcs7_encrypt — Encrypt an S/MIME message
- openssl_pkcs7_sign — Sign an S/MIME message
- openssl_pkcs7_verify — Verifies the signature of an S/MIME signed message
- openssl_pkey_export_to_file — Gets an exportable representation of a key into a file
- openssl_pkey_export — Gets an exportable representation of a key into a string
- openssl_pkey_free — Frees a private key
- openssl_pkey_get_details — Returns an array with the key details
- openssl_pkey_get_private — Get a private key
- openssl_pkey_get_public — Extract public key from certificate and prepare it for use
- openssl_pkey_new — Generates a new private key
- openssl_private_decrypt — Decrypts data with private key
- openssl_private_encrypt — Encrypts data with private key
- openssl_public_decrypt — Decrypts data with public key
- openssl_public_encrypt — Encrypts data with public key
- openssl_random_pseudo_bytes — Generate a pseudo-random string of bytes
- openssl_seal — Seal (encrypt) data
- openssl_sign — Generate signature
- openssl_verify — Verify signature
- openssl_x509_check_private_key — Checks if a private key corresponds to a certificate
- openssl_x509_checkpurpose — Verifies if a certificate can be used for a particular purpose
- openssl_x509_export_to_file — Exports a certificate to file
- openssl_x509_export — Exports a certificate as a string
- openssl_x509_free — Free certificate resource
- openssl_x509_parse — Parse an X509 certificate and return the information as an array
- openssl_x509_read — Parse an X.509 certificate and return a resource identifier for it
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Key/Certificate parameters
- Certificate Verification
- OpenSSL Funkcje
- openssl_cipher_iv_length — Gets the cipher iv length
- openssl_csr_export_to_file — Exports a CSR to a file
- openssl_csr_export — Exports a CSR as a string
- openssl_csr_get_public_key — Returns the public key of a CERT
- openssl_csr_get_subject — Returns the subject of a CERT
- openssl_csr_new — Generates a CSR
- openssl_csr_sign — Sign a CSR with another certificate (or itself) and generate a certificate
- openssl_decrypt — Decrypts data
- openssl_dh_compute_key — Computes shared secret for public value of remote DH key and local DH key
- openssl_digest — Computes a digest
- openssl_encrypt — Encrypts data
- openssl_error_string — Return openSSL error message
- openssl_free_key — Free key resource
- openssl_get_cipher_methods — Gets available cipher methods
- openssl_get_md_methods — Gets available digest methods
- openssl_get_privatekey — Alias dla openssl_pkey_get_private
- openssl_get_publickey — Alias dla openssl_pkey_get_public
- openssl_open — Open sealed data
- openssl_pkcs12_export_to_file — Exports a PKCS#12 Compatible Certificate Store File
- openssl_pkcs12_export — Exports a PKCS#12 Compatible Certificate Store File to variable.
- openssl_pkcs12_read — Parse a PKCS#12 Certificate Store into an array
- openssl_pkcs7_decrypt — Decrypts an S/MIME encrypted message
- openssl_pkcs7_encrypt — Encrypt an S/MIME message
- openssl_pkcs7_sign — Sign an S/MIME message
- openssl_pkcs7_verify — Verifies the signature of an S/MIME signed message
- openssl_pkey_export_to_file — Gets an exportable representation of a key into a file
- openssl_pkey_export — Gets an exportable representation of a key into a string
- openssl_pkey_free — Frees a private key
- openssl_pkey_get_details — Returns an array with the key details
- openssl_pkey_get_private — Get a private key
- openssl_pkey_get_public — Extract public key from certificate and prepare it for use
- openssl_pkey_new — Generates a new private key
- openssl_private_decrypt — Decrypts data with private key
- openssl_private_encrypt — Encrypts data with private key
- openssl_public_decrypt — Decrypts data with public key
- openssl_public_encrypt — Encrypts data with public key
- openssl_random_pseudo_bytes — Generate a pseudo-random string of bytes
- openssl_seal — Seal (encrypt) data
- openssl_sign — Generate signature
- openssl_verify — Verify signature
- openssl_x509_check_private_key — Checks if a private key corresponds to a certificate
- openssl_x509_checkpurpose — Verifies if a certificate can be used for a particular purpose
- openssl_x509_export_to_file — Exports a certificate to file
- openssl_x509_export — Exports a certificate as a string
- openssl_x509_free — Free certificate resource
- openssl_x509_parse — Parse an X509 certificate and return the information as an array
- openssl_x509_read — Parse an X.509 certificate and return a resource identifier for it
Rozszerzenia baz danych
Warstwy abstrakcji
Database (dbm-style) Abstraction Layer
Wstęp
These functions build the foundation for accessing Berkeley DB style databases.
This is a general abstraction layer for several file-based databases. As such, functionality is limited to a common subset of features supported by modern databases such as » Oracle Berkeley DB.
Instalacja/Konfiguracja
Spis treści
Wymagania
The behaviour of various aspects depends on the implementation of the underlying database. Functions such as dba_optimize() and dba_sync() will do what they promise for one database and will do nothing for others. You have to download and install supported dba-Handlers.
| Handler | Notes |
|---|---|
| dbm | Dbm is the oldest (original) type of Berkeley DB style databases. You should avoid it, if possible. We do not support the compatibility functions built into DB2 and gdbm, because they are only compatible on the source code level, but cannot handle the original dbm format. |
| ndbm | Ndbm is a newer type and more flexible than dbm. It still has most of the arbitrary limits of dbm (therefore it is deprecated). |
| gdbm | Gdbm is the » GNU database manager. |
| db2 | DB2 is for » Oracle Berkeley DB 2. It is described as "a programmatic toolkit that provides high-performance built-in database support for both standalone and client/server applications. |
| db3 | DB3 is for » Oracle Berkeley DB 3. |
| db4 | DB4 is for » Oracle Berkeley DB 4 or 5. This option is available from PHP 4.3.2. It can be used with BDB 5 from PHP 5.3.3. |
| cdb | Cdb is "a fast, reliable, lightweight package for creating and reading constant databases." It is from the author of qmail and can be found at » http://cr.yp.to/cdb.html. Since it is constant, we support only reading operations. And since PHP 4.3.0 we support writing (not updating) through the internal cdb library. |
| cdb_make | Since PHP 4.3.0 we support creation (not updating) of cdb files when the bundled cdb library is used. |
| flatfile | This is available since PHP 4.3.0 for compatibility with the deprecated dbm extension only and should be avoided. However you may use this where files were created in this format. That happens when configure could not find any external library. |
| inifile |
This is available since PHP 4.3.3 to be able to modify php.ini files
from within PHP scripts. When working with ini files you can pass arrays
of the form array(0=>group,1=>value_name) or strings of the form
"[group]value_name" where group is optional. As the functions
dba_firstkey() and dba_nextkey()
return string representations of the key there is a new function
dba_key_split() available since PHP 5 which allows
to convert the string keys into array keys without loosing FALSE.
|
| qdbm | This is available since PHP 5.0.0. The qdbm library can be loaded from » http://fallabs.com/qdbm/index.html. |
When invoking the dba_open() or dba_popen() functions, one of the handler names must be supplied as an argument. The actually available list of handlers is displayed by invoking phpinfo() or dba_handlers().
Instalacja
By using the --enable-dba=shared configuration option you can build a dynamic loadable module to enable PHP for basic support of dbm-style databases. You also have to add support for at least one of the following handlers by specifying the --with-XXXX configure switch to your PHP configure line.
After configuring and compiling PHP you must execute the following test from commandline: php run-tests.php ext/dba. This shows whether your combination of handlers works. Most problematic are dbm and ndbm which conflict with many installations. The reason for this is that on several systems these libraries are part of more than one other library. The configuration test only prevents you from configuring malfunctioning single handlers but not combinations.
| Handler | Configure Switch |
|---|---|
| dbm |
To enable support for dbm add --with-dbm[=DIR] .
|
| ndbm |
To enable support for ndbm add --with-ndbm[=DIR] .
|
| gdbm | To enable support for gdbm add --with-gdbm[=DIR] . |
| db2 |
To enable support for Oracle Berkeley DB 2 add --with-db2[=DIR] .
|
| db3 |
To enable support for Oracle Berkeley DB 3 add --with-db3[=DIR] .
|
| db4 |
To enable support for Oracle Berkeley DB 4 or 5 add --with-db4[=DIR] .
|
| cdb |
To enable support for cdb add --with-cdb[=DIR] .
|
| flatfile |
To enable support for flatfile add --with-flatfile .
|
| inifile |
To enable support for inifile add --with-inifile .
|
| qdbm |
To enable support for qdbm add --with-qdbm[=DIR] .
|
Informacja:
Up to PHP 4.3.0 you are able to add both db2 and db3 handler but only one of them can be used internally. That means that you cannot have both file formats. Starting with PHP 5.0.0 there is a configuration check avoid such misconfigurations.
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
The functions dba_open() and dba_popen() return a handle to the specified database file to access which is used by all other dba-function calls.
Stałe predefiniowane
To rozszerzenie nie posiada żadnych stałych.
Przykłady
Spis treści
Basic usage
Przykład #1 DBA example
<?php
$id = dba_open("/tmp/test.db", "n", "db2");
if (!$id) {
echo "dba_open failed\n";
exit;
}
dba_replace("key", "This is an example!", $id);
if (dba_exists("key", $id)) {
echo dba_fetch("key", $id);
dba_delete("key", $id);
}
dba_close($id);
?>
DBA is binary safe and does not have any arbitrary limits. However, it inherits all limits set by the underlying database implementation.
All file-based databases must provide a way of setting the file mode of a new created database, if that is possible at all. The file mode is commonly passed as the fourth argument to dba_open() or dba_popen().
You can access all entries of a database in a linear way by using the dba_firstkey() and dba_nextkey() functions. You may not change the database while traversing it.
Przykład #2 Traversing a database
<?php
// ...open database...
$key = dba_firstkey($id);
while ($key != false) {
if (true) { // remember the key to perform some action later
$handle_later[] = $key;
}
$key = dba_nextkey($id);
}
foreach ($handle_later as $val) {
dba_delete($val, $id);
}
?>
DBA Funkcje
dba_close
(PHP 4, PHP 5)
dba_close — Close a DBA database
Opis
$handle
)dba_close() closes the established database and frees all resources of the specified database handle.
Zwracane wartości
Nie jest zwracana żadna wartość.
dba_delete
(PHP 4, PHP 5)
dba_delete — Delete DBA entry specified by key
Opis
$key
, resource $handle
)dba_delete() deletes the specified entry from the database.
Parametry
-
key -
The key of the entry which is deleted.
-
handle -
The database handler, returned by dba_open() or dba_popen().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- dba_exists() - Check whether key exists
- dba_fetch() - Fetch data specified by key
- dba_insert() - Insert entry
- dba_replace() - Replace or insert entry
dba_exists
(PHP 4, PHP 5)
dba_exists — Check whether key exists
Opis
$key
, resource $handle
)
dba_exists() checks whether the specified
key exists in the database.
Parametry
-
key -
The key the check is performed for.
-
handle -
The database handler, returned by dba_open() or dba_popen().
Zwracane wartości
Returns TRUE if the key exists, FALSE otherwise.
Zobacz też:
- dba_delete() - Delete DBA entry specified by key
- dba_fetch() - Fetch data specified by key
- dba_insert() - Insert entry
- dba_replace() - Replace or insert entry
dba_fetch
(PHP 4, PHP 5)
dba_fetch — Fetch data specified by key
Opis
$key
, resource $handle
)$key
, int $skip
, resource $handle
)
dba_fetch() fetches the data specified by
key from the database specified with
handle.
Parametry
-
key -
The key the data is specified by.
Informacja:
When working with inifiles this function accepts arrays as keys where index 0 is the group and index 1 is the value name. See: dba_key_split().
-
skip -
The number of key-value pairs to ignore when using cdb databases. This value is ignored for all other databases which do not support multiple keys with the same name.
-
handle -
The database handler, returned by dba_open() or dba_popen().
Zwracane wartości
Returns the associated string if the key/data pair is found, FALSE
otherwise.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.3.0 |
The skip parameter is available to support
cdb's capability of multiple keys having the same name.
|
Zobacz też:
- dba_exists() - Check whether key exists
- dba_delete() - Delete DBA entry specified by key
- dba_insert() - Insert entry
- dba_replace() - Replace or insert entry
- dba_key_split() - Splits a key in string representation into array representation
dba_firstkey
(PHP 4, PHP 5)
dba_firstkey — Fetch first key
Opis
$handle
)dba_firstkey() returns the first key of the database and resets the internal key pointer. This permits a linear search through the whole database.
Zwracane wartości
Returns the key on success lub FALSE w przypadku niepowodzenia.
Zobacz też:
- dba_nextkey() - Fetch next key
- dba_key_split() - Splits a key in string representation into array representation
- Example 2 in the DBA examples
dba_handlers
(PHP 4 >= 4.3.0, PHP 5)
dba_handlers — List all the handlers available
Opis
$full_info = false
] )dba_handlers() list all the handlers supported by this extension.
Parametry
-
full_info -
Turns on/off full information display in the result.
Zwracane wartości
Returns an array of database handlers. If full_info
is set to TRUE, the array will be associative with the handlers names as
keys, and their version information as value. Otherwise, the result will be
an indexed array of handlers names.
Informacja:
When the internal cdb library is used you will see cdb and cdb_make.
Przykłady
Przykład #1 dba_handlers() Example
<?php
echo "Available DBA handlers:\n";
foreach (dba_handlers(true) as $handler_name => $handler_version) {
// clean the versions
$handler_version = str_replace('$', '', $handler_version);
echo " - $handler_name: $handler_version\n";
}
?>
Powyższy przykład wyświetli coś podobnego do:
Available DBA handlers: - cdb: 0.75, Revision: 1.3.2.3 - cdb_make: 0.75, Revision: 1.2.2.4 - db2: Sleepycat Software: Berkeley DB 2.7.7: (08/20/99) - inifile: 1.0, Revision: 1.6.2.3 - flatfile: 1.0, Revision: 1.5.2.4
dba_insert
(PHP 4, PHP 5)
dba_insert — Insert entry
Opis
$key
, string $value
, resource $handle
)
dba_insert() inserts the entry described with
key and value into the
database.
Parametry
-
key -
The key of the entry to be inserted. If this key already exist in the database, this function will fail. Use dba_replace() if you need to replace an existent key.
-
value -
The value to be inserted.
-
handle -
The database handler, returned by dba_open() or dba_popen().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- dba_exists() - Check whether key exists
- dba_delete() - Delete DBA entry specified by key
- dba_fetch() - Fetch data specified by key
- dba_replace() - Replace or insert entry
dba_key_split
(PHP 5)
dba_key_split — Splits a key in string representation into array representation
Opis
dba_key_split() splits a key (string representation) into an array representation.
Parametry
-
key -
The key in string representation.
Zwracane wartości
Returns an array of the form array(0 => group, 1 =>
value_name). This function will return FALSE if
key is NULL or FALSE.
Zobacz też:
- dba_firstkey() - Fetch first key
- dba_nextkey() - Fetch next key
- dba_fetch() - Fetch data specified by key
dba_list
(PHP 4 >= 4.3.0, PHP 5)
dba_list — List all open database files
Opis
dba_list() list all open database files.
Zwracane wartości
An associative array, in the form resourceid => filename.
dba_nextkey
(PHP 4, PHP 5)
dba_nextkey — Fetch next key
Opis
$handle
)dba_nextkey() returns the next key of the database and advances the internal key pointer.
Zwracane wartości
Returns the key on success lub FALSE w przypadku niepowodzenia.
Zobacz też:
- dba_firstkey() - Fetch first key
- dba_key_split() - Splits a key in string representation into array representation
- Example 2 in the DBA examples
dba_open
(PHP 4, PHP 5)
dba_open — Open database
Opis
dba_open() establishes a database instance for
path with mode using
handler.
Parametry
-
path -
Commonly a regular path in your filesystem.
-
mode -
It is r for read access, w for read/write access to an already existing database, c for read/write access and database creation if it doesn't currently exist, and n for create, truncate and read/write access. The database is created in BTree mode, other modes (like Hash or Queue) are not supported.
Additionally you can set the database lock method with the next char. Use l to lock the database with a .lck file or d to lock the databasefile itself. It is important that all of your applications do this consistently.
If you want to test the access and do not want to wait for the lock you can add t as third character. When you are absolutely sure that you do not require database locking you can do so by using - instead of l or d. When none of d, l or - is used, dba will lock on the database file as it would with d.
Informacja:
There can only be one writer for one database file. When you use dba on a web server and more than one request requires write operations they can only be done one after another. Also read during write is not allowed. The dba extension uses locks to prevent this. See the following table:
DBA locking already open mode= "rl"mode= "rlt"mode= "wl"mode= "wlt"mode= "rd"mode= "rdt"mode= "wd"mode= "wdt"not open ok ok ok ok ok ok ok ok mode= "rl"ok ok wait false illegal illegal illegal illegal mode= "wl"wait false wait false illegal illegal illegal illegal mode= "rd"illegal illegal illegal illegal ok ok wait false mode= "wd"illegal illegal illegal illegal wait false wait false - ok: the second call will be successfull.
- wait: the second call waits until dba_close() is called for the first.
- false: the second call returns false.
- illegal: you must not mix "l" and "d" modifiers for
modeparameter.
-
handler -
The name of the handler which shall be used for accessing
path. It is passed all optional parameters given to dba_open() and can act on behalf of them.
Zwracane wartości
Returns a positive handle on success lub FALSE w przypadku niepowodzenia.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.3.0 | It's possible to open database files over network connection. However in cases a socket connection will be used (as with http or ftp) the connection will be locked instead of the resource itself. This is important to know since in such cases locking is simply ignored on the resource and other solutions have to be found. |
| 4.3.0 |
Locking and the mode modifiers "l", "d", "-"
and "t" were added.
In previous PHP versions, you must use semaphores to guard against
simultaneous database access for any database handler with the exception
of GDBM. See System V semaphore support.
|
| before 4.3.5 | open mode 'c' is broken for several internal handlers and truncates the database instead of appending data to an existent database. Also dbm and ndbm fail on mode 'c' in typical configurations (this cannot be fixed). |
dba_optimize
(PHP 4, PHP 5)
dba_optimize — Optimize database
Opis
$handle
)dba_optimize() optimizes the underlying database.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
dba_popen
(PHP 4, PHP 5)
dba_popen — Open database persistently
Opis
dba_popen() establishes a persistent database instance
for path with mode using
handler.
Parametry
-
path -
Commonly a regular path in your filesystem.
-
mode -
It is r for read access, w for read/write access to an already existing database, c for read/write access and database creation if it doesn't currently exist, and n for create, truncate and read/write access.
-
handler -
The name of the handler which shall be used for accessing
path. It is passed all optional parameters given to dba_popen() and can act on behalf of them.
Zwracane wartości
Returns a positive handle on success lub FALSE w przypadku niepowodzenia.
dba_replace
(PHP 4, PHP 5)
dba_replace — Replace or insert entry
Opis
$key
, string $value
, resource $handle
)
dba_replace() replaces or inserts the entry described
with key and value into the
database specified by handle.
Parametry
-
key -
The key of the entry to be replaced.
-
value -
The value to be replaced.
-
handle -
The database handler, returned by dba_open() or dba_popen().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- dba_exists() - Check whether key exists
- dba_delete() - Delete DBA entry specified by key
- dba_fetch() - Fetch data specified by key
- dba_insert() - Insert entry
dba_sync
(PHP 4, PHP 5)
dba_sync — Synchronize database
Opis
$handle
)dba_sync() synchronizes the database. This will probably trigger a physical write to the disk, if supported.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Spis treści
- dba_close — Close a DBA database
- dba_delete — Delete DBA entry specified by key
- dba_exists — Check whether key exists
- dba_fetch — Fetch data specified by key
- dba_firstkey — Fetch first key
- dba_handlers — List all the handlers available
- dba_insert — Insert entry
- dba_key_split — Splits a key in string representation into array representation
- dba_list — List all open database files
- dba_nextkey — Fetch next key
- dba_open — Open database
- dba_optimize — Optimize database
- dba_popen — Open database persistently
- dba_replace — Replace or insert entry
- dba_sync — Synchronize database
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Przykłady
- DBA Funkcje
- dba_close — Close a DBA database
- dba_delete — Delete DBA entry specified by key
- dba_exists — Check whether key exists
- dba_fetch — Fetch data specified by key
- dba_firstkey — Fetch first key
- dba_handlers — List all the handlers available
- dba_insert — Insert entry
- dba_key_split — Splits a key in string representation into array representation
- dba_list — List all open database files
- dba_nextkey — Fetch next key
- dba_open — Open database
- dba_optimize — Optimize database
- dba_popen — Open database persistently
- dba_replace — Replace or insert entry
- dba_sync — Synchronize database
dbx
Wstęp
The dbx module is a database abstraction layer (db 'X', where 'X' is a supported database). The dbx functions allow you to access all supported databases using a single calling convention. The dbx-functions themselves do not interface directly to the databases, but interface to the modules that are used to support these databases.
Informacja:
To rozszerzenie zostało przeniesione do repozytorium » PECL i nie jest rozprowadzane z PHP od wersji 5.1.0.
Instalacja/Konfiguracja
Spis treści
Wymagania
To be able to use a database with the dbx-module, the module must be either linked or loaded into PHP, and the database module must be supported by the dbx-module. Currently, the following databases are supported, but others will follow:
- FrontBase (available from PHP 4.1.0).
- Microsoft SQL Server
- MySQL
- ODBC
- PostgreSQL
- Sybase-CT (available from PHP 4.2.0).
- Oracle (oci8) (available from PHP 4.3.0).
- SQLite (PHP 5).
Documentation for adding additional database support to dbx can be found at » http://www.guidance.nl/php/dbx/doc/.
Instalacja
In order to have these functions available, you must compile PHP with dbx support by using the --enable-dbx option and all options for the databases that will be used, e.g. for MySQL you must also specify --with-mysql=[DIR] . To get other supported databases to work with the dbx-module refer to their specific documentation.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| dbx.colnames_case | "unchanged" | PHP_INI_SYSTEM | Available since PHP 4.3.0. Removed in PHP 5.1.0. |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
dbx.colnames_casestring -
Columns names can be returned "unchanged" or converted to "uppercase" or "lowercase". This directive can be overridden with a flag to dbx_query().
Typy zasobów
There are two resource types used in the dbx module. The first one is the link-object for a database connection, the second a result-object which holds the result of a query.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
-
DBX_MYSQL(integer) -
DBX_ODBC(integer) -
DBX_PGSQL(integer) -
DBX_MSSQL(integer) -
DBX_FBSQL(integer) -
DBX_OCI8(integer) (available from PHP 4.3.0) -
DBX_SYBASECT(integer) -
DBX_SQLITE(integer) (PHP 5) -
DBX_PERSISTENT(integer) -
DBX_RESULT_INFO(integer) -
DBX_RESULT_INDEX(integer) -
DBX_RESULT_ASSOC(integer) -
DBX_RESULT_UNBUFFERED(integer) (PHP 5) -
DBX_COLNAMES_UNCHANGED(integer) (available from PHP 4.3.0) -
DBX_COLNAMES_UPPERCASE(integer) (available from PHP 4.3.0) -
DBX_COLNAMES_LOWERCASE(integer) (available from PHP 4.3.0) -
DBX_CMP_NATIVE(integer) -
DBX_CMP_TEXT(integer) -
DBX_CMP_NUMBER(integer) -
DBX_CMP_ASC(integer) -
DBX_CMP_DESC(integer)
dbx Funkcje
dbx_close
(PHP 4 >= 4.0.6, PHP 5 <= 5.0.5, PECL dbx >= 1.1.0)
dbx_close — Close an open connection/database
Opis
$link_identifier
)Parametry
-
link_identifier -
The DBX link object to close.
Zwracane wartości
Returns 1 on success and 0 on errors.
Przykłady
Przykład #1 dbx_close() example
<?php
$link = dbx_connect(DBX_MYSQL, "localhost", "db", "username", "password")
or die("Could not connect");
echo "Connected successfully";
dbx_close($link);
?>
Notatki
Informacja:
Always refer to the module-specific documentation as well.
dbx_compare
(PHP 4 >= 4.1.0, PHP 5 <= 5.0.5, PECL dbx >= 1.1.0)
dbx_compare — Compare two rows for sorting purposes
Opis
$row_a
, array $row_b
, string $column_key
[, int $flags = DBX_CMP_ASC | DBX_CMP_NATIVE
] )dbx_compare() is a helper function for dbx_sort() to ease the make and use of the custom sorting function.
Parametry
-
row_a -
First row
-
row_b -
Second row
-
column_key -
The compared column
-
flags -
The
flagscan be set to specify comparison direction:-
DBX_CMP_ASC- ascending order -
DBX_CMP_DESC- descending order
-
DBX_CMP_NATIVE- no type conversion -
DBX_CMP_TEXT- compare items as strings -
DBX_CMP_NUMBER- compare items numerically
-
Zwracane wartości
Returns 0 if the row_a[$column_key]
is equal to row_b[$column_key], and 1
or -1 if the former is greater or is smaller than the
latter one, respectively, or vice versa if the flag
is set to DBX_CMP_DESC.
Przykłady
Przykład #1 dbx_compare() example
<?php
function user_re_order($a, $b)
{
$rv = dbx_compare($a, $b, "parentid", DBX_CMP_DESC);
if (!$rv) {
$rv = dbx_compare($a, $b, "id", DBX_CMP_NUMBER);
}
return $rv;
}
$link = dbx_connect(DBX_ODBC, "", "db", "username", "password")
or die("Could not connect");
$result = dbx_query($link, "SELECT id, parentid, description FROM table ORDER BY id");
// data in $result is now ordered by id
dbx_sort($result, "user_re_order");
// date in $result is now ordered by parentid (descending), then by id
dbx_close($link);
?>
dbx_connect
(PHP 4 >= 4.0.6, PHP 5 <= 5.0.5, PECL dbx >= 1.1.0)
dbx_connect — Open a connection/database
Opis
$module
, string $host
, string $database
, string $username
, string $password
[, int $persistent
] )Opens a connection to a database.
Parametry
-
module -
The
moduleparameter can be either a string or a constant, though the latter form is preferred. The possible values are given below, but keep in mind that they only work if the module is actually loaded.-
DBX_MYSQLor "mysql" -
DBX_ODBCor "odbc" -
DBX_PGSQLor "pgsql" -
DBX_MSSQLor "mssql" -
DBX_FBSQLor "fbsql" -
DBX_SYBASECTor "sybase_ct" -
DBX_OCI8or "oci8" -
DBX_SQLITEor "sqlite"
-
-
host -
The SQL server host
-
database -
The database name
-
username -
The username
-
password -
The password
-
persistent -
The
persistentparameter can be set toDBX_PERSISTENT, if so, a persistent connection will be created.
The host, database,
username and password
parameters are expected, but not always used depending on the connect
functions for the abstracted module.
Zwracane wartości
Returns an object on success, FALSE on error. If a connection has been
made but the database could not be selected, the connection is closed and
FALSE is returned.
The returned object has three properties:
- database
- It is the name of the currently selected database.
- handle
-
It is a valid handle for the connected database, and as such it can be used in module-specific functions (if required).
<?php
$link = dbx_connect(DBX_MYSQL, "localhost", "db", "username", "password");
mysql_close($link->handle); // dbx_close($link) would be better here
?> - module
- It is used internally by dbx only, and is actually the module number mentioned above.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.0.0 |
Introduced DBX_SQLITE.
|
| 4.3.0 |
Introduced DBX_OCI8.
|
| 4.2.0 |
Introduced DBX_SYBASECT.
|
| 4.1.0 |
Introduced DBX_FBSQL.
|
Przykłady
Przykład #1 dbx_connect() example
<?php
$link = dbx_connect(DBX_ODBC, "", "db", "username", "password", DBX_PERSISTENT)
or die("Could not connect");
echo "Connected successfully";
dbx_close($link);
?>
Notatki
Informacja:
Always refer to the module-specific documentation as well.
dbx_error
(PHP 4 >= 4.0.6, PHP 5 <= 5.0.5, PECL dbx >= 1.1.0)
dbx_error — Report the error message of the latest function call in the module
Opis
$link_identifier
)dbx_error() returns the last error message.
Zwracane wartości
Returns a string containing the error message from the last function call
of the abstracted module (e.g. mysql module). If there are multiple
connections in the same module, just the last error is given. If there are
connections on different modules, the latest error is returned for the
module specified by the link_identifier parameter.
Przykłady
Przykład #1 dbx_error() example
<?php
$link = dbx_connect(DBX_MYSQL, "localhost", "db", "username", "password")
or die("Could not connect");
$result = dbx_query($link, "select id from non_existing_table");
if ($result == 0) {
echo dbx_error($link);
}
dbx_close($link);
?>
Notatki
Informacja:
Always refer to the module-specific documentation as well.
The error message for Microsoft SQL Server is actually the result of the mssql_get_last_message() function.
The error message for Oracle (oci8) is not implemented yet.
dbx_escape_string
(PHP 4 >= 4.3.0, PHP 5 <= 5.0.5, PECL dbx >= 1.1.0)
dbx_escape_string — Escape a string so it can safely be used in an sql-statement
Opis
$link_identifier
, string $text
)Escape the given string so that it can safely be used in an sql-statement.
Zwracane wartości
Returns the text, escaped where necessary (such as quotes, backslashes
etc). On error, NULL is returned.
Przykłady
Przykład #1 dbx_escape_string() example
<?php
$link = dbx_connect(DBX_MYSQL, "localhost", "db", "username", "password")
or die("Could not connect");
$text = dbx_escape_string($link, "It\'s quoted and backslashed (\\).");
$result = dbx_query($link, "insert into tbl (txt) values ('" . $text . "')");
if ($result == 0) {
echo dbx_error($link);
}
dbx_close($link);
?>
dbx_fetch_row
(PHP 5 <= 5.0.5, PECL dbx >= 1.1.0)
dbx_fetch_row — Fetches rows from a query-result that had the
DBX_RESULT_UNBUFFERED flag set
Opis
dbx_fetch_row() fetches rows from a result identifier
that had the DBX_RESULT_UNBUFFERED flag set.
When the DBX_RESULT_UNBUFFERED is not set in the
query, dbx_fetch_row() will fail as all rows have
already been fetched into the results data property.
As a side effect, the rows property of the query-result object is incremented for each successful call to dbx_fetch_row().
Zwracane wartości
Returns an object on success that contains the same information as any row would have in the dbx_query() result data property, including columns accessible by index or fieldname when the flags for dbx_query() were set that way.
Upon failure, returns 0 (e.g. when no more rows are available).
Przykłady
Przykład #1 How to handle the returned value
<?php
$result = dbx_query($link, 'SELECT id, parentid, description FROM table', DBX_RESULT_UNBUFFERED);
echo "<table>\n";
while ($row = dbx_fetch_row($result)) {
echo "<tr>\n";
foreach ($row as $field) {
echo "<td>$field</td>";
}
echo "</tr>\n";
}
echo "</table>\n";
?>
dbx_query
(PHP 4 >= 4.0.6, PHP 5 <= 5.0.5, PECL dbx >= 1.1.0)
dbx_query — Send a query and fetch all results (if any)
Opis
Sends a query and fetch all results.
Parametry
-
link_identifier -
The DBX link object returned by dbx_connect()
-
sql_statement -
SQL statement.
Data inside the query should be properly escaped.
-
flags -
The
flagsparameter is used to control the amount of information that is returned. It may be any combination of the following constants with the bitwise OR operator (|). The DBX_COLNAMES_* flags override the dbx.colnames_case setting from php.ini.-
DBX_RESULT_INDEX -
It is always set, that is, the returned object
has a data property which is a 2 dimensional
array indexed numerically. For example, in the expression
data[2][3] 2 stands for the row
(or record) number and 3 stands for the column
(or field) number. The first row and column are indexed at 0.
If
DBX_RESULT_ASSOCis also specified, the returning object contains the information related toDBX_RESULT_INFOtoo, even if it was not specified. -
DBX_RESULT_INFO - It provides info about columns, such as field names and field types.
-
DBX_RESULT_ASSOC - It effects that the field values can be accessed with the respective column names used as keys to the returned object's data property. Associated results are actually references to the numerically indexed data, so modifying data[0][0] causes that data[0]['field_name_for_first_column'] is modified as well.
-
DBX_RESULT_UNBUFFERED - This flag will not create the data property, and the rows property will initially be 0. Use this flag for large datasets, and use dbx_fetch_row() to retrieve the results row by row. The dbx_fetch_row() function will return rows that are conformant to the flags set with this query. Incidentally, it will also update the rows each time it is called.
-
DBX_COLNAMES_UNCHANGED - The case of the returned column names will not be changed.
-
DBX_COLNAMES_UPPERCASE - The case of the returned column names will be changed to uppercase.
-
DBX_COLNAMES_LOWERCASE - The case of the returned column names will be changed to lowercase.
DBX_RESULT_INDEXis always used, regardless of the actual value offlagsparameter. This means that only the following combinations are effective:-
DBX_RESULT_INDEX -
DBX_RESULT_INDEX|DBX_RESULT_INFO -
DBX_RESULT_INDEX|DBX_RESULT_INFO|DBX_RESULT_ASSOC- this is the default, ifflagsis not specified.
-
Zwracane wartości
dbx_query() returns an object or 1
on success, and 0 on failure. The result object is
returned only if the query given in sql_statement
produces a result set (i.e. a SELECT query, even if the result set is
empty).
The returned object has four or five
properties depending on flags:
- handle
-
It is a valid handle for the connected database, and as such it can be used in module specific functions (if required).
<?php
$result = dbx_query($link, "SELECT id FROM table");
mysql_field_len($result->handle, 0);
?> - cols and rows
-
These contain the number of columns (or fields) and rows (or records) respectively.
<?php
$result = dbx_query($link, 'SELECT id FROM table');
echo $result->rows; // number of records
echo $result->cols; // number of fields
?> - info (optional)
-
It is returned only if either
DBX_RESULT_INFOorDBX_RESULT_ASSOCis specified in theflagsparameter. It is a 2 dimensional array, that has two named rows (name and type) to retrieve column information.Przykład #1 lists each field's name and type
<?php
$result = dbx_query($link, 'SELECT id FROM table',
DBX_RESULT_INDEX | DBX_RESULT_INFO);
for ($i = 0; $i < $result->cols; $i++ ) {
echo $result->info['name'][$i] . "\n";
echo $result->info['type'][$i] . "\n";
}
?> - data
-
This property contains the actual resulting data, possibly associated
with column names as well depending on
flags. IfDBX_RESULT_ASSOCis set, it is possible to use $result->data[2]["field_name"].Przykład #2 outputs the content of data property into HTML table
<?php
$result = dbx_query($link, 'SELECT id, parentid, description FROM table');
echo "<table>\n";
foreach ($result->data as $row) {
echo "<tr>\n";
foreach ($row as $field) {
echo "<td>$field</td>";
}
echo "</tr>\n";
}
echo "</table>\n";
?>Przykład #3 How to handle UNBUFFERED queries
<?php
$result = dbx_query ($link, 'SELECT id, parentid, description FROM table', DBX_RESULT_UNBUFFERED);
echo "<table>\n";
while ($row = dbx_fetch_row($result)) {
echo "<tr>\n";
foreach ($row as $field) {
echo "<td>$field</td>";
}
echo "</tr>\n";
}
echo "</table>\n";
?>
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.0.0 |
Introduced DBX_RESULT_UNBUFFERED.
|
| 4.3.0 |
Introduced DBX_COLNAMES_UNCHANGED,
DBX_COLNAMES_UPPERCASE, and
DBX_COLNAMES_LOWERCASE.
|
Przykłady
Przykład #4 How to handle the returned value
<?php
$link = dbx_connect(DBX_ODBC, "", "db", "username", "password")
or die("Could not connect");
$result = dbx_query($link, 'SELECT id, parentid, description FROM table');
if (is_object($result) ) {
// ... do some stuff here, see detailed examples below ...
// first, print out field names and types
// then, draw a table filled with the returned field values
} else {
exit("Query failed");
}
dbx_close($link);
?>
Notatki
Informacja:
Always refer to the module-specific documentation as well.
Column names for queries on an Oracle database are returned in lowercase.
Zobacz też:
- dbx_escape_string() - Escape a string so it can safely be used in an sql-statement
- dbx_fetch_row() - Fetches rows from a query-result that had the DBX_RESULT_UNBUFFERED flag set
- dbx_connect() - Open a connection/database
dbx_sort
(PHP 4 >= 4.0.6, PHP 5 <= 5.0.5, PECL dbx >= 1.1.0)
dbx_sort — Sort a result from a dbx_query by a custom sort function
Opis
$result
, string $user_compare_function
)Sort a result from a dbx_query() call with a custom sort function.
Parametry
-
result -
A result set returned by dbx_query().
-
user_compare_function -
The user-defined comparison function. It must accept two arguments and return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 dbx_sort() example
<?php
function user_re_order($a, $b)
{
$rv = dbx_compare($a, $b, "parentid", DBX_CMP_DESC);
if (!$rv) {
$rv = dbx_compare($a, $b, "id", DBX_CMP_NUMBER);
}
return $rv;
}
$link = dbx_connect(DBX_ODBC, "", "db", "username", "password")
or die("Could not connect");
$result = dbx_query($link, "SELECT id, parentid, description FROM tbl ORDER BY id");
// data in $result is now ordered by id
dbx_sort($result, "user_re_order");
// data in $result is now ordered by parentid (descending), then by id
dbx_close($link);
?>
Notatki
Informacja:
It is always better to use ORDER BY SQL clause instead of dbx_sort() if possible.
Spis treści
- dbx_close — Close an open connection/database
- dbx_compare — Compare two rows for sorting purposes
- dbx_connect — Open a connection/database
- dbx_error — Report the error message of the latest function call in the module
- dbx_escape_string — Escape a string so it can safely be used in an sql-statement
- dbx_fetch_row — Fetches rows from a query-result that had the DBX_RESULT_UNBUFFERED flag set
- dbx_query — Send a query and fetch all results (if any)
- dbx_sort — Sort a result from a dbx_query by a custom sort function
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- dbx Funkcje
- dbx_close — Close an open connection/database
- dbx_compare — Compare two rows for sorting purposes
- dbx_connect — Open a connection/database
- dbx_error — Report the error message of the latest function call in the module
- dbx_escape_string — Escape a string so it can safely be used in an sql-statement
- dbx_fetch_row — Fetches rows from a query-result that had the DBX_RESULT_UNBUFFERED flag set
- dbx_query — Send a query and fetch all results (if any)
- dbx_sort — Sort a result from a dbx_query by a custom sort function
ODBC (Unified)
Wstęp
In addition to normal ODBC support, the Unified ODBC functions in PHP allow you to access several databases that have borrowed the semantics of the ODBC API to implement their own API. Instead of maintaining multiple database drivers that were all nearly identical, these drivers have been unified into a single set of ODBC functions.
The following databases are supported by the Unified ODBC functions: » Adabas D, » IBM DB2, » iODBC, » Solid, and » Sybase SQL Anywhere.
Informacja:
With the exception of iODBC, there is no ODBC involved when connecting to the above databases. The functions that you use to speak natively to them just happen to share the same names and syntax as the ODBC functions. However, building PHP with iODBC support enables you to use any ODBC-compliant drivers with your PHP applications. More information on iODBC, is available at » www.iodbc.org with the alternative unixODBC available at » www.unixodbc.org.
Instalacja/Konfiguracja
Spis treści
Wymagania
To access any of the supported databases you need to have the required libraries installed.
Instalacja
- --with-adabas[=DIR]
-
Dołącz obsługę Adabas D. DIR jest katalogiem gdzie została zainstalowana baza Adabas, domyślnie /usr/local.
- --with-sapdb[=DIR]
-
Dołącz obsługę SAP DB. DIR jest katalogiem gdzie została zainstalowana baza, domyślnie /usr/local.
- --with-solid[=DIR]
-
Dołącz obsługę Solid. DIR to katalog instalacji Solid, domyślnie /usr/local/solid
- --with-ibm-db2[=DIR]
-
Dołącz obsługę IBM DB2. DIR to katalog instalcji DB2, domyślnie /home/db2inst1/sqllib.
- --with-empress[=DIR]
-
Dołącz obsługę Empress. DIR to katalog instalacji Empress, domyślnie $EMPRESSPATH. Od PHP 4, ta opcja dotyczy tylko Empress w wersjach 8.60 i nowszych.
- --with-empress-bcs[=DIR]
-
Dołącz obsługę "Empress Local Access". DIR to katalog instalacji Empress, domyślnie $EMPRESSPATH. Od PHP 4, ta opcja dotyczy tylko Empress w wersjach 8.60 i nowszych.
- --with-birdstep[=DIR]
-
Dołącz obsługę Birdstep. DIR to katalog instalacji Birdstep, domyślnie /usr/local/birdstep.
- --with-custom-odbc[=DIR]
-
Dołącza obsługę niestandardowej biblioteki ODBC. DIR wskazuje na główny katalog instalacji, domyślnie /usr/local. Upewnij się, że zdefiniowałeś CUSTOM_ODBC_LIBS i masz plik odbc.h w katalogach include. Na przykład powinieneś zdefiniować następujące opcje w QNX dla bazy danych Sybase SQL Anywhere 5.5.00, zanim uruchomisz skrypt konfiguracyjny:
CPPFLAGS="-DODBC_QNX -DSQLANY_BUG" LDFLAGS=-lunix CUSTOM_ODBC_LIBS="-ldblib -lodbc".
- --with-iodbc[=DIR]
-
Dołącz obsługę iODBC. DIR jest to katalog instalacji iODBC, domyślnie /usr/local.
- --with-esoob[=DIR]
-
Dołącz obsługę Easysoft OOB. DIR to katalog instalacji OOB, domyślnie /usr/local/easysoft/oob/client.
- --with-unixODBC[=DIR]
-
Dołącz obsługę unixODBC. DIR to katalog instalacji unixODBC, domyślnie /usr/local.
- --with-openlink[=DIR]
-
Dołącz obsługę OpenLink ODBC. DIR to katalog instalacji OpenLink, domyślnie /usr/local. Opcja jest taka sama jak iODBC.
- --with-dbmaker[=DIR]
-
Dołącz obsługę DBMaker. DIR to katalog instalacji DBMakera domyślnie tam, gdzie została zainstalowana najnowsza wersja DBMakera (np. /home/dbmaker/3.6).
PHP w wersji dla systemów Windows posiada wbudowaną obsługę dla tego rozszerzenia. Nie trzeba ładować żadnych dodatkowych rozszerzeń, aby używać tych funkcji.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| odbc.default_db * | NULL | PHP_INI_ALL | |
| odbc.default_user * | NULL | PHP_INI_ALL | |
| odbc.default_pw * | NULL | PHP_INI_ALL | |
| odbc.allow_persistent | "1" | PHP_INI_SYSTEM | |
| odbc.check_persistent | "1" | PHP_INI_SYSTEM | |
| odbc.max_persistent | "-1" | PHP_INI_SYSTEM | |
| odbc.max_links | "-1" | PHP_INI_SYSTEM | |
| odbc.defaultlrl | "4096" | PHP_INI_ALL | |
| odbc.defaultbinmode | "1" | PHP_INI_ALL | |
| odbc.default_cursortype | "3" | PHP_INI_ALL | Available as of PHP 5.3.0 |
Szczegóły i definicje dotyczące działania PHP_INI_* znajdują się w rozdziale Where a configuration setting may be set.Informacja: Entries marked with * are not implemented yet.
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
odbc.default_dbstring -
ODBC data source to use if none is specified in odbc_connect() or odbc_pconnect().
-
odbc.default_userstring -
User name to use if none is specified in odbc_connect() or odbc_pconnect().
-
odbc.default_pwstring -
Password to use if none is specified in odbc_connect() or odbc_pconnect().
-
odbc.allow_persistentboolean -
Whether to allow persistent ODBC connections.
-
odbc.check_persistentboolean -
Check that a connection is still valid before reuse.
-
odbc.max_persistentinteger -
The maximum number of persistent ODBC connections per process.
-
odbc.max_linksinteger -
The maximum number of ODBC connections per process, including persistent connections.
-
odbc.defaultlrlinteger -
Handling of LONG fields. Specifies the number of bytes returned to variables.
Jeśli użyty zostanie typ integer, wartość zostanie liczona w bajtach. Można także użyć notacji skrótowej opisanej w FAQ. -
odbc.defaultbinmodeinteger -
Handling of binary data.
-
odbc.default_cursortypeinteger -
Controls the ODBC cursor model. Possible values are
SQL_CURSOR_FORWARD_ONLY,SQL_CURSOR_KEYSET_DRIVEN,SQL_CURSOR_DYNAMICandSQL_CURSOR_STATIC(default).
Typy zasobów
This extension defines two resource types: an ODBC connection identifier and an ODBC result identifier.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
-
ODBC_TYPE(integer) -
ODBC_BINMODE_PASSTHRU(integer) -
ODBC_BINMODE_RETURN(integer) -
ODBC_BINMODE_CONVERT(integer) -
SQL_ODBC_CURSORS(integer) -
SQL_CUR_USE_DRIVER(integer) -
SQL_CUR_USE_IF_NEEDED(integer) -
SQL_CUR_USE_ODBC(integer) -
SQL_CONCURRENCY(integer) -
SQL_CONCUR_READ_ONLY(integer) -
SQL_CONCUR_LOCK(integer) -
SQL_CONCUR_ROWVER(integer) -
SQL_CONCUR_VALUES(integer) -
SQL_CURSOR_TYPE(integer) -
SQL_CURSOR_FORWARD_ONLY(integer) -
SQL_CURSOR_KEYSET_DRIVEN(integer) -
SQL_CURSOR_DYNAMIC(integer) -
SQL_CURSOR_STATIC(integer) -
SQL_KEYSET_SIZE(integer) -
SQL_CHAR(integer) -
SQL_VARCHAR(integer) -
SQL_LONGVARCHAR(integer) -
SQL_DECIMAL(integer) -
SQL_NUMERIC(integer) -
SQL_BIT(integer) -
SQL_TINYINT(integer) -
SQL_SMALLINT(integer) -
SQL_INTEGER(integer) -
SQL_BIGINT(integer) -
SQL_REAL(integer) -
SQL_FLOAT(integer) -
SQL_DOUBLE(integer) -
SQL_BINARY(integer) -
SQL_VARBINARY(integer) -
SQL_LONGVARBINARY(integer) -
SQL_DATE(integer) -
SQL_TIME(integer) -
SQL_TIMESTAMP(integer) -
SQL_TYPE_DATE(integer) -
SQL_TYPE_TIME(integer) -
SQL_TYPE_TIMESTAMP(integer) -
SQL_BEST_ROWID(integer) -
SQL_ROWVER(integer) -
SQL_SCOPE_CURROW(integer) -
SQL_SCOPE_TRANSACTION(integer) -
SQL_SCOPE_SESSION(integer) -
SQL_NO_NULLS(integer) -
SQL_NULLABLE(integer) -
SQL_INDEX_UNIQUE(integer) -
SQL_INDEX_ALL(integer) -
SQL_ENSURE(integer) -
SQL_QUICK(integer)
ODBC Funkcje
odbc_autocommit
(PHP 4, PHP 5)
odbc_autocommit — Toggle autocommit behaviour
Opis
Toggles autocommit behaviour.
By default, auto-commit is on for a connection. Disabling auto-commit is equivalent with starting a transaction.
Parametry
-
connection_id -
Identyfikator połączenia ODBC. Zobacz opis funkcji odbc_connect() aby poznać szczegóły.
-
OnOff -
If
OnOffisTRUE, auto-commit is enabled, if it isFALSEauto-commit is disabled.
Zwracane wartości
Without the OnOff parameter, this function returns
auto-commit status for connection_id. Non-zero is
returned if auto-commit is on, 0 if it is off, or FALSE if an error
occurs.
If OnOff is set, this function returns TRUE on
success and FALSE on failure.
odbc_binmode
(PHP 4, PHP 5)
odbc_binmode — Handling of binary column data
Opis
$result_id
, int $mode
)Enables handling of binary column data. ODBC SQL types affected are BINARY, VARBINARY, and LONGVARBINARY.
When binary SQL data is converted to character C data, each byte (8 bits) of source data is represented as two ASCII characters. These characters are the ASCII character representation of the number in its hexadecimal form. For example, a binary 00000001 is converted to "01" and a binary 11111111 is converted to "FF".
| binmode | longreadlen | result |
|---|---|---|
ODBC_BINMODE_PASSTHRU |
0 | passthru |
ODBC_BINMODE_RETURN |
0 | passthru |
ODBC_BINMODE_CONVERT |
0 | passthru |
ODBC_BINMODE_PASSTHRU |
0 | passthru |
ODBC_BINMODE_PASSTHRU |
>0 | passthru |
ODBC_BINMODE_RETURN |
>0 | return as is |
ODBC_BINMODE_CONVERT |
>0 | return as char |
If odbc_fetch_into() is used, passthru means that an empty string is returned for these columns.
Parametry
-
result_id -
The result identifier.
If
result_idis 0, the settings apply as default for new results.Informacja: Default for longreadlen is 4096 and
modedefaults to ODBC_BINMODE_RETURN. Handling of binary long columns is also affected by odbc_longreadlen(). -
mode -
Possible values for
modeare:-
ODBC_BINMODE_PASSTHRU: Passthru BINARY data -
ODBC_BINMODE_RETURN: Return as is -
ODBC_BINMODE_CONVERT: Convert to char and return
-
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
odbc_close_all
(PHP 4, PHP 5)
odbc_close_all — Close all ODBC connections
Opis
odbc_close_all() will close down all connections to database server(s).
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Nie jest zwracana żadna wartość.
Notatki
Informacja:
This function will fail if there are open transactions on a connection. This connection will remain open in this case.
odbc_close
(PHP 4, PHP 5)
odbc_close — Close an ODBC connection
Opis
$connection_id
)Closes down the connection to the database server.
Parametry
-
connection_id -
Identyfikator połączenia ODBC. Zobacz opis funkcji odbc_connect() aby poznać szczegóły.
Zwracane wartości
Nie jest zwracana żadna wartość.
Notatki
Informacja:
This function will fail if there are open transactions on this connection. The connection will remain open in this case.
odbc_columnprivileges
(PHP 4, PHP 5)
odbc_columnprivileges — Lists columns and associated privileges for the given table
Opis
$connection_id
, string $qualifier
, string $owner
, string $table_name
, string $column_name
)Lists columns and associated privileges for the given table.
Parametry
-
connection_id -
Identyfikator połączenia ODBC. Zobacz opis funkcji odbc_connect() aby poznać szczegóły.
-
qualifier -
The qualifier.
-
owner -
The owner.
-
table_name -
The table name.
-
column_name -
The
column_nameargument accepts search patterns ('%' to match zero or more characters and '_' to match a single character).
The owner, table_name, and
column_name accept search patterns ('%' to match
zero or more characters and '_' to match a single character).
Zwracane wartości
Returns an ODBC result identifier lub FALSE w przypadku niepowodzenia.
This result identifier can be used to fetch a list of columns and
associated privileges.
The result set has the following columns:
- TABLE_QUALIFIER
- TABLE_OWNER
- TABLE_NAME
- GRANTOR
- GRANTEE
- PRIVILEGE
- IS_GRANTABLE
The result set is ordered by TABLE_QUALIFIER, TABLE_OWNER and TABLE_NAME.
odbc_columns
(PHP 4, PHP 5)
odbc_columns — Lists the column names in specified tables
Opis
$connection_id
[, string $qualifier
[, string $schema
[, string $table_name
[, string $column_name
]]]] )Lists all columns in the requested range.
Parametry
-
connection_id -
Identyfikator połączenia ODBC. Zobacz opis funkcji odbc_connect() aby poznać szczegóły.
-
qualifier -
The qualifier.
-
schema -
The owner.
-
table_name -
The table name.
-
column_name -
The column name.
The schema, table_name, and
column_name accept search patterns ('%' to match
zero or more characters and '_' to match a single character).
Zwracane wartości
Returns an ODBC result identifier lub FALSE w przypadku niepowodzenia.
The result set has the following columns:
- TABLE_QUALIFIER
- TABLE_SCHEM
- TABLE_NAME
- COLUMN_NAME
- DATA_TYPE
- TYPE_NAME
- PRECISION
- LENGTH
- SCALE
- RADIX
- NULLABLE
- REMARKS
The result set is ordered by TABLE_QUALIFIER, TABLE_SCHEM and TABLE_NAME.
Zobacz też:
- odbc_columnprivileges() - Lists columns and associated privileges for the given table to retrieve associated privileges
odbc_commit
(PHP 4, PHP 5)
odbc_commit — Commit an ODBC transaction
Opis
$connection_id
)Commits all pending transactions on the connection.
Parametry
-
connection_id -
Identyfikator połączenia ODBC. Zobacz opis funkcji odbc_connect() aby poznać szczegóły.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
odbc_connect
(PHP 4, PHP 5)
odbc_connect — Connect to a datasource
Opis
$dsn
, string $user
, string $password
[, int $cursor_type
] )The connection id returned by this functions is needed by other ODBC functions. You can have multiple connections open at once as long as they either use different db or different credentials.
With some ODBC drivers, executing a complex stored procedure may fail with an error similar to: "Cannot open a cursor on a stored procedure that has anything other than a single select statement in it". Using SQL_CUR_USE_ODBC may avoid that error. Also, some drivers don't support the optional row_number parameter in odbc_fetch_row(). SQL_CUR_USE_ODBC might help in that case, too.
Parametry
-
dsn -
The database source name for the connection. Alternatively, a DSN-less connection string can be used.
-
user -
The username.
-
password -
The password.
-
cursor_type -
This sets the type of cursor to be used for this connection. This parameter is not normally needed, but can be useful for working around problems with some ODBC drivers.
The following constants are defined for cursortype:- SQL_CUR_USE_IF_NEEDED
- SQL_CUR_USE_ODBC
- SQL_CUR_USE_DRIVER
Zwracane wartości
Returns an ODBC connection id or 0 (FALSE) on
error.
Przykłady
Przykład #1 DSN-less connections
<?php
// Microsoft SQL Server using the SQL Native Client 10.0 ODBC Driver - allows connection to SQL 7, 2000, 2005 and 2008
$connection = odbc_connect("Driver={SQL Server Native Client 10.0};Server=$server;Database=$database;", $user, $password);
// Microsoft Access
$connection = odbc_connect("Driver={Microsoft Access Driver (*.mdb)};Dbq=$mdbFilename", $user, $password);
// Microsoft Excel
$excelFile = realpath('C:/ExcelData.xls');
$excelDir = dirname($excelFile);
$connection = odbc_connect("Driver={Microsoft Excel Driver (*.xls)};DriverId=790;Dbq=$excelFile;DefaultDir=$excelDir" , '', '');
?>
odbc_cursor
(PHP 4, PHP 5)
odbc_cursor — Get cursorname
Opis
$result_id
)Gets the cursorname for the given result_id.
Parametry
-
result_id -
The result identifier.
Zwracane wartości
Returns the cursor name, as a string.
odbc_data_source
(PHP 4 >= 4.3.0, PHP 5)
odbc_data_source — Returns information about a current connection
Opis
$connection_id
, int $fetch_type
)This function will return the list of available DSN (after calling it several times).
Parametry
-
connection_id -
Identyfikator połączenia ODBC. Zobacz opis funkcji odbc_connect() aby poznać szczegóły.
-
fetch_type -
The
fetch_typecan be one of two constant types:SQL_FETCH_FIRST,SQL_FETCH_NEXT. UseSQL_FETCH_FIRSTthe first time this function is called, thereafter use theSQL_FETCH_NEXT.
Zwracane wartości
Returns FALSE on error, and an array upon success.
Opis
Ta funkcja jest aliasem dla: odbc_exec().
odbc_error
(PHP 4 >= 4.0.5, PHP 5)
odbc_error — Get the last error code
Opis
$connection_id
] )Returns a six-digit ODBC state, or an empty string if there has been no errors.
Parametry
-
connection_id -
Identyfikator połączenia ODBC. Zobacz opis funkcji odbc_connect() aby poznać szczegóły.
Zwracane wartości
If connection_id is specified, the last state
of that connection is returned, else the last state of any connection
is returned.
This function returns meaningful value only if last odbc query failed
(i.e. odbc_exec() returned FALSE).
Zobacz też:
- odbc_errormsg() - Get the last error message
- odbc_exec() - Prepare and execute an SQL statement
odbc_errormsg
(PHP 4 >= 4.0.5, PHP 5)
odbc_errormsg — Get the last error message
Opis
$connection_id
] )Returns a string containing the last ODBC error message, or an empty string if there has been no errors.
Parametry
-
connection_id -
Identyfikator połączenia ODBC. Zobacz opis funkcji odbc_connect() aby poznać szczegóły.
Zwracane wartości
If connection_id is specified, the last state
of that connection is returned, else the last state of any connection
is returned.
This function returns meaningful value only if last odbc query failed
(i.e. odbc_exec() returned FALSE).
Zobacz też:
- odbc_error() - Get the last error code
- odbc_exec() - Prepare and execute an SQL statement
odbc_exec
(PHP 4, PHP 5)
odbc_exec — Prepare and execute an SQL statement
Opis
$connection_id
, string $query_string
[, int $flags
] )Sends an SQL statement to the database server.
Parametry
-
connection_id -
Identyfikator połączenia ODBC. Zobacz opis funkcji odbc_connect() aby poznać szczegóły.
-
query_string -
The SQL statement.
-
flags -
This parameter is currently not used.
Zwracane wartości
Returns an ODBC result identifier if the SQL command was executed
successfully, or FALSE on error.
Zobacz też:
- odbc_prepare() - Prepares a statement for execution
- odbc_execute() - Execute a prepared statement
odbc_execute
(PHP 4, PHP 5)
odbc_execute — Execute a prepared statement
Opis
$result_id
[, array $parameters_array
] )Executes a statement prepared with odbc_prepare().
Parametry
-
result_id -
The result id resource, from odbc_prepare().
-
parameters_array -
Parameters in
parameter_arraywill be substituted for placeholders in the prepared statement in order. Elements of this array will be converted to strings by calling this function.Any parameters in
If you wish to store a string which actually begins and ends with single quotes, you must add a space or other non-single-quote character to the beginning or end of the parameter, which will prevent the parameter from being taken as a file name. If this is not an option, then you must use another mechanism to store the string, such as executing the query directly with odbc_exec()).parameter_arraywhich start and end with single quotes will be taken as the name of a file to read and send to the database server as the data for the appropriate placeholder.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 odbc_execute() and odbc_prepare() example
In the following code, $success will only be
TRUE if all three parameters to myproc are IN parameters:
<?php
$a = 1;
$b = 2;
$c = 3;
$stmt = odbc_prepare($conn, 'CALL myproc(?,?,?)');
$success = odbc_execute($stmt, array($a, $b, $c));
?>
If you need to call a stored procedure using INOUT or OUT parameters, the recommended workaround is to use a native extension for your database (for example, mssql for MS SQL Server, or oci8 for Oracle).
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.2.0 |
File reading is now subject to tryb bezpieczny and
open-basedir restrictions
in parameters_array.
|
| 4.1.1 |
Remote files
are no longer supported in parameters_array.
|
odbc_fetch_array
(PHP 4 >= 4.0.2, PHP 5)
odbc_fetch_array — Fetch a result row as an associative array
Opis
$result
[, int $rownumber
] )Fetch an associative array from an ODBC query. See the changelog below for when this function is available.
Parametry
-
result -
The result resource from odbc_exec().
-
rownumber -
Optionally choose which row number to retrieve.
Zwracane wartości
Returns an array that corresponds to the fetched row, or FALSE if there
are no more rows.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.3.3 | This function exists when compiled with IBM DB2 or UnixODBC support. |
| 4.3.2 | This function exists when compiled for Windows. |
| 4.0.2 | This function exists when compiled with DBMaker support. |
Zobacz też:
- odbc_fetch_row() - Fetch a row
- odbc_fetch_object() - Fetch a result row as an object
- odbc_num_rows() - Number of rows in a result
odbc_fetch_into
(PHP 4, PHP 5)
odbc_fetch_into — Fetch one result row into array
Opis
$result_id
, array &$result_array
[, int $rownumber
] )Fetch one result row into array.
Parametry
Zwracane wartości
Returns the number of columns in the result;
FALSE on error.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.2.0 |
The result_array and rownumber
parameters have been swapped. This allows the rownumber to be a constant again.
|
| 4.0.6 |
The rownumber can no longer be passed in as a
constant, but rather as a variable. This again changed in 4.2.0.
|
| 4.0.5 |
The result_array parameter no longer needs to
be passed in by reference.
|
Przykłady
Przykład #1 odbc_fetch_into() examples
<?php
$rc = odbc_fetch_into($res_id, $my_array);
?>
or
<?php
$rc = odbc_fetch_into($res_id, $my_array, 2);
?>
odbc_fetch_object
(PHP 4 >= 4.0.2, PHP 5)
odbc_fetch_object — Fetch a result row as an object
Opis
$result
[, int $rownumber
] )Fetch an object from an ODBC query. See the changelog below for when this function is available.
Parametry
-
result -
The result resource from odbc_exec().
-
rownumber -
Optionally choose which row number to retrieve.
Zwracane wartości
Returns an object that corresponds to the fetched row, or FALSE if there
are no more rows.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.3.3 | This function exists when compiled with IBM DB2 or UnixODBC support. |
| 4.3.2 | This function exists when compiled for Windows. |
| 4.0.2 | This function exists when compiled with DBMaker support. |
Zobacz też:
- odbc_fetch_row() - Fetch a row
- odbc_fetch_array() - Fetch a result row as an associative array
- odbc_num_rows() - Number of rows in a result
odbc_fetch_row
(PHP 4, PHP 5)
odbc_fetch_row — Fetch a row
Opis
$result_id
[, int $row_number
] )Fetches a row of the data that was returned by odbc_do() or odbc_exec(). After odbc_fetch_row() is called, the fields of that row can be accessed with odbc_result().
Parametry
-
result_id -
The result identifier.
-
row_number -
If
row_numberis not specified, odbc_fetch_row() will try to fetch the next row in the result set. Calls to odbc_fetch_row() with and withoutrow_numbercan be mixed.To step through the result more than once, you can call odbc_fetch_row() with
row_number1, and then continue doing odbc_fetch_row() withoutrow_numberto review the result. If a driver doesn't support fetching rows by number, therow_numberparameter is ignored.
Zwracane wartości
Returns TRUE if there was a row, FALSE otherwise.
odbc_field_len
(PHP 4, PHP 5)
odbc_field_len — Get the length (precision) of a field
Opis
$result_id
, int $field_number
)Gets the length of the field referenced by number in the given result identifier.
Parametry
-
result_id -
The result identifier.
-
field_number -
The field number. Field numbering starts at 1.
Zwracane wartości
Returns the field name as a string, or FALSE on error.
Zobacz też:
- odbc_field_scale() - Get the scale of a field to get the scale of a floating point number
odbc_field_name
(PHP 4, PHP 5)
odbc_field_name — Get the columnname
Opis
$result_id
, int $field_number
)Gets the name of the field occupying the given column number in the given result identifier.
Parametry
-
result_id -
The result identifier.
-
field_number -
The field number. Field numbering starts at 1.
Zwracane wartości
Returns the field name as a string, or FALSE on error.
odbc_field_num
(PHP 4, PHP 5)
odbc_field_num — Return column number
Opis
$result_id
, string $field_name
)Gets the number of the column slot that corresponds to the named field in the given result identifier.
Parametry
-
result_id -
The result identifier.
-
field_name -
The field name.
Zwracane wartości
Returns the field number as a integer, or FALSE on error.
Field numbering starts at 1.
Opis
Ta funkcja jest aliasem dla: odbc_field_len().
Zobacz też:
- odbc_field_scale() - Get the scale of a field to get the scale of a floating point number.
odbc_field_scale
(PHP 4, PHP 5)
odbc_field_scale — Get the scale of a field
Opis
$result_id
, int $field_number
)Gets the scale of the field referenced by number in the given result identifier.
Parametry
-
result_id -
The result identifier.
-
field_number -
The field number. Field numbering starts at 1.
Zwracane wartości
Returns the field scale as a integer, or FALSE on error.
odbc_field_type
(PHP 4, PHP 5)
odbc_field_type — Datatype of a field
Opis
$result_id
, int $field_number
)Gets the SQL type of the field referenced by number in the given result identifier.
Parametry
-
result_id -
The result identifier.
-
field_number -
The field number. Field numbering starts at 1.
Zwracane wartości
Returns the field type as a string, or FALSE on error.
odbc_foreignkeys
(PHP 4, PHP 5)
odbc_foreignkeys — Retrieves a list of foreign keys
Opis
$connection_id
, string $pk_qualifier
, string $pk_owner
, string $pk_table
, string $fk_qualifier
, string $fk_owner
, string $fk_table
)Retrieves a list of foreign keys in the specified table or a list of foreign keys in other tables that refer to the primary key in the specified table
Parametry
-
connection_id -
Identyfikator połączenia ODBC. Zobacz opis funkcji odbc_connect() aby poznać szczegóły.
-
pk_qualifier -
The primary key qualifier.
-
pk_owner -
The primary key owner.
-
pk_table -
The primary key table.
-
fk_qualifier -
The foreign key qualifier.
-
fk_owner -
The foreign key owner.
-
fk_table -
The foreign key table.
Zwracane wartości
Returns an ODBC result identifier lub FALSE w przypadku niepowodzenia.
The result set has the following columns:
- PKTABLE_QUALIFIER
- PKTABLE_OWNER
- PKTABLE_NAME
- PKCOLUMN_NAME
- FKTABLE_QUALIFIER
- FKTABLE_OWNER
- FKTABLE_NAME
- FKCOLUMN_NAME
- KEY_SEQ
- UPDATE_RULE
- DELETE_RULE
- FK_NAME
- PK_NAME
If pk_table contains a table name,
odbc_foreignkeys() returns a result set
containing the primary key of the specified table and all of the
foreign keys that refer to it.
If fk_table contains a table name,
odbc_foreignkeys() returns a result set
containing all of the foreign keys in the specified table and the
primary keys (in other tables) to which they refer.
If both pk_table and
fk_table contain table names,
odbc_foreignkeys() returns the foreign keys in
the table specified in fk_table that refer
to the primary key of the table specified in
pk_table. This should be one key at most.
odbc_free_result
(PHP 4, PHP 5)
odbc_free_result — Free resources associated with a result
Opis
$result_id
)Free resources associated with a result.
odbc_free_result() only needs to be called if you are worried about using too much memory while your script is running. All result memory will automatically be freed when the script is finished.
Parametry
-
result_id -
The result identifier.
Zwracane wartości
Always returns TRUE.
Notatki
Informacja:
If auto-commit is disabled (see odbc_autocommit()) and you call odbc_free_result() before committing, all pending transactions are rolled back.
odbc_gettypeinfo
(PHP 4, PHP 5)
odbc_gettypeinfo — Retrieves information about data types supported by the data source
Opis
$connection_id
[, int $data_type
] )Retrieves information about data types supported by the data source.
Parametry
-
connection_id -
Identyfikator połączenia ODBC. Zobacz opis funkcji odbc_connect() aby poznać szczegóły.
-
data_type -
The data type, which can be used to restrict the information to a single data type.
Zwracane wartości
Returns an ODBC result identifier or
FALSE on failure.
The result set has the following columns:
- TYPE_NAME
- DATA_TYPE
- PRECISION
- LITERAL_PREFIX
- LITERAL_SUFFIX
- CREATE_PARAMS
- NULLABLE
- CASE_SENSITIVE
- SEARCHABLE
- UNSIGNED_ATTRIBUTE
- MONEY
- AUTO_INCREMENT
- LOCAL_TYPE_NAME
- MINIMUM_SCALE
- MAXIMUM_SCALE
The result set is ordered by DATA_TYPE and TYPE_NAME.
odbc_longreadlen
(PHP 4, PHP 5)
odbc_longreadlen — Handling of LONG columns
Opis
$result_id
, int $length
)Enables handling of LONG and LONGVARBINARY columns.
Parametry
-
result_id -
The result identifier.
-
length -
The number of bytes returned to PHP is controlled by the parameter length. If it is set to 0, Long column data is passed through to the client.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Notatki
Informacja:
Handling of LONGVARBINARY columns is also affected by odbc_binmode().
odbc_next_result
(PHP 4 >= 4.0.5, PHP 5)
odbc_next_result — Checks if multiple results are available
Opis
$result_id
)Checks if there are more result sets available as well as allowing access to the next result set via odbc_fetch_array(), odbc_fetch_row(), odbc_result(), etc.
Parametry
-
result_id -
The result identifier.
Zwracane wartości
Returns TRUE if there are more result sets, FALSE otherwise.
Przykłady
Przykład #1 odbc_next_result()
<?php
$r_Connection = odbc_connect($dsn, $username, $password);
$s_SQL = <<<END_SQL
SELECT 'A'
SELECT 'B'
SELECT 'C'
END_SQL;
$r_Results = odbc_exec($r_Connection, $s_SQL);
$a_Row1 = odbc_fetch_array($r_Results);
$a_Row2 = odbc_fetch_array($r_Results);
echo "Dump first result set";
var_dump($a_Row1, $a_Row2);
echo "Get second results set ";
var_dump(odbc_next_result($r_Results));
$a_Row1 = odbc_fetch_array($r_Results);
$a_Row2 = odbc_fetch_array($r_Results);
echo "Dump second result set ";
var_dump($a_Row1, $a_Row2);
echo "Get third results set ";
var_dump(odbc_next_result($r_Results));
$a_Row1 = odbc_fetch_array($r_Results);
$a_Row2 = odbc_fetch_array($r_Results);
echo "Dump third result set ";
var_dump($a_Row1, $a_Row2);
echo "Try for a fourth result set ";
var_dump(odbc_next_result($r_Results));
?>
Powyższy przykład wyświetli:
Dump first result set array(1) {
["A"]=>
string(1) "A"
}
bool(false)
Get second results set bool(true)
Dump second result set array(1) {
["B"]=>
string(1) "B"
}
bool(false)
Get third results set bool(true)
Dump third result set array(1) {
["C"]=>
string(1) "C"
}
bool(false)
Try for a fourth result set bool(false)
odbc_num_fields
(PHP 4, PHP 5)
odbc_num_fields — Number of columns in a result
Opis
$result_id
)Gets the number of fields (columns) in an ODBC result.
Zwracane wartości
Returns the number of fields, or -1 on error.
odbc_num_rows
(PHP 4, PHP 5)
odbc_num_rows — Number of rows in a result
Opis
$result_id
)Gets the number of rows in a result. For INSERT, UPDATE and DELETE statements odbc_num_rows() returns the number of rows affected. For a SELECT clause this can be the number of rows available.
Zwracane wartości
Returns the number of rows in an ODBC result. This function will return -1 on error.
Notatki
Informacja:
Using odbc_num_rows() to determine the number of rows available after a SELECT will return -1 with many drivers.
odbc_pconnect
(PHP 4, PHP 5)
odbc_pconnect — Open a persistent database connection
Opis
$dsn
, string $user
, string $password
[, int $cursor_type
] )Opens a persistent database connection.
This function is much like
odbc_connect(), except that the connection is
not really closed when the script has finished. Future requests
for a connection with the same dsn,
user, password
combination (via odbc_connect() and
odbc_pconnect()) can reuse the persistent
connection.
Parametry
See odbc_connect() for details.
Zwracane wartości
Returns an ODBC connection id or 0 (FALSE) on
error.
Notatki
Informacja: Persistent connections have no effect if PHP is used as a CGI program.
odbc_prepare
(PHP 4, PHP 5)
odbc_prepare — Prepares a statement for execution
Opis
$connection_id
, string $query_string
)Prepares a statement for execution. The result identifier can be used later to execute the statement with odbc_execute().
Some databases (such as IBM DB2, MS SQL Server, and Oracle) support stored procedures that accept parameters of type IN, INOUT, and OUT as defined by the ODBC specification. However, the Unified ODBC driver currently only supports parameters of type IN to stored procedures.
Parametry
-
connection_id -
Identyfikator połączenia ODBC. Zobacz opis funkcji odbc_connect() aby poznać szczegóły.
-
query_string -
The query string statement being prepared.
Zwracane wartości
Returns an ODBC result identifier if the SQL command was prepared
successfully. Returns FALSE on error.
Przykłady
Przykład #1 odbc_execute() and odbc_prepare() example
In the following code, $success will only be
TRUE if all three parameters to myproc are IN parameters:
<?php
$a = 1;
$b = 2;
$c = 3;
$stmt = odbc_prepare($conn, 'CALL myproc(?,?,?)');
$success = odbc_execute($stmt, array($a, $b, $c));
?>
If you need to call a stored procedure using INOUT or OUT parameters, the recommended workaround is to use a native extension for your database (for example, mssql for MS SQL Server, or oci8 for Oracle).
odbc_primarykeys
(PHP 4, PHP 5)
odbc_primarykeys — Gets the primary keys for a table
Opis
$connection_id
, string $qualifier
, string $owner
, string $table
)Returns a result identifier that can be used to fetch the column names that comprise the primary key for a table.
Parametry
-
connection_id -
Identyfikator połączenia ODBC. Zobacz opis funkcji odbc_connect() aby poznać szczegóły.
-
qualifier -
-
owner -
-
table -
Zwracane wartości
Returns an ODBC result identifier lub FALSE w przypadku niepowodzenia.
The result set has the following columns:
- TABLE_QUALIFIER
- TABLE_OWNER
- TABLE_NAME
- COLUMN_NAME
- KEY_SEQ
- PK_NAME
odbc_procedurecolumns
(PHP 4, PHP 5)
odbc_procedurecolumns — Retrieve information about parameters to procedures
Opis
$connection_id
)$connection_id
, string $qualifier
, string $owner
, string $proc
, string $column
)Retrieve information about parameters to procedures.
Parametry
-
connection_id -
Identyfikator połączenia ODBC. Zobacz opis funkcji odbc_connect() aby poznać szczegóły.
-
qualifier -
The qualifier.
-
owner -
The owner. Ten parametr przyjmuje również następujące wzorce wyszukiwania: "%" - dopasowanie oznacza brak znaków lub dowolną ilość znaków, oraz "_" - dopasowanie oznacza jeden znak.
-
proc -
The proc. Ten parametr przyjmuje również następujące wzorce wyszukiwania: "%" - dopasowanie oznacza brak znaków lub dowolną ilość znaków, oraz "_" - dopasowanie oznacza jeden znak.
-
column -
The column. Ten parametr przyjmuje również następujące wzorce wyszukiwania: "%" - dopasowanie oznacza brak znaków lub dowolną ilość znaków, oraz "_" - dopasowanie oznacza jeden znak.
Zwracane wartości
Returns the list of input and output parameters, as well as the
columns that make up the result set for the specified procedures.
Returns an ODBC result identifier lub FALSE w przypadku niepowodzenia.
The result set has the following columns:
- PROCEDURE_QUALIFIER
- PROCEDURE_OWNER
- PROCEDURE_NAME
- COLUMN_NAME
- COLUMN_TYPE
- DATA_TYPE
- TYPE_NAME
- PRECISION
- LENGTH
- SCALE
- RADIX
- NULLABLE
- REMARKS
The result set is ordered by PROCEDURE_QUALIFIER, PROCEDURE_OWNER, PROCEDURE_NAME and COLUMN_TYPE.
odbc_procedures
(PHP 4, PHP 5)
odbc_procedures — Get the list of procedures stored in a specific data source
Opis
$connection_id
)$connection_id
, string $qualifier
, string $owner
, string $name
)Lists all procedures in the requested range.
Parametry
-
connection_id -
Identyfikator połączenia ODBC. Zobacz opis funkcji odbc_connect() aby poznać szczegóły.
-
qualifier -
The qualifier.
-
owner -
The owner. Ten parametr przyjmuje również następujące wzorce wyszukiwania: "%" - dopasowanie oznacza brak znaków lub dowolną ilość znaków, oraz "_" - dopasowanie oznacza jeden znak.
-
name -
The name. Ten parametr przyjmuje również następujące wzorce wyszukiwania: "%" - dopasowanie oznacza brak znaków lub dowolną ilość znaków, oraz "_" - dopasowanie oznacza jeden znak.
Zwracane wartości
Returns an ODBC
result identifier containing the information lub FALSE w przypadku niepowodzenia.
The result set has the following columns:
- PROCEDURE_QUALIFIER
- PROCEDURE_OWNER
- PROCEDURE_NAME
- NUM_INPUT_PARAMS
- NUM_OUTPUT_PARAMS
- NUM_RESULT_SETS
- REMARKS
- PROCEDURE_TYPE
odbc_result_all
(PHP 4, PHP 5)
odbc_result_all — Print result as HTML table
Opis
$result_id
[, string $format
] )Prints all rows from a result identifier produced by odbc_exec(). The result is printed in HTML table format.
Parametry
-
result_id -
The result identifier.
-
format -
Additional overall table formatting.
Zwracane wartości
Returns the number of rows in the result or FALSE on error.
odbc_result
(PHP 4, PHP 5)
odbc_result — Get result data
Parametry
-
result_id -
The ODBC resource.
-
field -
The field name being retrieved. It can either be an integer containing the column number of the field you want; or it can be a string containing the name of the field.
Zwracane wartości
Returns the string contents of the field, FALSE on error, NULL for
NULL data, or TRUE for binary data.
Przykłady
The first call to odbc_result() returns the value of the third field in the current record of the query result. The second function call to odbc_result() returns the value of the field whose field name is "val" in the current record of the query result. An error occurs if a column number parameter for a field is less than one or exceeds the number of columns (or fields) in the current record. Similarly, an error occurs if a field with a name that is not one of the fieldnames of the table(s) that is(are) being queried.
Przykład #1 odbc_result() examples
<?php
$item_3 = odbc_result($Query_ID, 3);
$item_val = odbc_result($Query_ID, "val");
?>
Notatki
Field indices start from 1. Regarding the way binary or long column data is returned refer to odbc_binmode() and odbc_longreadlen().
odbc_rollback
(PHP 4, PHP 5)
odbc_rollback — Rollback a transaction
Opis
$connection_id
)Rolls back all pending statements on the connection.
Parametry
-
connection_id -
Identyfikator połączenia ODBC. Zobacz opis funkcji odbc_connect() aby poznać szczegóły.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
odbc_setoption
(PHP 4, PHP 5)
odbc_setoption — Adjust ODBC settings
Opis
$id
, int $function
, int $option
, int $param
)This function allows fiddling with the ODBC options for a particular connection or query result. It was written to help find work around to problems in quirky ODBC drivers. You should probably only use this function if you are an ODBC programmer and understand the effects the various options will have. You will certainly need a good ODBC reference to explain all the different options and values that can be used. Different driver versions support different options.
Because the effects may vary depending on the ODBC driver, use of this function in scripts to be made publicly available is strongly discouraged. Also, some ODBC options are not available to this function because they must be set before the connection is established or the query is prepared. However, if on a particular job it can make PHP work so your boss doesn't tell you to use a commercial product, that's all that really matters.
Parametry
-
id -
Is a connection id or result id on which to change the settings. For SQLSetConnectOption(), this is a connection id. For SQLSetStmtOption(), this is a result id.
-
function -
Is the ODBC function to use. The value should be 1 for SQLSetConnectOption() and 2 for SQLSetStmtOption().
-
option -
The option to set.
-
param -
The value for the given
option.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 odbc_setoption() examples
<?php
// 1. Option 102 of SQLSetConnectOption() is SQL_AUTOCOMMIT.
// Value 1 of SQL_AUTOCOMMIT is SQL_AUTOCOMMIT_ON.
// This example has the same effect as
// odbc_autocommit($conn, true);
odbc_setoption($conn, 1, 102, 1);
// 2. Option 0 of SQLSetStmtOption() is SQL_QUERY_TIMEOUT.
// This example sets the query to timeout after 30 seconds.
$result = odbc_prepare($conn, $sql);
odbc_setoption($result, 2, 0, 30);
odbc_execute($result);
?>
odbc_specialcolumns
(PHP 4, PHP 5)
odbc_specialcolumns — Retrieves special columns
Opis
$connection_id
, int $type
, string $qualifier
, string $owner
, string $table
, int $scope
, int $nullable
)Retrieves either the optimal set of columns that uniquely identifies a row in the table, or columns that are automatically updated when any value in the row is updated by a transaction.
Parametry
-
connection_id -
Identyfikator połączenia ODBC. Zobacz opis funkcji odbc_connect() aby poznać szczegóły.
-
type -
When the type argument is
SQL_BEST_ROWID, odbc_specialcolumns() returns the column or columns that uniquely identify each row in the table. When the type argument isSQL_ROWVER, odbc_specialcolumns() returns the column or columns in the specified table, if any, that are automatically updated by the data source when any value in the row is updated by any transaction. -
qualifier -
The qualifier.
-
owner -
The owner.
-
table -
The table.
-
scope -
The scope, which orders the result set.
-
nullable -
The nullable option.
Zwracane wartości
Returns an ODBC result identifier or FALSE on
failure.
The result set has the following columns:
- SCOPE
- COLUMN_NAME
- DATA_TYPE
- TYPE_NAME
- PRECISION
- LENGTH
- SCALE
- PSEUDO_COLUMN
odbc_statistics
(PHP 4, PHP 5)
odbc_statistics — Retrieve statistics about a table
Opis
$connection_id
, string $qualifier
, string $owner
, string $table_name
, int $unique
, int $accuracy
)Get statistics about a table and its indexes.
Parametry
-
connection_id -
Identyfikator połączenia ODBC. Zobacz opis funkcji odbc_connect() aby poznać szczegóły.
-
qualifier -
The qualifier.
-
owner -
The owner.
-
table_name -
The table name.
-
unique -
The unique attribute.
-
accuracy -
The accuracy.
Zwracane wartości
Returns an ODBC result identifier lub FALSE w przypadku niepowodzenia.
The result set has the following columns:
- TABLE_QUALIFIER
- TABLE_OWNER
- TABLE_NAME
- NON_UNIQUE
- INDEX_QUALIFIER
- INDEX_NAME
- TYPE
- SEQ_IN_INDEX
- COLUMN_NAME
- COLLATION
- CARDINALITY
- PAGES
- FILTER_CONDITION
The result set is ordered by NON_UNIQUE, TYPE, INDEX_QUALIFIER, INDEX_NAME and SEQ_IN_INDEX.
odbc_tableprivileges
(PHP 4, PHP 5)
odbc_tableprivileges — Lists tables and the privileges associated with each table
Opis
$connection_id
, string $qualifier
, string $owner
, string $name
)Lists tables in the requested range and the privileges associated with each table.
Parametry
-
connection_id -
Identyfikator połączenia ODBC. Zobacz opis funkcji odbc_connect() aby poznać szczegóły.
-
qualifier -
The qualifier.
-
owner -
The owner. Accepts the following search patterns: ('%' to match zero or more characters and '_' to match a single character)
-
name -
The name. Accepts the following search patterns: ('%' to match zero or more characters and '_' to match a single character)
Zwracane wartości
An ODBC result identifier lub FALSE w przypadku niepowodzenia.
The result set has the following columns:
- TABLE_QUALIFIER
- TABLE_OWNER
- TABLE_NAME
- GRANTOR
- GRANTEE
- PRIVILEGE
- IS_GRANTABLE
The result set is ordered by TABLE_QUALIFIER, TABLE_OWNER and TABLE_NAME.
odbc_tables
(PHP 4, PHP 5)
odbc_tables — Get the list of table names stored in a specific data source
Opis
$connection_id
[, string $qualifier
[, string $owner
[, string $name
[, string $types
]]]] )Lists all tables in the requested range.
To support enumeration of qualifiers, owners, and table types,
the following special semantics for the
qualifier, owner,
name, and
table_type are available:
-
If
qualifieris a single percent character (%) andownerandnameare empty strings, then the result set contains a list of valid qualifiers for the data source. (All columns except the TABLE_QUALIFIER column contain NULLs.) -
If
owneris a single percent character (%) andqualifierandnameare empty strings, then the result set contains a list of valid owners for the data source. (All columns except the TABLE_OWNER column contain NULLs.) -
If
table_typeis a single percent character (%) andqualifier,ownerandnameare empty strings, then the result set contains a list of valid table types for the data source. (All columns except the TABLE_TYPE column contain NULLs.)
Parametry
-
connection_id -
Identyfikator połączenia ODBC. Zobacz opis funkcji odbc_connect() aby poznać szczegóły.
-
qualifier -
The qualifier.
-
owner -
The owner. Accepts search patterns ('%' to match zero or more characters and '_' to match a single character).
-
name -
The name. Accepts search patterns ('%' to match zero or more characters and '_' to match a single character).
-
types -
If
table_typeis not an empty string, it must contain a list of comma-separated values for the types of interest; each value may be enclosed in single quotes (') or unquoted. For example, "'TABLE','VIEW'" or "TABLE, VIEW". If the data source does not support a specified table type, odbc_tables() does not return any results for that type.
Zwracane wartości
Returns an ODBC result identifier containing the information
lub FALSE w przypadku niepowodzenia.
The result set has the following columns:
- TABLE_QUALIFIER
- TABLE_OWNER
- TABLE_NAME
- TABLE_TYPE
- REMARKS
The result set is ordered by TABLE_TYPE, TABLE_QUALIFIER, TABLE_OWNER and TABLE_NAME.
Spis treści
- odbc_autocommit — Toggle autocommit behaviour
- odbc_binmode — Handling of binary column data
- odbc_close_all — Close all ODBC connections
- odbc_close — Close an ODBC connection
- odbc_columnprivileges — Lists columns and associated privileges for the given table
- odbc_columns — Lists the column names in specified tables
- odbc_commit — Commit an ODBC transaction
- odbc_connect — Connect to a datasource
- odbc_cursor — Get cursorname
- odbc_data_source — Returns information about a current connection
- odbc_do — Alias dla odbc_exec
- odbc_error — Get the last error code
- odbc_errormsg — Get the last error message
- odbc_exec — Prepare and execute an SQL statement
- odbc_execute — Execute a prepared statement
- odbc_fetch_array — Fetch a result row as an associative array
- odbc_fetch_into — Fetch one result row into array
- odbc_fetch_object — Fetch a result row as an object
- odbc_fetch_row — Fetch a row
- odbc_field_len — Get the length (precision) of a field
- odbc_field_name — Get the columnname
- odbc_field_num — Return column number
- odbc_field_precision — Alias dla odbc_field_len
- odbc_field_scale — Get the scale of a field
- odbc_field_type — Datatype of a field
- odbc_foreignkeys — Retrieves a list of foreign keys
- odbc_free_result — Free resources associated with a result
- odbc_gettypeinfo — Retrieves information about data types supported by the data source
- odbc_longreadlen — Handling of LONG columns
- odbc_next_result — Checks if multiple results are available
- odbc_num_fields — Number of columns in a result
- odbc_num_rows — Number of rows in a result
- odbc_pconnect — Open a persistent database connection
- odbc_prepare — Prepares a statement for execution
- odbc_primarykeys — Gets the primary keys for a table
- odbc_procedurecolumns — Retrieve information about parameters to procedures
- odbc_procedures — Get the list of procedures stored in a specific data source
- odbc_result_all — Print result as HTML table
- odbc_result — Get result data
- odbc_rollback — Rollback a transaction
- odbc_setoption — Adjust ODBC settings
- odbc_specialcolumns — Retrieves special columns
- odbc_statistics — Retrieve statistics about a table
- odbc_tableprivileges — Lists tables and the privileges associated with each table
- odbc_tables — Get the list of table names stored in a specific data source
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- ODBC Funkcje
- odbc_autocommit — Toggle autocommit behaviour
- odbc_binmode — Handling of binary column data
- odbc_close_all — Close all ODBC connections
- odbc_close — Close an ODBC connection
- odbc_columnprivileges — Lists columns and associated privileges for the given table
- odbc_columns — Lists the column names in specified tables
- odbc_commit — Commit an ODBC transaction
- odbc_connect — Connect to a datasource
- odbc_cursor — Get cursorname
- odbc_data_source — Returns information about a current connection
- odbc_do — Alias dla odbc_exec
- odbc_error — Get the last error code
- odbc_errormsg — Get the last error message
- odbc_exec — Prepare and execute an SQL statement
- odbc_execute — Execute a prepared statement
- odbc_fetch_array — Fetch a result row as an associative array
- odbc_fetch_into — Fetch one result row into array
- odbc_fetch_object — Fetch a result row as an object
- odbc_fetch_row — Fetch a row
- odbc_field_len — Get the length (precision) of a field
- odbc_field_name — Get the columnname
- odbc_field_num — Return column number
- odbc_field_precision — Alias dla odbc_field_len
- odbc_field_scale — Get the scale of a field
- odbc_field_type — Datatype of a field
- odbc_foreignkeys — Retrieves a list of foreign keys
- odbc_free_result — Free resources associated with a result
- odbc_gettypeinfo — Retrieves information about data types supported by the data source
- odbc_longreadlen — Handling of LONG columns
- odbc_next_result — Checks if multiple results are available
- odbc_num_fields — Number of columns in a result
- odbc_num_rows — Number of rows in a result
- odbc_pconnect — Open a persistent database connection
- odbc_prepare — Prepares a statement for execution
- odbc_primarykeys — Gets the primary keys for a table
- odbc_procedurecolumns — Retrieve information about parameters to procedures
- odbc_procedures — Get the list of procedures stored in a specific data source
- odbc_result_all — Print result as HTML table
- odbc_result — Get result data
- odbc_rollback — Rollback a transaction
- odbc_setoption — Adjust ODBC settings
- odbc_specialcolumns — Retrieves special columns
- odbc_statistics — Retrieve statistics about a table
- odbc_tableprivileges — Lists tables and the privileges associated with each table
- odbc_tables — Get the list of table names stored in a specific data source
PHP Data Objects
Wstęp
The PHP Data Objects (PDO) extension defines a lightweight, consistent interface for accessing databases in PHP. Each database driver that implements the PDO interface can expose database-specific features as regular extension functions. Note that you cannot perform any database functions using the PDO extension by itself; you must use a database-specific PDO driver to access a database server.
PDO provides a data-access abstraction layer, which means that, regardless of which database you're using, you use the same functions to issue queries and fetch data. PDO does not provide a database abstraction; it doesn't rewrite SQL or emulate missing features. You should use a full-blown abstraction layer if you need that facility.
PDO ships with PHP 5.1, and is available as a PECL extension for PHP 5.0; PDO requires the new OO features in the core of PHP 5, and so will not run with earlier versions of PHP.
Instalacja/Konfiguracja
Spis treści
Wymagania
Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.
Instalacja
-
PDO and the PDO_SQLITE driver is enabled by default as of PHP 5.1.0. You may need to enable the PDO driver for your database of choice; consult the documentation for database-specific PDO drivers to find out more about that. Note: When building PDO as a shared extension (not recommended) then all PDO drivers must be loaded after PDO itself.
-
When installing PDO as a shared module, the php.ini file needs to be updated so that the PDO extension will be loaded automatically when PHP runs. You will also need to enable any database specific drivers there too; make sure that they are listed after the pdo.so line, as PDO must be initialized before the database-specific extensions can be loaded. If you built PDO and the database-specific extensions statically, you can skip this step.
extension=pdo.so
-
PDO and all the major drivers ship with PHP as shared extensions, and simply need to be activated by editing the php.ini file:
extension=php_pdo.dll
Informacja:
This step is not necessary for PHP 5.3 and above, as a DLL is no longer required for PDO.
-
Next, choose the other database-specific DLL files and either use dl() to load them at runtime, or enable them in php.ini below php_pdo.dll. For example:
extension=php_pdo.dll extension=php_pdo_firebird.dll extension=php_pdo_informix.dll extension=php_pdo_mssql.dll extension=php_pdo_mysql.dll extension=php_pdo_oci.dll extension=php_pdo_oci8.dll extension=php_pdo_odbc.dll extension=php_pdo_pgsql.dll extension=php_pdo_sqlite.dll
These DLLs should exist in the system's extension_dir.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| pdo.dsn.* | php.ini only |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
pdo.dsn.*string -
Defines DSN alias. See PDO::__construct() for thorough explanation.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
PDO uses class constants since PHP 5.1. Prior releases use global constants
in the form PDO_PARAM_BOOL.
-
PDO::PARAM_BOOL(integer) - Represents a boolean data type.
-
PDO::PARAM_NULL(integer) - Represents the SQL NULL data type.
-
PDO::PARAM_INT(integer) - Represents the SQL INTEGER data type.
-
PDO::PARAM_STR(integer) - Represents the SQL CHAR, VARCHAR, or other string data type.
-
PDO::PARAM_LOB(integer) - Represents the SQL large object data type.
-
PDO::PARAM_STMT(integer) - Represents a recordset type. Not currently supported by any drivers.
-
PDO::PARAM_INPUT_OUTPUT(integer) - Specifies that the parameter is an INOUT parameter for a stored procedure. You must bitwise-OR this value with an explicit PDO::PARAM_* data type.
-
PDO::FETCH_LAZY(integer) -
Specifies that the fetch method shall return each row as an object with
variable names that correspond to the column names returned in the result
set.
PDO::FETCH_LAZYcreates the object variable names as they are accessed. -
PDO::FETCH_ASSOC(integer) -
Specifies that the fetch method shall return each row as an array indexed
by column name as returned in the corresponding result set. If the result
set contains multiple columns with the same name,
PDO::FETCH_ASSOCreturns only a single value per column name. -
PDO::FETCH_NAMED(integer) -
Specifies that the fetch method shall return each row as an array indexed
by column name as returned in the corresponding result set. If the result
set contains multiple columns with the same name,
PDO::FETCH_NAMEDreturns an array of values per column name. -
PDO::FETCH_NUM(integer) - Specifies that the fetch method shall return each row as an array indexed by column number as returned in the corresponding result set, starting at column 0.
-
PDO::FETCH_BOTH(integer) - Specifies that the fetch method shall return each row as an array indexed by both column name and number as returned in the corresponding result set, starting at column 0.
-
PDO::FETCH_OBJ(integer) - Specifies that the fetch method shall return each row as an object with property names that correspond to the column names returned in the result set.
-
PDO::FETCH_BOUND(integer) - Specifies that the fetch method shall return TRUE and assign the values of the columns in the result set to the PHP variables to which they were bound with the PDOStatement::bindParam() or PDOStatement::bindColumn() methods.
-
PDO::FETCH_COLUMN(integer) - Specifies that the fetch method shall return only a single requested column from the next row in the result set.
-
PDO::FETCH_CLASS(integer) -
Specifies that the fetch method shall return a new instance of the
requested class, mapping the columns to named properties in the class.
Informacja: The magic __set() method is called if the property doesn't exist in the requested class
-
PDO::FETCH_INTO(integer) - Specifies that the fetch method shall update an existing instance of the requested class, mapping the columns to named properties in the class.
-
PDO::FETCH_FUNC(integer) -
PDO::FETCH_GROUP(integer) -
PDO::FETCH_UNIQUE(integer) -
PDO::FETCH_KEY_PAIR(integer) - Fetch a two-column result into an array where the first column is a key and the second column is the value. Available since PHP 5.2.3.
-
PDO::FETCH_CLASSTYPE(integer) - Determine the class name from the value of first column.
-
PDO::FETCH_SERIALIZE(integer) -
As
PDO::FETCH_INTObut object is provided as a serialized string. Available since PHP 5.1.0. -
PDO::FETCH_PROPS_LATE(integer) - Available since PHP 5.2.0
-
PDO::ATTR_AUTOCOMMIT(integer) -
If this value is
FALSE, PDO attempts to disable autocommit so that the connection begins a transaction. -
PDO::ATTR_PREFETCH(integer) - Setting the prefetch size allows you to balance speed against memory usage for your application. Not all database/driver combinations support setting of the prefetch size. A larger prefetch size results in increased performance at the cost of higher memory usage.
-
PDO::ATTR_TIMEOUT(integer) - Sets the timeout value in seconds for communications with the database.
-
PDO::ATTR_ERRMODE(integer) - See the Errors and error handling section for more information about this attribute.
-
PDO::ATTR_SERVER_VERSION(integer) - This is a read only attribute; it will return information about the version of the database server to which PDO is connected.
-
PDO::ATTR_CLIENT_VERSION(integer) - This is a read only attribute; it will return information about the version of the client libraries that the PDO driver is using.
-
PDO::ATTR_SERVER_INFO(integer) - This is a read only attribute; it will return some meta information about the database server to which PDO is connected.
-
PDO::ATTR_CONNECTION_STATUS(integer) -
PDO::ATTR_CASE(integer) - Force column names to a specific case specified by the PDO::CASE_* constants.
-
PDO::ATTR_CURSOR_NAME(integer) - Get or set the name to use for a cursor. Most useful when using scrollable cursors and positioned updates.
-
PDO::ATTR_CURSOR(integer) -
Selects the cursor type. PDO currently supports either
PDO::CURSOR_FWDONLYandPDO::CURSOR_SCROLL. Stick withPDO::CURSOR_FWDONLYunless you know that you need a scrollable cursor. -
PDO::ATTR_DRIVER_NAME(string) -
Returns the name of the driver.
Przykład #1 using
PDO::ATTR_DRIVER_NAME<?php
if ($db->getAttribute(PDO::ATTR_DRIVER_NAME) == 'mysql') {
echo "Running on mysql; doing something mysql specific here\n";
}
?> -
PDO::ATTR_ORACLE_NULLS(integer) - Convert empty strings to SQL NULL values on data fetches.
-
PDO::ATTR_PERSISTENT(integer) - Request a persistent connection, rather than creating a new connection. See Connections and Connection management for more information on this attribute.
-
PDO::ATTR_STATEMENT_CLASS(integer) -
PDO::ATTR_FETCH_CATALOG_NAMES(integer) - Prepend the containing catalog name to each column name returned in the result set. The catalog name and column name are separated by a decimal (.) character. Support of this attribute is at the driver level; it may not be supported by your driver.
-
PDO::ATTR_FETCH_TABLE_NAMES(integer) - Prepend the containing table name to each column name returned in the result set. The table name and column name are separated by a decimal (.) character. Support of this attribute is at the driver level; it may not be supported by your driver.
-
PDO::ATTR_STRINGIFY_FETCHES(integer) -
PDO::ATTR_MAX_COLUMN_LEN(integer) -
PDO::ATTR_DEFAULT_FETCH_MODE(integer) - Available since PHP 5.2.0
-
PDO::ATTR_EMULATE_PREPARES(integer) - Available since PHP 5.1.3.
-
PDO::ERRMODE_SILENT(integer) - Do not raise an error or exception if an error occurs. The developer is expected to explicitly check for errors. This is the default mode. See Errors and error handling for more information about this attribute.
-
PDO::ERRMODE_WARNING(integer) -
Issue a PHP
E_WARNINGmessage if an error occurs. See Errors and error handling for more information about this attribute. -
PDO::ERRMODE_EXCEPTION(integer) - Throw a PDOException if an error occurs. See Errors and error handling for more information about this attribute.
-
PDO::CASE_NATURAL(integer) - Leave column names as returned by the database driver.
-
PDO::CASE_LOWER(integer) - Force column names to lower case.
-
PDO::CASE_UPPER(integer) - Force column names to upper case.
-
PDO::NULL_NATURAL(integer) -
PDO::NULL_EMPTY_STRING(integer) -
PDO::NULL_TO_STRING(integer) -
PDO::FETCH_ORI_NEXT(integer) - Fetch the next row in the result set. Valid only for scrollable cursors.
-
PDO::FETCH_ORI_PRIOR(integer) - Fetch the previous row in the result set. Valid only for scrollable cursors.
-
PDO::FETCH_ORI_FIRST(integer) - Fetch the first row in the result set. Valid only for scrollable cursors.
-
PDO::FETCH_ORI_LAST(integer) - Fetch the last row in the result set. Valid only for scrollable cursors.
-
PDO::FETCH_ORI_ABS(integer) - Fetch the requested row by row number from the result set. Valid only for scrollable cursors.
-
PDO::FETCH_ORI_REL(integer) - Fetch the requested row by relative position from the current position of the cursor in the result set. Valid only for scrollable cursors.
-
PDO::CURSOR_FWDONLY(integer) - Create a PDOStatement object with a forward-only cursor. This is the default cursor choice, as it is the fastest and most common data access pattern in PHP.
-
PDO::CURSOR_SCROLL(integer) - Create a PDOStatement object with a scrollable cursor. Pass the PDO::FETCH_ORI_* constants to control the rows fetched from the result set.
-
PDO::ERR_NONE(string) - Corresponds to SQLSTATE '00000', meaning that the SQL statement was successfully issued with no errors or warnings. This constant is for your convenience when checking PDO::errorCode() or PDOStatement::errorCode() to determine if an error occurred. You will usually know if this is the case by examining the return code from the method that raised the error condition anyway.
-
PDO::PARAM_EVT_ALLOC(integer) - Allocation event
-
PDO::PARAM_EVT_FREE(integer) - Deallocation event
-
PDO::PARAM_EVT_EXEC_PRE(integer) - Event triggered prior to execution of a prepared statement.
-
PDO::PARAM_EVT_EXEC_POST(integer) - Event triggered subsequent to execution of a prepared statement.
-
PDO::PARAM_EVT_FETCH_PRE(integer) - Event triggered prior to fetching a result from a resultset.
-
PDO::PARAM_EVT_FETCH_POST(integer) - Event triggered subsequent to fetching a result from a resultset.
-
PDO::PARAM_EVT_NORMALIZE(integer) - Event triggered during bound parameter registration allowing the driver to normalize the parameter name.
Connections and Connection management
Connections are established by creating instances of the PDO base class. It doesn't matter which driver you want to use; you always use the PDO class name. The constructor accepts parameters for specifying the database source (known as the DSN) and optionally for the username and password (if any).
Przykład #1 Connecting to MySQL
<?php
$dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
?>
If there are any connection errors, a PDOException object will be thrown. You may catch the exception if you want to handle the error condition, or you may opt to leave it for an application global exception handler that you set up via set_exception_handler().
Przykład #2 Handling connection errors
<?php
try {
$dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
foreach($dbh->query('SELECT * from FOO') as $row) {
print_r($row);
}
$dbh = null;
} catch (PDOException $e) {
print "Error!: " . $e->getMessage() . "<br/>";
die();
}
?>
If your application does not catch the exception thrown from the PDO constructor, the default action taken by the zend engine is to terminate the script and display a back trace. This back trace will likely reveal the full database connection details, including the username and password. It is your responsibility to catch this exception, either explicitly (via a catch statement) or implicitly via set_exception_handler().
Upon successful connection to the database, an instance of the PDO class
is returned to your script. The connection remains active for the
lifetime of that PDO object. To close the connection, you need to
destroy the object by ensuring that all remaining references to it are
deleted--you do this by assigning NULL to the variable that holds the
object. If you don't do this explicitly, PHP will automatically close
the connection when your script ends.
Przykład #3 Closing a connection
<?php
$dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
// use the connection here
// and now we're done; close it
$dbh = null;
?>
Many web applications will benefit from making persistent connections to database servers. Persistent connections are not closed at the end of the script, but are cached and re-used when another script requests a connection using the same credentials. The persistent connection cache allows you to avoid the overhead of establishing a new connection every time a script needs to talk to a database, resulting in a faster web application.
Przykład #4 Persistent connections
<?php
$dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass, array(
PDO::ATTR_PERSISTENT => true
));
?>
Informacja:
If you wish to use persistent connections, you must set
PDO::ATTR_PERSISTENTin the array of driver options passed to the PDO constructor. If setting this attribute with PDO::setAttribute() after instantiation of the object, the driver will not use persistent connections.
Informacja:
If you're using the PDO ODBC driver and your ODBC libraries support ODBC Connection Pooling (unixODBC and Windows are two that do; there may be more), then it's recommended that you don't use persistent PDO connections, and instead leave the connection caching to the ODBC Connection Pooling layer. The ODBC Connection Pool is shared with other modules in the process; if PDO is told to cache the connection, then that connection would never be returned to the ODBC connection pool, resulting in additional connections being created to service those other modules.
Transactions and auto-commit
Now that you're connected via PDO, you must understand how PDO manages transactions before you start issuing queries. If you've never encountered transactions before, they offer 4 major features: Atomicity, Consistency, Isolation and Durability (ACID). In layman's terms, any work carried out in a transaction, even if it is carried out in stages, is guaranteed to be applied to the database safely, and without interference from other connections, when it is committed. Transactional work can also be automatically undone at your request (provided you haven't already committed it), which makes error handling in your scripts easier.
Transactions are typically implemented by "saving-up" your batch of changes to be applied all at once; this has the nice side effect of drastically improving the efficiency of those updates. In other words, transactions can make your scripts faster and potentially more robust (you still need to use them correctly to reap that benefit).
Unfortunately, not every database supports transactions, so PDO needs to run in what is known as "auto-commit" mode when you first open the connection. Auto-commit mode means that every query that you run has its own implicit transaction, if the database supports it, or no transaction if the database doesn't support transactions. If you need a transaction, you must use the PDO::beginTransaction() method to initiate one. If the underlying driver does not support transactions, a PDOException will be thrown (regardless of your error handling settings: this is always a serious error condition). Once you are in a transaction, you may use PDO::commit() or PDO::rollBack() to finish it, depending on the success of the code you run during the transaction.
PDO only checks for transaction capabilities on driver level. If certain
runtime conditions mean that transactions are unavailable,
PDO::beginTransaction() will still return TRUE
without error if the database server accepts the request to start a
transaction.
An example of this would be trying to use transactions on MyISAM tables on a MySQL database.
When the script ends or when a connection is about to be closed, if you have an outstanding transaction, PDO will automatically roll it back. This is a safety measure to help avoid inconsistency in the cases where the script terminates unexpectedly--if you didn't explicitly commit the transaction, then it is assumed that something went awry, so the rollback is performed for the safety of your data.
The automatic rollback only happens if you initiate the transaction via PDO::beginTransaction(). If you manually issue a query that begins a transaction PDO has no way of knowing about it and thus cannot roll it back if something bad happens.
Przykład #1 Executing a batch in a transaction
In the following sample, let's assume that we are creating a set of entries for a new employee, who has been assigned an ID number of 23. In addition to entering the basic data for that person, we also need to record their salary. It's pretty simple to make two separate updates, but by enclosing them within the PDO::beginTransaction() and PDO::commit() calls, we are guaranteeing that no one else will be able to see those changes until they are complete. If something goes wrong, the catch block rolls back all changes made since the transaction was started, and then prints out an error message.
<?php
try {
$dbh = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2',
array(PDO::ATTR_PERSISTENT => true));
echo "Connected\n";
} catch (Exception $e) {
die("Unable to connect: " . $e->getMessage());
}
try {
$dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
$dbh->beginTransaction();
$dbh->exec("insert into staff (id, first, last) values (23, 'Joe', 'Bloggs')");
$dbh->exec("insert into salarychange (id, amount, changedate)
values (23, 50000, NOW())");
$dbh->commit();
} catch (Exception $e) {
$dbh->rollBack();
echo "Failed: " . $e->getMessage();
}
?>
You're not limited to making updates in a transaction; you can also issue complex queries to extract data, and possibly use that information to build up more updates and queries; while the transaction is active, you are guaranteed that no one else can make changes while you are in the middle of your work. For further reading on transactions, refer to the documentation provided by your database server.
Prepared statements and stored procedures
Many of the more mature databases support the concept of prepared statements. What are they? They can be thought of as a kind of compiled template for the SQL that an application wants to run, that can be customized using variable parameters. Prepared statements offer two major benefits:
- The query only needs to be parsed (or prepared) once, but can be executed multiple times with the same or different parameters. When the query is prepared, the database will analyze, compile and optimize its plan for executing the query. For complex queries this process can take up enough time that it will noticeably slow down an application if there is a need to repeat the same query many times with different parameters. By using a prepared statement the application avoids repeating the analyze/compile/optimize cycle. This means that prepared statements use fewer resources and thus run faster.
- The parameters to prepared statements don't need to be quoted; the driver automatically handles this. If an application exclusively uses prepared statements, the developer can be sure that no SQL injection will occur (however, if other portions of the query are being built up with unescaped input, SQL injection is still possible).
Prepared statements are so useful that they are the only feature that PDO will emulate for drivers that don't support them. This ensures that an application will be able to use the same data access paradigm regardless of the capabilities of the database.
Przykład #1 Repeated inserts using prepared statements
This example performs an INSERT query by substituting a name and a value for the named placeholders.
<?php
$stmt = $dbh->prepare("INSERT INTO REGISTRY (name, value) VALUES (:name, :value)");
$stmt->bindParam(':name', $name);
$stmt->bindParam(':value', $value);
// insert one row
$name = 'one';
$value = 1;
$stmt->execute();
// insert another row with different values
$name = 'two';
$value = 2;
$stmt->execute();
?>
Przykład #2 Repeated inserts using prepared statements
This example performs an INSERT query by substituting a name and a value for the positional ? placeholders.
<?php
$stmt = $dbh->prepare("INSERT INTO REGISTRY (name, value) VALUES (?, ?)");
$stmt->bindParam(1, $name);
$stmt->bindParam(2, $value);
// insert one row
$name = 'one';
$value = 1;
$stmt->execute();
// insert another row with different values
$name = 'two';
$value = 2;
$stmt->execute();
?>
Przykład #3 Fetching data using prepared statements
This example fetches data based on a key value supplied by a form. The user input is automatically quoted, so there is no risk of a SQL injection attack.
<?php
$stmt = $dbh->prepare("SELECT * FROM REGISTRY where name = ?");
if ($stmt->execute(array($_GET['name']))) {
while ($row = $stmt->fetch()) {
print_r($row);
}
}
?>
If the database driver supports it, an application may also bind parameters for output as well as input. Output parameters are typically used to retrieve values from stored procedures. Output parameters are slightly more complex to use than input parameters, in that a developer must know how large a given parameter might be when they bind it. If the value turns out to be larger than the size they suggested, an error is raised.
Przykład #4 Calling a stored procedure with an output parameter
<?php
$stmt = $dbh->prepare("CALL sp_returns_string(?)");
$stmt->bindParam(1, $return_value, PDO::PARAM_STR, 4000);
// call the stored procedure
$stmt->execute();
print "procedure returned $return_value\n";
?>
Developers may also specify parameters that hold values both input and output; the syntax is similar to output parameters. In this next example, the string 'hello' is passed into the stored procedure, and when it returns, hello is replaced with the return value of the procedure.
Przykład #5 Calling a stored procedure with an input/output parameter
<?php
$stmt = $dbh->prepare("CALL sp_takes_string_returns_string(?)");
$value = 'hello';
$stmt->bindParam(1, $value, PDO::PARAM_STR|PDO::PARAM_INPUT_OUTPUT, 4000);
// call the stored procedure
$stmt->execute();
print "procedure returned $value\n";
?>
Przykład #6 Invalid use of placeholder
<?php
$stmt = $dbh->prepare("SELECT * FROM REGISTRY where name LIKE '%?%'");
$stmt->execute(array($_GET['name']));
// placeholder must be used in the place of the whole value
$stmt = $dbh->prepare("SELECT * FROM REGISTRY where name LIKE ?");
$stmt->execute(array("%$_GET[name]%"));
?>
Errors and error handling
PDO offers you a choice of 3 different error handling strategies, to fit your style of application development.
-
PDO::ERRMODE_SILENTThis is the default mode. PDO will simply set the error code for you to inspect using the PDO::errorCode() and PDO::errorInfo() methods on both the statement and database objects; if the error resulted from a call on a statement object, you would invoke the PDOStatement::errorCode() or PDOStatement::errorInfo() method on that object. If the error resulted from a call on the database object, you would invoke those methods on the database object instead.
-
PDO::ERRMODE_WARNINGIn addition to setting the error code, PDO will emit a traditional E_WARNING message. This setting is useful during debugging/testing, if you just want to see what problems occurred without interrupting the flow of the application.
-
PDO::ERRMODE_EXCEPTIONIn addition to setting the error code, PDO will throw a PDOException and set its properties to reflect the error code and error information. This setting is also useful during debugging, as it will effectively "blow up" the script at the point of the error, very quickly pointing a finger at potential problem areas in your code (remember: transactions are automatically rolled back if the exception causes the script to terminate).
Exception mode is also useful because you can structure your error handling more clearly than with traditional PHP-style warnings, and with less code/nesting than by running in silent mode and explicitly checking the return value of each database call.
See Exceptions for more information about Exceptions in PHP.
PDO standardizes on using SQL-92 SQLSTATE error code strings; individual PDO drivers are responsible for mapping their native codes to the appropriate SQLSTATE codes. The PDO::errorCode() method returns a single SQLSTATE code. If you need more specific information about an error, PDO also offers an PDO::errorInfo() method which returns an array containing the SQLSTATE code, the driver specific error code and driver specific error string.
Przykład #1 Create a PDO instance and set the error mode
<?php
$dsn = 'mysql:dbname=testdb;host=127.0.0.1';
$user = 'dbuser';
$password = 'dbpass';
try {
$dbh = new PDO($dsn, $user, $password);
$dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
} catch (PDOException $e) {
echo 'Connection failed: ' . $e->getMessage();
}
?>
Large Objects (LOBs)
At some point in your application, you might find that you need to store
"large" data in your database. Large typically means "around 4kb or
more", although some databases can happily handle up to 32kb before data becomes
"large". Large objects can be either textual or binary in nature. PDO
allows you to work with this large data type by using the
PDO::PARAM_LOB
type code in your PDOStatement::bindParam() or
PDOStatement::bindColumn() calls.
PDO::PARAM_LOB tells
PDO to map the data as a stream, so that you can manipulate it using the
PHP Streams API.
Przykład #1 Displaying an image from a database
This example binds the LOB into the variable named $lob and then sends it to the browser using fpassthru(). Since the LOB is represented as a stream, functions such as fgets(), fread() and stream_get_contents() can be used on it.
<?php
$db = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2');
$stmt = $db->prepare("select contenttype, imagedata from images where id=?");
$stmt->execute(array($_GET['id']));
$stmt->bindColumn(1, $type, PDO::PARAM_STR, 256);
$stmt->bindColumn(2, $lob, PDO::PARAM_LOB);
$stmt->fetch(PDO::FETCH_BOUND);
header("Content-Type: $type");
fpassthru($lob);
?>
Przykład #2 Inserting an image into a database
This example opens up a file and passes the file handle to PDO to insert it as a LOB. PDO will do its best to get the contents of the file up to the database in the most efficient manner possible.
<?php
$db = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2');
$stmt = $db->prepare("insert into images (id, contenttype, imagedata) values (?, ?, ?)");
$id = get_new_id(); // some function to allocate a new ID
// assume that we are running as part of a file upload form
// You can find more information in the PHP documentation
$fp = fopen($_FILES['file']['tmp_name'], 'rb');
$stmt->bindParam(1, $id);
$stmt->bindParam(2, $_FILES['file']['type']);
$stmt->bindParam(3, $fp, PDO::PARAM_LOB);
$db->beginTransaction();
$stmt->execute();
$db->commit();
?>
Przykład #3 Inserting an image into a database: Oracle
Oracle requires a slightly different syntax for inserting a lob from a file. It's also essential that you perform the insert under a transaction, otherwise your newly inserted LOB will be committed with a zero-length as part of the implicit commit that happens when the query is executed:
<?php
$db = new PDO('oci:', 'scott', 'tiger');
$stmt = $db->prepare("insert into images (id, contenttype, imagedata) " .
"VALUES (?, ?, EMPTY_BLOB()) RETURNING imagedata INTO ?");
$id = get_new_id(); // some function to allocate a new ID
// assume that we are running as part of a file upload form
// You can find more information in the PHP documentation
$fp = fopen($_FILES['file']['tmp_name'], 'rb');
$stmt->bindParam(1, $id);
$stmt->bindParam(2, $_FILES['file']['type']);
$stmt->bindParam(3, $fp, PDO::PARAM_LOB);
$stmt->beginTransaction();
$stmt->execute();
$stmt->commit();
?>
The PDO class
(No version information available, might only be in SVN)
Wstęp
Represents a connection between PHP and a database server.
Krótki opis klasy
PDO::beginTransaction
(PHP 5 >= 5.1.0, PECL pdo >= 0.1.0)
PDO::beginTransaction — Initiates a transaction
Opis
Turns off autocommit mode. While autocommit mode is turned off, changes made to the database via the PDO object instance are not committed until you end the transaction by calling PDO::commit(). Calling PDO::rollBack() will roll back all changes to the database and return the connection to autocommit mode.
Some databases, including MySQL, automatically issue an implicit COMMIT when a database definition language (DDL) statement such as DROP TABLE or CREATE TABLE is issued within a transaction. The implicit COMMIT will prevent you from rolling back any other changes within the transaction boundary.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Roll back a transaction
The following example begins a transaction and issues two statements that modify the database before rolling back the changes. On MySQL, however, the DROP TABLE statement automatically commits the transaction so that none of the changes in the transaction are rolled back.
<?php
/* Begin a transaction, turning off autocommit */
$dbh->beginTransaction();
/* Change the database schema and data */
$sth = $dbh->exec("DROP TABLE fruit");
$sth = $dbh->exec("UPDATE dessert
SET name = 'hamburger'");
/* Recognize mistake and roll back changes */
$dbh->rollBack();
/* Database connection is now back in autocommit mode */
?>
Zobacz też:
- PDO::commit() - Commits a transaction
- PDO::rollBack() - Rolls back a transaction
- Transactions and auto-commit
PDO::commit
(PHP 5 >= 5.1.0, PECL pdo >= 0.1.0)
PDO::commit — Commits a transaction
Opis
Commits a transaction, returning the database connection to autocommit mode until the next call to PDO::beginTransaction() starts a new transaction.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Commit a transaction
<?php
/* Begin a transaction, turning off autocommit */
$dbh->beginTransaction();
/* Change the database schema */
$sth = $dbh->exec("DROP TABLE fruit");
/* Commit the changes */
$dbh->commit();
/* Database connection is now back in autocommit mode */
?>
Zobacz też:
- PDO::beginTransaction() - Initiates a transaction
- PDO::rollBack() - Rolls back a transaction
- Transactions and auto-commit
PDO::__construct
(PHP 5 >= 5.1.0, PECL pdo >= 0.1.0)
PDO::__construct — Creates a PDO instance representing a connection to a database
Opis
$dsn
[, string $username
[, string $password
[, array $driver_options
]]] )Creates a PDO instance to represent a connection to the requested database.
Parametry
- dsn
-
The Data Source Name, or DSN, contains the information required to connect to the database.
In general, a DSN consists of the PDO driver name, followed by a colon, followed by the PDO driver-specific connection syntax. Further information is available from the PDO driver-specific documentation.
The
dsnparameter supports three different methods of specifying the arguments required to create a database connection:- Driver invocation
-
dsncontains the full DSN. - URI invocation
-
dsnconsists ofuri:followed by a URI that defines the location of a file containing the DSN string. The URI can specify a local file or a remote URL.uri:file:///path/to/dsnfile - Aliasing
-
dsnconsists of a namenamethat maps topdo.dsn.in php.ini defining the DSN string.nameInformacja:
The alias must be defined in php.ini, and not .htaccess or httpd.conf
- username
-
The user name for the DSN string. This parameter is optional for some PDO drivers.
- password
-
The password for the DSN string. This parameter is optional for some PDO drivers.
- driver_options
-
A key=>value array of driver-specific connection options.
Zwracane wartości
Returns a PDO object on success.
Błędy/Wyjątki
PDO::__construct() throws a PDOException if the attempt to connect to the requested database fails.
Przykłady
Przykład #1 Create a PDO instance via driver invocation
<?php
/* Connect to an ODBC database using driver invocation */
$dsn = 'mysql:dbname=testdb;host=127.0.0.1';
$user = 'dbuser';
$password = 'dbpass';
try {
$dbh = new PDO($dsn, $user, $password);
} catch (PDOException $e) {
echo 'Connection failed: ' . $e->getMessage();
}
?>
Przykład #2 Create a PDO instance via URI invocation
The following example assumes that the file /usr/local/dbconnect exists with file permissions that enable PHP to read the file. The file contains the PDO DSN to connect to a DB2 database through the PDO_ODBC driver:
odbc:DSN=SAMPLE;UID=john;PWD=mypass
The PHP script can then create a database connection by simply passing the uri: parameter and pointing to the file URI:
<?php
/* Connect to an ODBC database using driver invocation */
$dsn = 'uri:file:///usr/local/dbconnect';
$user = '';
$password = '';
try {
$dbh = new PDO($dsn, $user, $password);
} catch (PDOException $e) {
echo 'Connection failed: ' . $e->getMessage();
}
?>
Przykład #3 Create a PDO instance using an alias
The following example assumes that php.ini contains the following entry to enable a connection to a MySQL database using only the alias mydb:
[PDO] pdo.dsn.mydb="mysql:dbname=testdb;host=localhost"
<?php
/* Connect to an ODBC database using an alias */
$dsn = 'mydb';
$user = '';
$password = '';
try {
$dbh = new PDO($dsn, $user, $password);
} catch (PDOException $e) {
echo 'Connection failed: ' . $e->getMessage();
}
?>
PDO::errorCode
(PHP 5 >= 5.1.0, PECL pdo >= 0.1.0)
PDO::errorCode — Fetch the SQLSTATE associated with the last operation on the database handle
Opis
Zwracane wartości
Returns an SQLSTATE, a five characters alphanumeric identifier defined in the ANSI SQL-92 standard. Briefly, an SQLSTATE consists of a two characters class value followed by a three characters subclass value. A class value of 01 indicates a warning and is accompanied by a return code of SQL_SUCCESS_WITH_INFO. Class values other than '01', except for the class 'IM', indicate an error. The class 'IM' is specific to warnings and errors that derive from the implementation of PDO (or perhaps ODBC, if you're using the ODBC driver) itself. The subclass value '000' in any class indicates that there is no subclass for that SQLSTATE.
PDO::errorCode() only retrieves error codes for operations performed directly on the database handle. If you create a PDOStatement object through PDO::prepare() or PDO::query() and invoke an error on the statement handle, PDO::errorCode() will not reflect that error. You must call PDOStatement::errorCode() to return the error code for an operation performed on a particular statement handle.
Returns NULL if no operation has been run on the database handle.
Przykłady
Przykład #1 Retrieving an SQLSTATE code
<?php
/* Provoke an error -- the BONES table does not exist */
$dbh->exec("INSERT INTO bones(skull) VALUES ('lucy')");
echo "\nPDO::errorCode(): ";
print $dbh->errorCode();
?>
Powyższy przykład wyświetli:
PDO::errorCode(): 42S02
Zobacz też:
- PDO::errorInfo() - Fetch extended error information associated with the last operation on the database handle
- PDOStatement::errorCode() - Fetch the SQLSTATE associated with the last operation on the statement handle
- PDOStatement::errorInfo() - Fetch extended error information associated with the last operation on the statement handle
PDO::errorInfo
(PHP 5 >= 5.1.0, PECL pdo >= 0.1.0)
PDO::errorInfo — Fetch extended error information associated with the last operation on the database handle
Opis
Zwracane wartości
PDO::errorInfo() returns an array of error information about the last operation performed by this database handle. The array consists of the following fields:
| Element | Information |
|---|---|
| 0 | SQLSTATE error code (a five characters alphanumeric identifier defined in the ANSI SQL standard). |
| 1 | Driver-specific error code. |
| 2 | Driver-specific error message. |
Informacja:
If the SQLSTATE error code is not set or there is no driver-specific error, the elements following element 0 will be set to
NULL.
PDO::errorInfo() only retrieves error information for operations performed directly on the database handle. If you create a PDOStatement object through PDO::prepare() or PDO::query() and invoke an error on the statement handle, PDO::errorInfo() will not reflect the error from the statement handle. You must call PDOStatement::errorInfo() to return the error information for an operation performed on a particular statement handle.
Przykłady
Przykład #1 Displaying errorInfo() fields for a PDO_ODBC connection to a DB2 database
<?php
/* Provoke an error -- bogus SQL syntax */
$stmt = $dbh->prepare('bogus sql');
if (!$stmt) {
echo "\nPDO::errorInfo():\n";
print_r($dbh->errorInfo());
}
?>
Powyższy przykład wyświetli:
PDO::errorInfo():
Array
(
[0] => HY000
[1] => 1
[2] => near "bogus": syntax error
)
Zobacz też:
- PDO::errorCode() - Fetch the SQLSTATE associated with the last operation on the database handle
- PDOStatement::errorCode() - Fetch the SQLSTATE associated with the last operation on the statement handle
- PDOStatement::errorInfo() - Fetch extended error information associated with the last operation on the statement handle
PDO::exec
(PHP 5 >= 5.1.0, PECL pdo >= 0.1.0)
PDO::exec — Execute an SQL statement and return the number of affected rows
Opis
$statement
)PDO::exec() executes an SQL statement in a single function call, returning the number of rows affected by the statement.
PDO::exec() does not return results from a SELECT statement. For a SELECT statement that you only need to issue once during your program, consider issuing PDO::query(). For a statement that you need to issue multiple times, prepare a PDOStatement object with PDO::prepare() and issue the statement with PDOStatement::execute().
Parametry
-
statement -
The SQL statement to prepare and execute.
Data inside the query should be properly escaped.
Zwracane wartości
PDO::exec() returns the number of rows that were modified or deleted by the SQL statement you issued. If no rows were affected, PDO::exec() returns 0.
Ta funkcja może
zwrócić Boolean FALSE, ale może też zwrócić wartość innego typu niż Boolean, która oznacza
wartość FALSE, takie jak 0 lub
"". Aby uzyskać więcej informacji proszę zapoznać się z rozdziałem Typy logiczne.
Można używać operatora ===
do testowania zwracanych wartości przez tę
funkcję.
The following example incorrectly relies on the return value of PDO::exec(), wherein a statement that affected 0 rows results in a call to die():
<?php
$db->exec() or die(print_r($db->errorInfo(), true));
?>
Przykłady
Przykład #1 Issuing a DELETE statement
Count the number of rows deleted by a DELETE statement with no WHERE clause.
<?php
$dbh = new PDO('odbc:sample', 'db2inst1', 'ibmdb2');
/* Delete all rows from the FRUIT table */
$count = $dbh->exec("DELETE FROM fruit WHERE colour = 'red'");
/* Return number of rows that were deleted */
print("Deleted $count rows.\n");
?>
Powyższy przykład wyświetli:
Deleted 1 rows.
Zobacz też:
- PDO::prepare() - Prepares a statement for execution and returns a statement object
- PDO::query() - Executes an SQL statement, returning a result set as a PDOStatement object
- PDOStatement::execute() - Executes a prepared statement
PDO::getAttribute
(PHP 5 >= 5.1.0, PECL pdo >= 0.2.0)
PDO::getAttribute — Retrieve a database connection attribute
Opis
This function returns the value of a database connection attribute. To retrieve PDOStatement attributes, refer to PDOStatement::getAttribute().
Note that some database/driver combinations may not support all of the database connection attributes.
Parametry
-
attribute -
One of the PDO::ATTR_* constants. The constants that apply to database connections are as follows:
- PDO::ATTR_AUTOCOMMIT
- PDO::ATTR_CASE
- PDO::ATTR_CLIENT_VERSION
- PDO::ATTR_CONNECTION_STATUS
- PDO::ATTR_DRIVER_NAME
- PDO::ATTR_ERRMODE
- PDO::ATTR_ORACLE_NULLS
- PDO::ATTR_PERSISTENT
- PDO::ATTR_PREFETCH
- PDO::ATTR_SERVER_INFO
- PDO::ATTR_SERVER_VERSION
- PDO::ATTR_TIMEOUT
Zwracane wartości
A successful call returns the value of the requested PDO attribute. An unsuccessful call returns null.
Przykłady
Przykład #1 Retrieving database connection attributes
<?php
$conn = new PDO('odbc:sample', 'db2inst1', 'ibmdb2');
$attributes = array(
"AUTOCOMMIT", "ERRMODE", "CASE", "CLIENT_VERSION", "CONNECTION_STATUS",
"ORACLE_NULLS", "PERSISTENT", "PREFETCH", "SERVER_INFO", "SERVER_VERSION",
"TIMEOUT"
);
foreach ($attributes as $val) {
echo "PDO::ATTR_$val: ";
echo $conn->getAttribute(constant("PDO::ATTR_$val")) . "\n";
}
?>
Zobacz też:
- PDO::setAttribute() - Set an attribute
- PDOStatement::getAttribute() - Retrieve a statement attribute
- PDOStatement::setAttribute() - Set a statement attribute
PDO::getAvailableDrivers
(PHP 5 >= 5.1.3, PECL pdo >= 1.0.3)
PDO::getAvailableDrivers — Return an array of available PDO drivers
Opis
This function returns all currently available PDO drivers which can be used
in DSN parameter of
PDO::__construct().
Zwracane wartości
PDO::getAvailableDrivers() returns an array of PDO driver names. If no drivers are available, it returns an empty array.
Przykłady
Przykład #1 A PDO::getAvailableDrivers() example
<?php
print_r(PDO::getAvailableDrivers());
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[0] => mysql
[1] => sqlite
)
PDO::inTransaction
(PHP 5 >= 5.3.3, Bundled pdo_pgsql)
PDO::inTransaction — Checks if inside a transaction
Opis
Checks if a transaction is currently active within the driver. This method only works for database drivers that support transactions.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns TRUE if a transaction is currently active, and FALSE if not.
PDO::lastInsertId
(PHP 5 >= 5.1.0, PECL pdo >= 0.1.0)
PDO::lastInsertId — Returns the ID of the last inserted row or sequence value
Opis
$name = NULL
] )
Returns the ID of the last inserted row, or the last value from a
sequence object, depending on the underlying driver. For example,
PDO_PGSQL() requires you to specify the name of
a sequence object for the name parameter.
Informacja:
This method may not return a meaningful or consistent result across different PDO drivers, because the underlying database may not even support the notion of auto-increment fields or sequences.
Parametry
-
name -
Name of the sequence object from which the ID should be returned.
Zwracane wartości
If a sequence name was not specified for the name
parameter, PDO::lastInsertId() returns a
string representing the row ID of the last row that was inserted into
the database.
If a sequence name was specified for the name
parameter, PDO::lastInsertId() returns a
string representing the last value retrieved from the specified sequence
object.
If the PDO driver does not support this capability, PDO::lastInsertId() triggers an IM001 SQLSTATE.
PDO::prepare
(PHP 5 >= 5.1.0, PECL pdo >= 0.1.0)
PDO::prepare — Prepares a statement for execution and returns a statement object
Opis
Prepares an SQL statement to be executed by the PDOStatement::execute() method. The SQL statement can contain zero or more named (:name) or question mark (?) parameter markers for which real values will be substituted when the statement is executed. You cannot use both named and question mark parameter markers within the same SQL statement; pick one or the other parameter style. Use these parameters to bind any user-input, do not include the user-input directly in the query.
You must include a unique parameter marker for each value you wish to pass in to the statement when you call PDOStatement::execute(). You cannot use a named parameter marker of the same name twice in a prepared statement. You cannot bind multiple values to a single named parameter in, for example, the IN() clause of an SQL statement.
Calling PDO::prepare() and PDOStatement::execute() for statements that will be issued multiple times with different parameter values optimizes the performance of your application by allowing the driver to negotiate client and/or server side caching of the query plan and meta information, and helps to prevent SQL injection attacks by eliminating the need to manually quote the parameters.
PDO will emulate prepared statements/bound parameters for drivers that do not natively support them, and can also rewrite named or question mark style parameter markers to something more appropriate, if the driver supports one style but not the other.
Parametry
-
statement -
This must be a valid SQL statement for the target database server.
-
driver_options -
This array holds one or more key=>value pairs to set attribute values for the PDOStatement object that this method returns. You would most commonly use this to set the PDO::ATTR_CURSOR value to PDO::CURSOR_SCROLL to request a scrollable cursor. Some drivers have driver specific options that may be set at prepare-time.
Zwracane wartości
If the database server successfully prepares the statement,
PDO::prepare() returns a
PDOStatement object.
If the database server cannot successfully prepare the statement,
PDO::prepare() returns FALSE or emits
PDOException (depending on error handling).
Informacja:
Emulated prepared statements does not communicate with the database server so PDO::prepare() does not check the statement.
Przykłady
Przykład #1 Prepare an SQL statement with named parameters
<?php
/* Execute a prepared statement by passing an array of values */
$sql = 'SELECT name, colour, calories
FROM fruit
WHERE calories < :calories AND colour = :colour';
$sth = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY));
$sth->execute(array(':calories' => 150, ':colour' => 'red'));
$red = $sth->fetchAll();
$sth->execute(array(':calories' => 175, ':colour' => 'yellow'));
$yellow = $sth->fetchAll();
?>
Przykład #2 Prepare an SQL statement with question mark parameters
<?php
/* Execute a prepared statement by passing an array of values */
$sth = $dbh->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < ? AND colour = ?');
$sth->execute(array(150, 'red'));
$red = $sth->fetchAll();
$sth->execute(array(175, 'yellow'));
$yellow = $sth->fetchAll();
?>
Zobacz też:
- PDO::exec() - Execute an SQL statement and return the number of affected rows
- PDO::query() - Executes an SQL statement, returning a result set as a PDOStatement object
- PDOStatement::execute() - Executes a prepared statement
PDO::query
(PHP 5 >= 5.1.0, PECL pdo >= 0.2.0)
PDO::query — Executes an SQL statement, returning a result set as a PDOStatement object
Opis
$statement
, int $PDO::FETCH_CLASS
, string $classname
, array $ctorargs
)PDO::query() executes an SQL statement in a single function call, returning the result set (if any) returned by the statement as a PDOStatement object.
For a query that you need to issue multiple times, you will realize better performance if you prepare a PDOStatement object using PDO::prepare() and issue the statement with multiple calls to PDOStatement::execute().
If you do not fetch all of the data in a result set before issuing your next call to PDO::query(), your call may fail. Call PDOStatement::closeCursor() to release the database resources associated with the PDOStatement object before issuing your next call to PDO::query().
Informacja:
Although this function is only documented as having a single parameter, you may pass additional arguments to this function. They will be treated as though you called PDOStatement::setFetchMode() on the resultant statement object.
Parametry
-
statement -
The SQL statement to prepare and execute.
Data inside the query should be properly escaped.
Zwracane wartości
PDO::query() returns a PDOStatement object, or FALSE
on failure.
Przykłady
Przykład #1 Demonstrate PDO::query
A nice feature of PDO::query() is that it enables you to iterate over the rowset returned by a successfully executed SELECT statement.
<?php
function getFruit($conn) {
$sql = 'SELECT name, color, calories FROM fruit ORDER BY name';
foreach ($conn->query($sql) as $row) {
print $row['name'] . "\t";
print $row['color'] . "\t";
print $row['calories'] . "\n";
}
}
?>
Powyższy przykład wyświetli:
apple red 150 banana yellow 250 kiwi brown 75 lemon yellow 25 orange orange 300 pear green 150 watermelon pink 90
Zobacz też:
- PDO::exec() - Execute an SQL statement and return the number of affected rows
- PDO::prepare() - Prepares a statement for execution and returns a statement object
- PDOStatement::execute() - Executes a prepared statement
PDO::quote
(PHP 5 >= 5.1.0, PECL pdo >= 0.2.1)
PDO::quote — Quotes a string for use in a query.
Opis
$string
[, int $parameter_type = PDO::PARAM_STR
] )PDO::quote() places quotes around the input string (if required) and escapes special characters within the input string, using a quoting style appropriate to the underlying driver.
If you are using this function to build SQL statements, you are strongly recommended to use PDO::prepare() to prepare SQL statements with bound parameters instead of using PDO::quote() to interpolate user input into an SQL statement. Prepared statements with bound parameters are not only more portable, more convenient, immune to SQL injection, but are often much faster to execute than interpolated queries, as both the server and client side can cache a compiled form of the query.
Not all PDO drivers implement this method (notably PDO_ODBC). Consider using prepared statements instead.
Parametry
-
string -
The string to be quoted.
-
parameter_type -
Provides a data type hint for drivers that have alternate quoting styles.
Zwracane wartości
Returns a quoted string that is theoretically safe to pass into an
SQL statement. Returns FALSE if the driver does not support quoting in
this way.
Przykłady
Przykład #1 Quoting a normal string
<?php
$conn = new PDO('sqlite:/home/lynn/music.sql3');
/* Simple string */
$string = 'Nice';
print "Unquoted string: $string\n";
print "Quoted string: " . $conn->quote($string) . "\n";
?>
Powyższy przykład wyświetli:
Unquoted string: Nice Quoted string: 'Nice'
Przykład #2 Quoting a dangerous string
<?php
$conn = new PDO('sqlite:/home/lynn/music.sql3');
/* Dangerous string */
$string = 'Naughty \' string';
print "Unquoted string: $string\n";
print "Quoted string:" . $conn->quote($string) . "\n";
?>
Powyższy przykład wyświetli:
Unquoted string: Naughty ' string Quoted string: 'Naughty '' string'
Przykład #3 Quoting a complex string
<?php
$conn = new PDO('sqlite:/home/lynn/music.sql3');
/* Complex string */
$string = "Co'mpl''ex \"st'\"ring";
print "Unquoted string: $string\n";
print "Quoted string: " . $conn->quote($string) . "\n";
?>
Powyższy przykład wyświetli:
Unquoted string: Co'mpl''ex "st'"ring Quoted string: 'Co''mpl''''ex "st''"ring'
Zobacz też:
- PDO::prepare() - Prepares a statement for execution and returns a statement object
- PDOStatement::execute() - Executes a prepared statement
PDO::rollBack
(PHP 5 >= 5.1.0, PECL pdo >= 0.1.0)
PDO::rollBack — Rolls back a transaction
Opis
Rolls back the current transaction, as initiated by PDO::beginTransaction(). A PDOException will be thrown if no transaction is active.
If the database was set to autocommit mode, this function will restore autocommit mode after it has rolled back the transaction.
Some databases, including MySQL, automatically issue an implicit COMMIT when a database definition language (DDL) statement such as DROP TABLE or CREATE TABLE is issued within a transaction. The implicit COMMIT will prevent you from rolling back any other changes within the transaction boundary.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Roll back a transaction
The following example begins a transaction and issues two statements that modify the database before rolling back the changes. On MySQL, however, the DROP TABLE statement automatically commits the transaction so that none of the changes in the transaction are rolled back.
<?php
/* Begin a transaction, turning off autocommit */
$dbh->beginTransaction();
/* Change the database schema and data */
$sth = $dbh->exec("DROP TABLE fruit");
$sth = $dbh->exec("UPDATE dessert
SET name = 'hamburger'");
/* Recognize mistake and roll back changes */
$dbh->rollBack();
/* Database connection is now back in autocommit mode */
?>
Zobacz też:
- PDO::beginTransaction() - Initiates a transaction
- PDO::commit() - Commits a transaction
- Transactions and auto-commit
PDO::setAttribute
(PHP 5 >= 5.1.0, PECL pdo >= 0.1.0)
PDO::setAttribute — Set an attribute
Opis
Sets an attribute on the database handle. Some of the available generic attributes are listed below; some drivers may make use of additional driver specific attributes.
PDO::ATTR_CASE: Force column names to a specific case.
PDO::CASE_LOWER: Force column names to lower case.
PDO::CASE_NATURAL: Leave column names as returned by the database driver.
PDO::CASE_UPPER: Force column names to upper case.
PDO::ATTR_ERRMODE: Error reporting.
PDO::ERRMODE_SILENT: Just set error codes.
PDO::ERRMODE_WARNING: Raise E_WARNING.
PDO::ERRMODE_EXCEPTION: Throw exceptions.
PDO::ATTR_ORACLE_NULLS (available with all drivers, not just Oracle): Conversion of NULL and empty strings.
PDO::NULL_NATURAL: No conversion.
PDO::NULL_EMPTY_STRING: Empty string is converted to
NULL.PDO::NULL_TO_STRING: NULL is converted to an empty string.
PDO::ATTR_STRINGIFY_FETCHES: Convert numeric values to strings when fetching. Requires bool.
PDO::ATTR_STATEMENT_CLASS: Set user-supplied statement class derived from PDOStatement. Cannot be used with persistent PDO instances. Requires array(string classname, array(mixed constructor_args)).
PDO::ATTR_TIMEOUT: Specifies the timeout duration in seconds. Not all drivers support this option, and it's meaning may differ from driver to driver. For example, sqlite will wait for up to this time value before giving up on obtaining an writable lock, but other drivers may interpret this as a connect or a read timeout interval. Requires int.
PDO::ATTR_AUTOCOMMIT (available in OCI, Firebird and MySQL): Whether to autocommit every single statement.
PDO::ATTR_EMULATE_PREPARES Enables or disables emulation of prepared statements. Some drivers do not support native prepared statements or have limited support for them. Use this setting to force PDO to either always emulate prepared statements (if
TRUE), or to try to use native prepared statements (ifFALSE). It will always fall back to emulating the prepared statement if the driver cannot successfully prepare the current query. Requires bool.PDO::MYSQL_ATTR_USE_BUFFERED_QUERY (available in MySQL): Use buffered queries.
PDO::ATTR_DEFAULT_FETCH_MODE: Set default fetch mode. Description of modes is available in PDOStatement::fetch() documentation.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Spis treści
- PDO::beginTransaction — Initiates a transaction
- PDO::commit — Commits a transaction
- PDO::__construct — Creates a PDO instance representing a connection to a database
- PDO::errorCode — Fetch the SQLSTATE associated with the last operation on the database handle
- PDO::errorInfo — Fetch extended error information associated with the last operation on the database handle
- PDO::exec — Execute an SQL statement and return the number of affected rows
- PDO::getAttribute — Retrieve a database connection attribute
- PDO::getAvailableDrivers — Return an array of available PDO drivers
- PDO::inTransaction — Checks if inside a transaction
- PDO::lastInsertId — Returns the ID of the last inserted row or sequence value
- PDO::prepare — Prepares a statement for execution and returns a statement object
- PDO::query — Executes an SQL statement, returning a result set as a PDOStatement object
- PDO::quote — Quotes a string for use in a query.
- PDO::rollBack — Rolls back a transaction
- PDO::setAttribute — Set an attribute
The PDOStatement class
(No version information available, might only be in SVN)
Wstęp
Represents a prepared statement and, after the statement is executed, an associated result set.
Krótki opis klasy
$column
, mixed &$param
[, int $type
[, int $maxlen
[, mixed $driverdata
]]] )$parameter
, mixed &$variable
[, int $data_type = PDO::PARAM_STR
[, int $length
[, mixed $driver_options
]]] )$fetch_style
[, int $cursor_orientation = PDO::FETCH_ORI_NEXT
[, int $cursor_offset = 0
]]] )Właściwości
- queryString
-
Used query string.
PDOStatement::bindColumn
(PHP 5 >= 5.1.0, PECL pdo >= 0.1.0)
PDOStatement::bindColumn — Bind a column to a PHP variable
Opis
$column
, mixed &$param
[, int $type
[, int $maxlen
[, mixed $driverdata
]]] )PDOStatement::bindColumn() arranges to have a particular variable bound to a given column in the result-set from a query. Each call to PDOStatement::fetch() or PDOStatement::fetchAll() will update all the variables that are bound to columns.
Informacja:
Since information about the columns is not always available to PDO until the statement is executed, portable applications should call this function after PDOStatement::execute().
However, to be able to bind a LOB column as a stream when using the PgSQL driver, applications should call this method before calling PDOStatement::execute(), otherwise the large object OID will be returned as an integer.
Parametry
-
column -
Number of the column (1-indexed) or name of the column in the result set. If using the column name, be aware that the name should match the case of the column, as returned by the driver.
-
param -
Name of the PHP variable to which the column will be bound.
-
type -
Data type of the parameter, specified by the PDO::PARAM_* constants.
-
maxlen -
A hint for pre-allocation.
-
driverdata -
Optional parameter(s) for the driver.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Binding result set output to PHP variables
Binding columns in the result set to PHP variables is an effective way to make the data contained in each row immediately available to your application. The following example demonstrates how PDO allows you to bind and retrieve columns with a variety of options and with intelligent defaults.
<?php
function readData($dbh) {
$sql = 'SELECT name, colour, calories FROM fruit';
try {
$stmt = $dbh->prepare($sql);
$stmt->execute();
/* Bind by column number */
$stmt->bindColumn(1, $name);
$stmt->bindColumn(2, $colour);
/* Bind by column name */
$stmt->bindColumn('calories', $cals);
while ($row = $stmt->fetch(PDO::FETCH_BOUND)) {
$data = $name . "\t" . $colour . "\t" . $cals . "\n";
print $data;
}
}
catch (PDOException $e) {
print $e->getMessage();
}
}
readData($dbh);
?>
Powyższy przykład wyświetli:
apple red 150 banana yellow 175 kiwi green 75 orange orange 150 mango red 200 strawberry red 25
Zobacz też:
- PDOStatement::execute() - Executes a prepared statement
- PDOStatement::fetch() - Fetches the next row from a result set
- PDOStatement::fetchAll() - Returns an array containing all of the result set rows
- PDOStatement::fetchColumn() - Returns a single column from the next row of a result set
PDOStatement::bindParam
(PHP 5 >= 5.1.0, PECL pdo >= 0.1.0)
PDOStatement::bindParam — Binds a parameter to the specified variable name
Opis
$parameter
, mixed &$variable
[, int $data_type = PDO::PARAM_STR
[, int $length
[, mixed $driver_options
]]] )Binds a PHP variable to a corresponding named or question mark placeholder in the SQL statement that was use to prepare the statement. Unlike PDOStatement::bindValue(), the variable is bound as a reference and will only be evaluated at the time that PDOStatement::execute() is called.
Most parameters are input parameters, that is, parameters that are used in a read-only fashion to build up the query. Some drivers support the invocation of stored procedures that return data as output parameters, and some also as input/output parameters that both send in data and are updated to receive it.
Parametry
-
parameter -
Parameter identifier. For a prepared statement using named placeholders, this will be a parameter name of the form :name. For a prepared statement using question mark placeholders, this will be the 1-indexed position of the parameter.
-
variable -
Name of the PHP variable to bind to the SQL statement parameter.
-
data_type -
Explicit data type for the parameter using the PDO::PARAM_* constants. To return an INOUT parameter from a stored procedure, use the bitwise OR operator to set the PDO::PARAM_INPUT_OUTPUT bits for the
data_typeparameter. -
length -
Length of the data type. To indicate that a parameter is an OUT parameter from a stored procedure, you must explicitly set the length.
-
driver_options -
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Execute a prepared statement with named placeholders
<?php
/* Execute a prepared statement by binding PHP variables */
$calories = 150;
$colour = 'red';
$sth = $dbh->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < :calories AND colour = :colour');
$sth->bindParam(':calories', $calories, PDO::PARAM_INT);
$sth->bindParam(':colour', $colour, PDO::PARAM_STR, 12);
$sth->execute();
?>
Przykład #2 Execute a prepared statement with question mark placeholders
<?php
/* Execute a prepared statement by binding PHP variables */
$calories = 150;
$colour = 'red';
$sth = $dbh->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < ? AND colour = ?');
$sth->bindParam(1, $calories, PDO::PARAM_INT);
$sth->bindParam(2, $colour, PDO::PARAM_STR, 12);
$sth->execute();
?>
Przykład #3 Call a stored procedure with an INOUT parameter
<?php
/* Call a stored procedure with an INOUT parameter */
$colour = 'red';
$sth = $dbh->prepare('CALL puree_fruit(?)');
$sth->bindParam(1, $colour, PDO::PARAM_STR|PDO::PARAM_INPUT_OUTPUT, 12);
$sth->execute();
print("After pureeing fruit, the colour is: $colour");
?>
Zobacz też:
- PDO::prepare() - Prepares a statement for execution and returns a statement object
- PDOStatement::execute() - Executes a prepared statement
- PDOStatement::bindValue() - Binds a value to a parameter
PDOStatement::bindValue
(PHP 5 >= 5.1.0, PECL pdo >= 1.0.0)
PDOStatement::bindValue — Binds a value to a parameter
Opis
$parameter
, mixed $value
[, int $data_type = PDO::PARAM_STR
] )Binds a value to a corresponding named or question mark placeholder in the SQL statement that was used to prepare the statement.
Parametry
-
parameter -
Parameter identifier. For a prepared statement using named placeholders, this will be a parameter name of the form :name. For a prepared statement using question mark placeholders, this will be the 1-indexed position of the parameter.
-
value -
The value to bind to the parameter.
-
data_type -
Explicit data type for the parameter using the PDO::PARAM_* constants.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Execute a prepared statement with named placeholders
<?php
/* Execute a prepared statement by binding PHP variables */
$calories = 150;
$colour = 'red';
$sth = $dbh->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < :calories AND colour = :colour');
$sth->bindValue(':calories', $calories, PDO::PARAM_INT);
$sth->bindValue(':colour', $colour, PDO::PARAM_STR);
$sth->execute();
?>
Przykład #2 Execute a prepared statement with question mark placeholders
<?php
/* Execute a prepared statement by binding PHP variables */
$calories = 150;
$colour = 'red';
$sth = $dbh->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < ? AND colour = ?');
$sth->bindValue(1, $calories, PDO::PARAM_INT);
$sth->bindValue(2, $colour, PDO::PARAM_STR);
$sth->execute();
?>
Zobacz też:
- PDO::prepare() - Prepares a statement for execution and returns a statement object
- PDOStatement::execute() - Executes a prepared statement
- PDOStatement::bindParam() - Binds a parameter to the specified variable name
PDOStatement::closeCursor
(PHP 5 >= 5.1.0, PECL pdo >= 0.9.0)
PDOStatement::closeCursor — Closes the cursor, enabling the statement to be executed again.
Opis
PDOStatement::closeCursor() frees up the connection to the server so that other SQL statements may be issued, but leaves the statement in a state that enables it to be executed again.
This method is useful for database drivers that do not support executing a PDOStatement object when a previously executed PDOStatement object still has unfetched rows. If your database driver suffers from this limitation, the problem may manifest itself in an out-of-sequence error.
PDOStatement::closeCursor() is implemented either as an optional driver specific method (allowing for maximum efficiency), or as the generic PDO fallback if no driver specific function is installed. The PDO generic fallback is semantically the same as writing the following code in your PHP script:
<?php
do {
while ($stmt->fetch())
;
if (!$stmt->nextRowset())
break;
} while (true);
?>
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 A PDOStatement::closeCursor() example
In the following example, the $stmt PDOStatement object returns multiple rows but the application fetches only the first row, leaving the PDOStatement object in a state of having unfetched rows. To ensure that the application will work with all database drivers, the author inserts a call to PDOStatement::closeCursor() on $stmt before executing the $otherStmt PDOStatement object.
<?php
/* Create a PDOStatement object */
$stmt = $dbh->prepare('SELECT foo FROM bar');
/* Create a second PDOStatement object */
$otherStmt = $dbh->prepare('SELECT foobaz FROM foobar');
/* Execute the first statement */
$stmt->execute();
/* Fetch only the first row from the results */
$stmt->fetch();
/* The following call to closeCursor() may be required by some drivers */
$stmt->closeCursor();
/* Now we can execute the second statement */
$otherStmt->execute();
?>
PDOStatement::columnCount
(PHP 5 >= 5.1.0, PECL pdo >= 0.2.0)
PDOStatement::columnCount — Returns the number of columns in the result set
Opis
Use PDOStatement::columnCount() to return the number of columns in the result set represented by the PDOStatement object.
If the PDOStatement object was returned from PDO::query(), the column count is immediately available.
If the PDOStatement object was returned from PDO::prepare(), an accurate column count will not be available until you invoke PDOStatement::execute().
Zwracane wartości
Returns the number of columns in the result set represented by the PDOStatement object. If there is no result set, PDOStatement::columnCount() returns 0.
Przykłady
Przykład #1 Counting columns
This example demonstrates how PDOStatement::columnCount() operates with and without a result set.
<?php
$dbh = new PDO('odbc:sample', 'db2inst1', 'ibmdb2');
$sth = $dbh->prepare("SELECT name, colour FROM fruit");
/* Count the number of columns in the (non-existent) result set */
$colcount = $sth->columnCount();
print("Before execute(), result set has $colcount columns (should be 0)\n");
$sth->execute();
/* Count the number of columns in the result set */
$colcount = $sth->columnCount();
print("After execute(), result set has $colcount columns (should be 2)\n");
?>
Powyższy przykład wyświetli:
Before execute(), result set has 0 columns (should be 0) After execute(), result set has 2 columns (should be 2)
Zobacz też:
- PDO::prepare() - Prepares a statement for execution and returns a statement object
- PDOStatement::execute() - Executes a prepared statement
- PDOStatement::rowCount() - Returns the number of rows affected by the last SQL statement
PDOStatement::debugDumpParams
(PHP 5 >= 5.1.0, PECL pdo >= 0.9.0)
PDOStatement::debugDumpParams — Dump an SQL prepared command
Opis
Dumps the informations contained by a prepared statement directly on the output. It will provide the SQL query in use, the number of parameters used (Params), the list of parameters, with their name, type (paramtype) as an integer, their key name or position, the value, and the position in the query (if this is supported by the PDO driver, otherwise, it will be -1).
This is a debug function, which dump directly the data on the normal output.
Ze wszystkim, co wysyła dane bezpośrednio do przeglądarki, możesz używać funkcji kontroli wyjścia aby przejąć wyjście tej funkcji i zapisać je w zmiennej tekstowej (na przykład).
This will only dumps the parameters in the statement at the moment of the dump. Extra parameters are not stored in the statement, and not displayed.
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 PDOStatement::debugDumpParams() example with named parameters
<?php
/* Execute a prepared statement by binding PHP variables */
$calories = 150;
$colour = 'red';
$sth = $dbh->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < :calories AND colour = :colour');
$sth->bindParam(':calories', $calories, PDO::PARAM_INT);
$sth->bindValue(':colour', $colour, PDO::PARAM_STR, 12);
$sth->execute();
$sth->debugDumpParams();
?>
Powyższy przykład wyświetli:
SQL: [96] SELECT name, colour, calories
FROM fruit
WHERE calories < :calories AND colour = :colour
Params: 2
Key: Name: [9] :calories
paramno=-1
name=[9] ":calories"
is_param=1
param_type=1
Key: Name: [7] :colour
paramno=-1
name=[7] ":colour"
is_param=1
param_type=2
Przykład #2 PDOStatement::debugDumpParams() example with unnamed parameters
<?php
/* Execute a prepared statement by binding PHP variables */
$calories = 150;
$colour = 'red';
$name = 'apple';
$sth = $dbh->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < ? AND colour = ?');
$sth->bindParam(1, $calories, PDO::PARAM_INT);
$sth->bindValue(2, $colour, PDO::PARAM_STR);
$sth->execute();
$sth->debugDumpParams();
?>
Powyższy przykład wyświetli:
SQL: [82] SELECT name, colour, calories
FROM fruit
WHERE calories < ? AND colour = ?
Params: 2
Key: Position #0:
paramno=0
name=[0] ""
is_param=1
param_type=1
Key: Position #1:
paramno=1
name=[0] ""
is_param=1
param_type=2
Zobacz też:
- PDO::prepare() - Prepares a statement for execution and returns a statement object
- PDOStatement::bindParam() - Binds a parameter to the specified variable name
- PDOStatement::bindValue() - Binds a value to a parameter
PDOStatement::errorCode
(PHP 5 >= 5.1.0, PECL pdo >= 0.1.0)
PDOStatement::errorCode — Fetch the SQLSTATE associated with the last operation on the statement handle
Opis
Zwracane wartości
Identical to PDO::errorCode(), except that PDOStatement::errorCode() only retrieves error codes for operations performed with PDOStatement objects.
Przykłady
Przykład #1 Retrieving an SQLSTATE code
<?php
/* Provoke an error -- the BONES table does not exist */
$err = $dbh->prepare('SELECT skull FROM bones');
$err->execute();
echo "\nPDOStatement::errorCode(): ";
print $err->errorCode();
?>
Powyższy przykład wyświetli:
PDOStatement::errorCode(): 42S02
Zobacz też:
- PDO::errorCode() - Fetch the SQLSTATE associated with the last operation on the database handle
- PDO::errorInfo() - Fetch extended error information associated with the last operation on the database handle
- PDOStatement::errorInfo() - Fetch extended error information associated with the last operation on the statement handle
PDOStatement::errorInfo
(PHP 5 >= 5.1.0, PECL pdo >= 0.1.0)
PDOStatement::errorInfo — Fetch extended error information associated with the last operation on the statement handle
Opis
Zwracane wartości
PDOStatement::errorInfo() returns an array of error information about the last operation performed by this statement handle. The array consists of the following fields:
| Element | Information |
|---|---|
| 0 | SQLSTATE error code (a five characters alphanumeric identifier defined in the ANSI SQL standard). |
| 1 | Driver specific error code. |
| 2 | Driver specific error message. |
Przykłady
Przykład #1 Displaying errorInfo() fields for a PDO_ODBC connection to a DB2 database
<?php
/* Provoke an error -- the BONES table does not exist */
$sth = $dbh->prepare('SELECT skull FROM bones');
$sth->execute();
echo "\nPDOStatement::errorInfo():\n";
$arr = $sth->errorInfo();
print_r($arr);
?>
Powyższy przykład wyświetli:
PDOStatement::errorInfo():
Array
(
[0] => 42S02
[1] => -204
[2] => [IBM][CLI Driver][DB2/LINUX] SQL0204N "DANIELS.BONES" is an undefined name. SQLSTATE=42704
)
Zobacz też:
- PDO::errorCode() - Fetch the SQLSTATE associated with the last operation on the database handle
- PDO::errorInfo() - Fetch extended error information associated with the last operation on the database handle
- PDOStatement::errorCode() - Fetch the SQLSTATE associated with the last operation on the statement handle
PDOStatement::execute
(PHP 5 >= 5.1.0, PECL pdo >= 0.1.0)
PDOStatement::execute — Executes a prepared statement
Opis
$input_parameters
] )Execute the prepared statement. If the prepared statement included parameter markers, you must either:
call PDOStatement::bindParam() to bind PHP variables to the parameter markers: bound variables pass their value as input and receive the output value, if any, of their associated parameter markers
or pass an array of input-only parameter values
Parametry
-
input_parameters -
An array of values with as many elements as there are bound parameters in the SQL statement being executed. All values are treated as
PDO::PARAM_STR.You cannot bind multiple values to a single parameter; for example, you cannot bind two values to a single named parameter in an IN() clause.
You cannot bind more values than specified; if more keys exist in
input_parametersthan in the SQL specified in the PDO::prepare(), then the statement will fail and an error is emitted.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.2.0 |
The keys from input_parameters must match the ones
declared in the SQL. Before PHP 5.2.0 this was silently ignored.
|
Przykłady
Przykład #1 Execute a prepared statement with bound variables
<?php
/* Execute a prepared statement by binding PHP variables */
$calories = 150;
$colour = 'red';
$sth = $dbh->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < :calories AND colour = :colour');
$sth->bindParam(':calories', $calories, PDO::PARAM_INT);
$sth->bindParam(':colour', $colour, PDO::PARAM_STR, 12);
$sth->execute();
?>
Przykład #2 Execute a prepared statement with an array of insert values (named parameters)
<?php
/* Execute a prepared statement by passing an array of insert values */
$calories = 150;
$colour = 'red';
$sth = $dbh->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < :calories AND colour = :colour');
$sth->execute(array(':calories' => $calories, ':colour' => $colour));
?>
Przykład #3 Execute a prepared statement with an array of insert values (placeholders)
<?php
/* Execute a prepared statement by passing an array of insert values */
$calories = 150;
$colour = 'red';
$sth = $dbh->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < ? AND colour = ?');
$sth->execute(array($calories, $colour));
?>
Przykład #4 Execute a prepared statement with question mark placeholders
<?php
/* Execute a prepared statement by binding PHP variables */
$calories = 150;
$colour = 'red';
$sth = $dbh->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < ? AND colour = ?');
$sth->bindParam(1, $calories, PDO::PARAM_INT);
$sth->bindParam(2, $colour, PDO::PARAM_STR, 12);
$sth->execute();
?>
Notatki
Informacja:
Some drivers require to close cursor before executing next statement.
Zobacz też:
- PDO::prepare() - Prepares a statement for execution and returns a statement object
- PDOStatement::bindParam() - Binds a parameter to the specified variable name
- PDOStatement::fetch() - Fetches the next row from a result set
- PDOStatement::fetchAll() - Returns an array containing all of the result set rows
- PDOStatement::fetchColumn() - Returns a single column from the next row of a result set
PDOStatement::fetch
(PHP 5 >= 5.1.0, PECL pdo >= 0.1.0)
PDOStatement::fetch — Fetches the next row from a result set
Opis
$fetch_style
[, int $cursor_orientation = PDO::FETCH_ORI_NEXT
[, int $cursor_offset = 0
]]] )
Fetches a row from a result set associated with a PDOStatement object. The
fetch_style parameter determines how PDO returns
the row.
Parametry
-
fetch_style -
Controls how the next row will be returned to the caller. This value must be one of the PDO::FETCH_* constants, defaulting to value of PDO::ATTR_DEFAULT_FETCH_MODE (which defaults to PDO::FETCH_BOTH).
PDO::FETCH_ASSOC: returns an array indexed by column name as returned in your result set
PDO::FETCH_BOTH (default): returns an array indexed by both column name and 0-indexed column number as returned in your result set
PDO::FETCH_BOUND: returns
TRUEand assigns the values of the columns in your result set to the PHP variables to which they were bound with the PDOStatement::bindColumn() methodPDO::FETCH_CLASS: returns a new instance of the requested class, mapping the columns of the result set to named properties in the class. If
fetch_styleincludes PDO::FETCH_CLASSTYPE (e.g. PDO::FETCH_CLASS | PDO::FETCH_CLASSTYPE) then the name of the class is determined from a value of the first column.PDO::FETCH_INTO: updates an existing instance of the requested class, mapping the columns of the result set to named properties in the class
PDO::FETCH_LAZY: combines PDO::FETCH_BOTH and PDO::FETCH_OBJ, creating the object variable names as they are accessed
PDO::FETCH_NUM: returns an array indexed by column number as returned in your result set, starting at column 0
PDO::FETCH_OBJ: returns an anonymous object with property names that correspond to the column names returned in your result set
-
cursor_orientation -
For a PDOStatement object representing a scrollable cursor, this value determines which row will be returned to the caller. This value must be one of the PDO::FETCH_ORI_* constants, defaulting to PDO::FETCH_ORI_NEXT. To request a scrollable cursor for your PDOStatement object, you must set the PDO::ATTR_CURSOR attribute to PDO::CURSOR_SCROLL when you prepare the SQL statement with PDO::prepare().
-
offset -
For a PDOStatement object representing a scrollable cursor for which the cursor_orientation parameter is set to PDO::FETCH_ORI_ABS, this value specifies the absolute number of the row in the result set that shall be fetched.
For a PDOStatement object representing a scrollable cursor for which the cursor_orientation parameter is set to PDO::FETCH_ORI_REL, this value specifies the row to fetch relative to the cursor position before PDOStatement::fetch() was called.
Zwracane wartości
The return value of this function on success depends on the fetch type. In
all cases, FALSE is returned on failure.
Przykłady
Przykład #1 Fetching rows using different fetch styles
<?php
$sth = $dbh->prepare("SELECT name, colour FROM fruit");
$sth->execute();
/* Exercise PDOStatement::fetch styles */
print("PDO::FETCH_ASSOC: ");
print("Return next row as an array indexed by column name\n");
$result = $sth->fetch(PDO::FETCH_ASSOC);
print_r($result);
print("\n");
print("PDO::FETCH_BOTH: ");
print("Return next row as an array indexed by both column name and number\n");
$result = $sth->fetch(PDO::FETCH_BOTH);
print_r($result);
print("\n");
print("PDO::FETCH_LAZY: ");
print("Return next row as an anonymous object with column names as properties\n");
$result = $sth->fetch(PDO::FETCH_LAZY);
print_r($result);
print("\n");
print("PDO::FETCH_OBJ: ");
print("Return next row as an anonymous object with column names as properties\n");
$result = $sth->fetch(PDO::FETCH_OBJ);
print $result->NAME;
print("\n");
?>
Powyższy przykład wyświetli:
PDO::FETCH_ASSOC: Return next row as an array indexed by column name
Array
(
[NAME] => apple
[COLOUR] => red
)
PDO::FETCH_BOTH: Return next row as an array indexed by both column name and number
Array
(
[NAME] => banana
[0] => banana
[COLOUR] => yellow
[1] => yellow
)
PDO::FETCH_LAZY: Return next row as an anonymous object with column names as properties
PDORow Object
(
[NAME] => orange
[COLOUR] => orange
)
PDO::FETCH_OBJ: Return next row as an anonymous object with column names as properties
kiwi
Przykład #2 Fetching rows with a scrollable cursor
<?php
function readDataForwards($dbh) {
$sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY BET';
try {
$stmt = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL));
$stmt->execute();
while ($row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_NEXT)) {
$data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
print $data;
}
$stmt = null;
}
catch (PDOException $e) {
print $e->getMessage();
}
}
function readDataBackwards($dbh) {
$sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY bet';
try {
$stmt = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL));
$stmt->execute();
$row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_LAST);
do {
$data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
print $data;
} while ($row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_PRIOR));
$stmt = null;
}
catch (PDOException $e) {
print $e->getMessage();
}
}
print "Reading forwards:\n";
readDataForwards($conn);
print "Reading backwards:\n";
readDataBackwards($conn);
?>
Powyższy przykład wyświetli:
Reading forwards: 21 10 5 16 0 5 19 20 10 Reading backwards: 19 20 10 16 0 5 21 10 5
Zobacz też:
- PDO::prepare() - Prepares a statement for execution and returns a statement object
- PDOStatement::execute() - Executes a prepared statement
- PDOStatement::fetchAll() - Returns an array containing all of the result set rows
- PDOStatement::fetchColumn() - Returns a single column from the next row of a result set
- PDOStatement::fetchObject() - Fetches the next row and returns it as an object.
- PDOStatement::setFetchMode() - Set the default fetch mode for this statement
PDOStatement::fetchAll
(PHP 5 >= 5.1.0, PECL pdo >= 0.1.0)
PDOStatement::fetchAll — Returns an array containing all of the result set rows
Opis
$fetch_style
[, mixed $fetch_argument
[, array $ctor_args = array()
]]] )Parametry
-
fetch_style -
Controls the contents of the returned array as documented in PDOStatement::fetch(). Defaults to value of
PDO::ATTR_DEFAULT_FETCH_MODE(which defaults toPDO::FETCH_BOTH)To return an array consisting of all values of a single column from the result set, specify
PDO::FETCH_COLUMN. You can specify which column you want with thecolumn-indexparameter.To fetch only the unique values of a single column from the result set, bitwise-OR
PDO::FETCH_COLUMNwithPDO::FETCH_UNIQUE.To return an associative array grouped by the values of a specified column, bitwise-OR
PDO::FETCH_COLUMNwithPDO::FETCH_GROUP. -
fetch_argument -
This argument have a different meaning depending on the value of the
fetch_styleparameter:-
PDO::FETCH_COLUMN: Returns the indicated 0-indexed column. -
PDO::FETCH_CLASS: Returns instances of the specified class, mapping the columns of each row to named properties in the class. -
PDO::FETCH_FUNC: Returns the results of calling the specified function, using each row's columns as parameters in the call.
-
-
ctor_args -
Arguments of custom class constructor when the
fetch_styleparameter isPDO::FETCH_CLASS.
Zwracane wartości
PDOStatement::fetchAll() returns an array containing all of the remaining rows in the result set. The array represents each row as either an array of column values or an object with properties corresponding to each column name.
Using this method to fetch large result sets will result in a heavy demand on system and possibly network resources. Rather than retrieving all of the data and manipulating it in PHP, consider using the database server to manipulate the result sets. For example, use the WHERE and ORDER BY clauses in SQL to restrict results before retrieving and processing them with PHP.
Przykłady
Przykład #1 Fetch all remaining rows in a result set
<?php
$sth = $dbh->prepare("SELECT name, colour FROM fruit");
$sth->execute();
/* Fetch all of the remaining rows in the result set */
print("Fetch all of the remaining rows in the result set:\n");
$result = $sth->fetchAll();
print_r($result);
?>
Powyższy przykład wyświetli coś podobnego do:
Fetch all of the remaining rows in the result set:
Array
(
[0] => Array
(
[NAME] => pear
[0] => pear
[COLOUR] => green
[1] => green
)
[1] => Array
(
[NAME] => watermelon
[0] => watermelon
[COLOUR] => pink
[1] => pink
)
)
Przykład #2 Fetching all values of a single column from a result set
The following example demonstrates how to return all of the values of a single column from a result set, even though the SQL statement itself may return multiple columns per row.
<?php
$sth = $dbh->prepare("SELECT name, colour FROM fruit");
$sth->execute();
/* Fetch all of the values of the first column */
$result = $sth->fetchAll(PDO::FETCH_COLUMN, 0);
var_dump($result);
?>
Powyższy przykład wyświetli coś podobnego do:
Array(3)
(
[0] =>
string(5) => apple
[1] =>
string(4) => pear
[2] =>
string(10) => watermelon
)
Przykład #3 Grouping all values by a single column
The following example demonstrates how to return an associative array grouped by the values of the specified column in the result set. The array contains three keys: values apple and pear are returned as arrays that contain two different colours, while watermelon is returned as an array that contains only one colour.
<?php
$insert = $dbh->prepare("INSERT INTO fruit(name, colour) VALUES (?, ?)");
$insert->execute(array('apple', 'green'));
$insert->execute(array('pear', 'yellow'));
$sth = $dbh->prepare("SELECT name, colour FROM fruit");
$sth->execute();
/* Group values by the first column */
var_dump($sth->fetchAll(PDO::FETCH_COLUMN|PDO::FETCH_GROUP));
?>
Powyższy przykład wyświetli coś podobnego do:
array(3) {
["apple"]=>
array(2) {
[0]=>
string(5) "green"
[1]=>
string(3) "red"
}
["pear"]=>
array(2) {
[0]=>
string(5) "green"
[1]=>
string(6) "yellow"
}
["watermelon"]=>
array(1) {
[0]=>
string(5) "green"
}
}
Przykład #4 Instantiating a class for each result
The following example demonstrates the behaviour of the
PDO::FETCH_CLASS fetch style.
<?php
class fruit {
public $name;
public $colour;
}
$sth = $dbh->prepare("SELECT name, colour FROM fruit");
$sth->execute();
$result = $sth->fetchAll(PDO::FETCH_CLASS, "fruit");
var_dump($result);
?>
Powyższy przykład wyświetli coś podobnego do:
array(3) {
[0]=>
object(fruit)#1 (2) {
["name"]=>
string(5) "apple"
["colour"]=>
string(5) "green"
}
[1]=>
object(fruit)#2 (2) {
["name"]=>
string(4) "pear"
["colour"]=>
string(6) "yellow"
}
[2]=>
object(fruit)#3 (2) {
["name"]=>
string(10) "watermelon"
["colour"]=>
string(4) "pink"
}
}
Przykład #5 Calling a function for each result
The following example demonstrates the behaviour of the
PDO::FETCH_FUNC fetch style.
<?php
function fruit($name, $colour) {
return "{$name}: {$colour}";
}
$sth = $dbh->prepare("SELECT name, colour FROM fruit");
$sth->execute();
$result = $sth->fetchAll(PDO::FETCH_FUNC, "fruit");
var_dump($result);
?>
Powyższy przykład wyświetli coś podobnego do:
array(3) {
[0]=>
string(12) "apple: green"
[1]=>
string(12) "pear: yellow"
[2]=>
string(16) "watermelon: pink"
}
Zobacz też:
- PDO::query() - Executes an SQL statement, returning a result set as a PDOStatement object
- PDOStatement::fetch() - Fetches the next row from a result set
- PDOStatement::fetchColumn() - Returns a single column from the next row of a result set
- PDO::prepare() - Prepares a statement for execution and returns a statement object
- PDOStatement::setFetchMode() - Set the default fetch mode for this statement
PDOStatement::fetchColumn
(PHP 5 >= 5.1.0, PECL pdo >= 0.9.0)
PDOStatement::fetchColumn — Returns a single column from the next row of a result set
Opis
$column_number = 0
] )
Returns a single column from the next row of a result set or FALSE if
there are no more rows.
Parametry
-
column_number -
0-indexed number of the column you wish to retrieve from the row. If no value is supplied, PDOStatement::fetchColumn() fetches the first column.
Zwracane wartości
PDOStatement::fetchColumn() returns a single column in the next row of a result set.
There is no way to return another column from the same row if you use PDOStatement::fetchColumn() to retrieve data.
Przykłady
Przykład #1 Return first column of the next row
<?php
$sth = $dbh->prepare("SELECT name, colour FROM fruit");
$sth->execute();
/* Fetch the first column from the next row in the result set */
print("Fetch the first column from the next row in the result set:\n");
$result = $sth->fetchColumn();
print("name = $result\n");
print("Fetch the second column from the next row in the result set:\n");
$result = $sth->fetchColumn(1);
print("colour = $result\n");
?>
Powyższy przykład wyświetli:
Fetch the first column from the next row in the result set: name = lemon Fetch the second column from the next row in the result set: colour = red
Zobacz też:
- PDO::query() - Executes an SQL statement, returning a result set as a PDOStatement object
- PDOStatement::fetch() - Fetches the next row from a result set
- PDOStatement::fetchAll() - Returns an array containing all of the result set rows
- PDO::prepare() - Prepares a statement for execution and returns a statement object
- PDOStatement::setFetchMode() - Set the default fetch mode for this statement
PDOStatement::fetchObject
(PHP 5 >= 5.1.0, PECL pdo >= 0.2.4)
PDOStatement::fetchObject — Fetches the next row and returns it as an object.
Opis
Fetches the next row and returns it as an object. This function is an
alternative to PDOStatement::fetch() with
PDO::FETCH_CLASS or
PDO::FETCH_OBJ style.
Parametry
-
class_name -
Name of the created class.
-
ctor_args -
Elements of this array are passed to the constructor.
Zwracane wartości
Returns an instance of the required class with property names that
correspond to the column names lub FALSE w przypadku niepowodzenia.
PDOStatement::getAttribute
(PHP 5 >= 5.1.0, PECL pdo >= 0.2.0)
PDOStatement::getAttribute — Retrieve a statement attribute
Opis
Gets an attribute of the statement. Currently, no generic attributes exist but only driver specific:
PDO::ATTR_CURSOR_NAME (Firebird and ODBC specific): Get the name of cursor for UPDATE ... WHERE CURRENT OF.
Zwracane wartości
Returns the attribute value.
Zobacz też:
- PDO::getAttribute() - Retrieve a database connection attribute
- PDO::setAttribute() - Set an attribute
- PDOStatement::setAttribute() - Set a statement attribute
PDOStatement::getColumnMeta
(PHP 5 >= 5.1.0, PECL pdo >= 0.2.0)
PDOStatement::getColumnMeta — Returns metadata for a column in a result set
Opis
$column
)Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Retrieves the metadata for a 0-indexed column in a result set as an associative array.
Not all PDO drivers support PDOStatement::getColumnMeta().
Parametry
-
column -
The 0-indexed column in the result set.
Zwracane wartości
Returns an associative array containing the following values representing the metadata for a single column:
| Name | Value |
|---|---|
| native_type | The PHP native type used to represent the column value. |
| driver:decl_type | The SQL type used to represent the column value in the database. If the column in the result set is the result of a function, this value is not returned by PDOStatement::getColumnMeta(). |
| flags | Any flags set for this column. |
| name | The name of this column as returned by the database. |
| table | The name of this column's table as returned by the database. |
| len | The length of this column. Normally -1 for types other than floating point decimals. |
| precision | The numeric precision of this column. Normally 0 for types other than floating point decimals. |
| pdo_type | The type of this column as represented by the PDO::PARAM_* constants. |
Returns FALSE if the requested column does not exist in the result set,
or if no result set exists.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.2.3 | table field |
Przykłady
Przykład #1 Retrieving column metadata
The following example shows the results of retrieving the metadata for a single column generated by a function (COUNT) in a PDO_SQLITE driver.
<?php
$select = $DB->query('SELECT COUNT(*) FROM fruit');
$meta = $select->getColumnMeta(0);
var_dump($meta);
?>
Powyższy przykład wyświetli:
array(6) {
["native_type"]=>
string(7) "integer"
["flags"]=>
array(0) {
}
["name"]=>
string(8) "COUNT(*)"
["len"]=>
int(-1)
["precision"]=>
int(0)
["pdo_type"]=>
int(2)
}
Zobacz też:
- PDOStatement::columnCount() - Returns the number of columns in the result set
- PDOStatement::rowCount() - Returns the number of rows affected by the last SQL statement
PDOStatement::nextRowset
(PHP 5 >= 5.1.0, PECL pdo >= 0.2.0)
PDOStatement::nextRowset — Advances to the next rowset in a multi-rowset statement handle
Opis
Some database servers support stored procedures that return more than one rowset (also known as a result set). PDOStatement::nextRowset() enables you to access the second and subsequent rowsets associated with a PDOStatement object. Each rowset can have a different set of columns from the preceding rowset.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Fetching multiple rowsets returned from a stored procedure
The following example shows how to call a stored procedure, MULTIPLE_ROWSETS, that returns three rowsets. We use a do / while loop to loop over the PDOStatement::nextRowset() method, which returns false and terminates the loop when no more rowsets can be returned.
<?php
$sql = 'CALL multiple_rowsets()';
$stmt = $conn->query($sql);
$i = 1;
do {
$rowset = $stmt->fetchAll(PDO::FETCH_NUM);
if ($rowset) {
printResultSet($rowset, $i);
}
$i++;
} while ($stmt->nextRowset());
function printResultSet(&$rowset, $i) {
print "Result set $i:\n";
foreach ($rowset as $row) {
foreach ($row as $col) {
print $col . "\t";
}
print "\n";
}
print "\n";
}
?>
Powyższy przykład wyświetli:
Result set 1: apple red banana yellow Result set 2: orange orange 150 banana yellow 175 Result set 3: lime green apple red banana yellow
Zobacz też:
- PDOStatement::columnCount() - Returns the number of columns in the result set
- PDOStatement::execute() - Executes a prepared statement
- PDOStatement::getColumnMeta() - Returns metadata for a column in a result set
- PDO::query() - Executes an SQL statement, returning a result set as a PDOStatement object
PDOStatement::rowCount
(PHP 5 >= 5.1.0, PECL pdo >= 0.1.0)
PDOStatement::rowCount — Returns the number of rows affected by the last SQL statement
Opis
PDOStatement::rowCount() returns the number of rows affected by the last DELETE, INSERT, or UPDATE statement executed by the corresponding PDOStatement object.
If the last SQL statement executed by the associated PDOStatement was a SELECT statement, some databases may return the number of rows returned by that statement. However, this behaviour is not guaranteed for all databases and should not be relied on for portable applications.
Zwracane wartości
Returns the number of rows.
Przykłady
Przykład #1 Return the number of deleted rows
PDOStatement::rowCount() returns the number of rows affected by a DELETE, INSERT, or UPDATE statement.
<?php
/* Delete all rows from the FRUIT table */
$del = $dbh->prepare('DELETE FROM fruit');
$del->execute();
/* Return number of rows that were deleted */
print("Return number of rows that were deleted:\n");
$count = $del->rowCount();
print("Deleted $count rows.\n");
?>
Powyższy przykład wyświetli:
Return number of rows that were deleted: Deleted 9 rows.
Przykład #2 Counting rows returned by a SELECT statement
For most databases, PDOStatement::rowCount() does not return the number of rows affected by a SELECT statement. Instead, use PDO::query() to issue a SELECT COUNT(*) statement with the same predicates as your intended SELECT statement, then use PDOStatement::fetchColumn() to retrieve the number of rows that will be returned. Your application can then perform the correct action.
<?php
$sql = "SELECT COUNT(*) FROM fruit WHERE calories > 100";
if ($res = $conn->query($sql)) {
/* Check the number of rows that match the SELECT statement */
if ($res->fetchColumn() > 0) {
/* Issue the real SELECT statement and work with the results */
$sql = "SELECT name FROM fruit WHERE calories > 100";
foreach ($conn->query($sql) as $row) {
print "Name: " . $row['NAME'] . "\n";
}
}
/* No rows matched -- do something else */
else {
print "No rows matched the query.";
}
}
$res = null;
$conn = null;
?>
Powyższy przykład wyświetli:
apple banana orange pear
Zobacz też:
- PDOStatement::columnCount() - Returns the number of columns in the result set
- PDOStatement::fetchColumn() - Returns a single column from the next row of a result set
- PDO::query() - Executes an SQL statement, returning a result set as a PDOStatement object
PDOStatement::setAttribute
(PHP 5 >= 5.1.0, PECL pdo >= 0.2.0)
PDOStatement::setAttribute — Set a statement attribute
Opis
Sets an attribute on the statement. Currently, no generic attributes are set but only driver specific:
PDO::ATTR_CURSOR_NAME (Firebird and ODBC specific): Set the name of cursor for UPDATE ... WHERE CURRENT OF.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- PDO::getAttribute() - Retrieve a database connection attribute
- PDO::setAttribute() - Set an attribute
- PDOStatement::getAttribute() - Retrieve a statement attribute
PDOStatement::setFetchMode
(PHP 5 >= 5.1.0, PECL pdo >= 0.2.0)
PDOStatement::setFetchMode — Set the default fetch mode for this statement
Opis
$mode
)$PDO::FETCH_COLUMN
, int $colno
)$PDO::FETCH_CLASS
, string $classname
, array $ctorargs
)$PDO::FETCH_INTO
, object $object
)Parametry
-
mode -
The fetch mode must be one of the PDO::FETCH_* constants.
-
colno -
Column number.
-
classname -
Class name.
-
ctorargs -
Constructor arguments.
-
object -
Object.
Zwracane wartości
Returns 1 on success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 Setting the fetch mode
The following example demonstrates how PDOStatement::setFetchMode() changes the default fetch mode for a PDOStatement object.
<?php
$sql = 'SELECT name, colour, calories FROM fruit';
try {
$stmt = $dbh->query($sql);
$result = $stmt->setFetchMode(PDO::FETCH_NUM);
while ($row = $stmt->fetch()) {
print $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
}
}
catch (PDOException $e) {
print $e->getMessage();
}
?>
Powyższy przykład wyświetli:
apple red 150 banana yellow 250 orange orange 300 kiwi brown 75 lemon yellow 25 pear green 150 watermelon pink 90
Spis treści
- PDOStatement::bindColumn — Bind a column to a PHP variable
- PDOStatement::bindParam — Binds a parameter to the specified variable name
- PDOStatement::bindValue — Binds a value to a parameter
- PDOStatement::closeCursor — Closes the cursor, enabling the statement to be executed again.
- PDOStatement::columnCount — Returns the number of columns in the result set
- PDOStatement::debugDumpParams — Dump an SQL prepared command
- PDOStatement::errorCode — Fetch the SQLSTATE associated with the last operation on the statement handle
- PDOStatement::errorInfo — Fetch extended error information associated with the last operation on the statement handle
- PDOStatement::execute — Executes a prepared statement
- PDOStatement::fetch — Fetches the next row from a result set
- PDOStatement::fetchAll — Returns an array containing all of the result set rows
- PDOStatement::fetchColumn — Returns a single column from the next row of a result set
- PDOStatement::fetchObject — Fetches the next row and returns it as an object.
- PDOStatement::getAttribute — Retrieve a statement attribute
- PDOStatement::getColumnMeta — Returns metadata for a column in a result set
- PDOStatement::nextRowset — Advances to the next rowset in a multi-rowset statement handle
- PDOStatement::rowCount — Returns the number of rows affected by the last SQL statement
- PDOStatement::setAttribute — Set a statement attribute
- PDOStatement::setFetchMode — Set the default fetch mode for this statement
The PDOException class
(No version information available, might only be in SVN)
Wstęp
Represents an error raised by PDO. You should not throw a PDOException from your own code. See Exceptions for more information about Exceptions in PHP.
Krótki opis klasy
Właściwości
- errorInfo
-
Corresponds to PDO::errorInfo() or PDOStatement::errorInfo()
- message
-
Textual error message. Exception::getMessage() to access it.
- code
-
SQLSTATE error code. Use Exception::getCode() to access it.
PDO Drivers
Spis treści
- CUBRID (PDO)
- MS SQL Server (PDO)
- Firebird/Interbase (PDO)
- IBM (PDO)
- Informix (PDO)
- MySQL (PDO)
- MS SQL Server (PDO)
- Oracle (PDO)
- ODBC and DB2 (PDO)
- PostgreSQL (PDO)
- SQLite (PDO)
- 4D (PDO)
The following drivers currently implement the PDO interface:
| Driver name | Supported databases |
|---|---|
| PDO_CUBRID | Cubrid |
| PDO_DBLIB | FreeTDS / Microsoft SQL Server / Sybase |
| PDO_FIREBIRD | Firebird/Interbase 6 |
| PDO_IBM | IBM DB2 |
| PDO_INFORMIX | IBM Informix Dynamic Server |
| PDO_MYSQL | MySQL 3.x/4.x/5.x |
| PDO_OCI | Oracle Call Interface |
| PDO_ODBC | ODBC v3 (IBM DB2, unixODBC and win32 ODBC) |
| PDO_PGSQL | PostgreSQL |
| PDO_SQLITE | SQLite 3 and SQLite 2 |
| PDO_SQLSRV | Microsoft SQL Server / SQL Azure |
| PDO_4D | 4D |
CUBRID Functions (PDO_CUBRID)
Wstęp
PDO_CUBRID is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to CUBRID databases.
Informacja:
Current version of PDO_CUBRID doesn't support persistent connection now.
Instalacja
To build the PDO_CUBRID extension, the CUBRID DBMS must be installed on the same system as PHP. PDO_CUBRID is a » PECL extension, so follow the instructions in Installation of PECL extensions to install the PDO_CUBRID extension. Issue the configure command to point to the location of your CUBRID base dir as follows:
$ ./configure --with-pdo-cubrid=/path/to/CUBRID[,shared]
DLL z tym rozszerzeniem PECL można pobrać zarówno ze strony » PHP Downloads lub z » http://pecl4win.php.net/ Detailed information about installation on Linux and Windows manually, please read build-guide.html in PECL package CUBRID for reference.
Features
| Feature | Description |
|---|---|
| Scrollable cursors | PDO_CUBRID supports scrollable cursors. The default cursor type is forward only, and you can use parameter driver_options in PDO::prepare() to change cursor type. |
| Timeout | PDO_CUBRID supports sql statement execution timeout setting; You can use PDO::setAttribute() to set timeout value. |
| Autocommit_mode and Transaction |
PDO_CUBRID supports both autocommit_mode and transaction, and
autocommit_mode is disabled by default. You can use
PDO::setAttribute() to change its state.
If you use PDO::beginTransaction() to begin a transaction, it will disable autocommit_mode automatically and restore it after PDO::commit() or PDO::rollBack(). Note that before disabling the autocommit_mode, any pending work is automatically committed. |
| Multiple SQL Statements | PDO_CUBRID supports Multiple SQL statements. Multiple SQL statements are separated by semicolons (;) |
| Schema Information | PDO_CUBRID implements a function PDO::cubrid_schema() to get schema information. |
| LOBs | PDO_CUBRID supports BLOB/CLOB data type. The LOB in PDO is
represented as a stream, so you can insert LOBs by binding a stream,
and get LOBs by reading a stream returned by CUBRID PDO. For example:
Przykład #1 Insert LOBs in CUBRID PDO
<?php
Przykład #2 Fetch LOBs in CUBRID PDO
<?php |
| Column meta |
The PDOStatement::getColumnMeta() in CUBRID PDO
will return an associative array containing the following values:
|
Stałe predefiniowane
Poniższe stałe są definiowane przez ten sterownik, i będą dostępne tylko, gdy
to rozszerzenie będzie skompilowane z PHP lub załadowane dynamicznie przy
starcie. Dodatkowo, te specyficzne dla sterownika stałe powinny być używane
tylko przy użyciu tego konkretnego sterownika. Używanie atrybutów bazy MySQL
przy użyciu sterownika PostgreSQL może prowadzić do nieprzewidzianego zachowania.
Jeśli skrypt korzysta z wielu sterowników, do pobrania atrybutu
PDO_ATTR_DRIVER_NAME, zawierającego
nazwę sterownika, można zastosować funkcję
PDO::getAttribute().
The following constants can be used when setting the database attribute. They can be passed to PDO::getAttribute() or PDO::setAttribute().
| Constant | Description |
|---|---|
| PDO::CUBRID_ATTR_ISOLATION_LEVEL | Transaction isolation level for the database connection. |
| PDO::CUBRID_ATTR_LOCK_TIMEOUT | Transaction timeout in seconds. |
| PDO::CUBRID_ATTR_MAX_STRING_LENGTH | Read only. The maximum string length for bit, varbit, char, varchar, nchar, nchar varying data types when using CUBRID PDO API. |
The following constants can be used when setting the transaction isolation level. They can be passed to PDO::getAttribute() or returned by PDO::setAttribute().
| Constant | Description |
|---|---|
| PDO::TRAN_COMMIT_CLASS_UNCOMMIT_INSTANCE | The lowest isolation level (1). A dirty, non-repeatable or phantom read may occur for the tuple and a non-repeatable read may occur for the table as well. |
| PDO::TRAN_COMMIT_CLASS_COMMIT_INSTANCE | A relatively low isolation level (2). A dirty read does not occur, but non-repeatable or phantom read may occur. |
| PDO::TRAN_REP_CLASS_UNCOMMIT_INSTANCE | The default isolation of CUBRID (3). A dirty, non-repeatable or phantom read may occur for the tuple, but repeatable read is ensured for the table. |
| PDO::TRAN_REP_CLASS_COMMIT_INSTANCE | A relatively low isolation level (4). A dirty read does not occur, but non-repeatable or phantom read may. |
| PDO::TRAN_REP_CLASS_REP_INSTANCE | A relatively high isolation level (5). A dirty or non-repeatable read does not occur, but a phantom read may. |
| PDO::TRAN_SERIALIZABLE | The highest isolation level (6). Problems concerning concurrency (e.g. dirty read, non-repeatable read, phantom read, etc.) do not occur. |
The following constants can be used when getting schema information. They can be passed to PDO::cubrid_schema().
| Constant | Description |
|---|---|
| PDO::CUBRID_SCH_TABLE | Get name and type of table in CUBRID. |
| PDO::CUBRID_SCH_VIEW | Get name and type of view in CUBRID. |
| PDO::CUBRID_SCH_QUERY_SPEC | Get the query definition of view. |
| PDO::CUBRID_SCH_ATTRIBUTE | Get the attributes of table column. |
| PDO::CUBRID_SCH_TABLE_ATTRIBUTE | Get the attributes of table. |
| PDO::CUBRID_SCH_METHOD | Get the instance method. The instance method is a method called by a class instance. It is used more often than the class method because most operations are executed in the instance. |
| PDO::CUBRID_SCH_TABLE_METHOD | Get the class method. The class method is a method called by a class object. It is usually used to create a new class instance or to initialize it. It is also used to access or update class attributes. |
| PDO::CUBRID_SCH_METHOD_FILE | Get the information of the file where the method of the table is defined. |
| PDO::CUBRID_SCH_SUPER_TABLE | Get the name and type of table which table inherites attributes from. |
| PDO::CUBRID_SCH_SUB_TABLE | Get the name and type of table which inherites attributes from this table. |
| PDO::CUBRID_SCH_CONSTRAINT | Get the table constraints. |
| PDO::CUBRID_SCH_TRIGGER | Get the table triggers. |
| PDO::CUBRID_SCH_TABLE_PRIVILEGE | Get the privilege information of table. |
| PDO::CUBRID_SCH_COL_PRIVILEGE | Get the privilege information of column. |
| PDO::CUBRID_SCH_DIRECT_SUPER_TABLE | Get the direct super table of table. |
| PDO::CUBRID_SCH_PRIMARY_KEY | Get the table primary key. |
| PDO::CUBRID_SCH_IMPORTED_KEYS | Get imported keys of table. |
| PDO::CUBRID_SCH_EXPORTED_KEYS | Get exported keys of table. |
| PDO::CUBRID_SCH_CROSS_REFERENCE | Get reference relationship of tow tables. |
PDO_CUBRID DSN
(No version information available, might only be in SVN)
PDO_CUBRID DSN — Connecting to CUBRID databases
Opis
The PDO_CUBRID Data Source Name (DSN) is composed of the following elements, delimited by semicolons:
- DSN prefix
-
The DSN prefix is
cubrid:. - host
-
The hostname on which the database server resides.
- port
-
The port on which the database server is running.
- dbname
-
The name of the database.
Notatki
Informacja:
When you estalish the connection to CUBRID, you should give username and password except DSN.
Przykłady
Przykład #1 PDO_CUBRID DSN examples
The following example shows a PDO_CUBRID DSN for connecting to a CUBRID database:
cubrid:host=localhost;port=33000;dbname=demodb
PDO::cubrid_schema
(No version information available, might only be in SVN)
PDO::cubrid_schema — Get the requested schema information
Opis
$schema_type
[, string $table_name
[, string $col_name
]] )
This function is used to get the requested schema information from
database. You have to designate table_name, if you
want to get information on certain table, col_name,
if you want to get information on certain column (can be used only with
PDO::CUBRID_SCH_COL_PRIVILEGE).
The result of this function is returned as a two-dimensional array (column (associative array) * row (numeric array)). The following tables shows types of schema and the column structure of the result array to be returned based on the schema type.
| Schema | Column Number | Column Name | Value |
|---|---|---|---|
| PDO::CUBRID_SCH_TABLE | 1 | NAME | |
| 2 | TYPE | 0:system table 1:view 2:table | |
| PDO::CUBRID_SCH_VIEW | 1 | NAME | |
| 2 | TYPE | 1:view | |
| PDO::CUBRID_SCH_QUERY_SPEC | 1 | QUERY_SPEC | |
| PDO::CUBRID_SCH_ATTRIBUTE / PDO::CUBRID_SCH_TABLE_ATTRIBUTE | 1 | ATTR_NAME | |
| 2 | DOMAIN | ||
| 3 | SCALE | ||
| 4 | PRECISION | ||
| 5 | INDEXED | 1:indexed | |
| 6 | NOT NULL | 1:not null | |
| 7 | SHARED | 1:shared | |
| 8 | UNIQUE | 1:unique | |
| 9 | DEFAULT | ||
| 10 | ATTR_ORDER | base:1 | |
| 11 | CLASS_NAME | ||
| 12 | SOURCE_CLASS | ||
| 13 | IS_KEY | 1:key | |
| PDO::CUBRID_SCH_METHOD / PDO::CUBRID_SCH_TABLE_METHOD | 1 | NAME | |
| 2 | RET_DOMAIN | ||
| 3 | ARG_DOMAIN | ||
| PDO::CUBRID_SCH_METHOD_FILE | 1 | METHOD_FILE | |
| PDO::CUBRID_SCH_SUPER_TABLE / PDO::CUBRID_SCH_DIRECT_SUPER_TABLE / PDO::CUBRID_SCH_SUB_TABLE | 1 | CLASS_NAME | |
| 2 | TYPE | 0:system table 1:view 2:table | |
| PDO::CUBRID_SCH_CONSTRAINT | 1 | TYPE | 0:unique 1:index 2:reverse unique 3:reverse index |
| 2 | NAME | ||
| 3 | ATTR_NAME | ||
| 4 | NUM_PAGES | ||
| 5 | NUM_KEYS | ||
| 6 | PRIMARY_KEY | 1:primary key | |
| 7 | KEY_ORDER | base:1 | |
| PDO::CUBRID_SCH_TRIGGER | 1 | NAME | |
| 2 | STATUS | ||
| 3 | EVENT | ||
| 4 | TARGET_CLASS | ||
| 5 | TARGET_ATTR | ||
| 6 | ACTION_TIME | ||
| 7 | ACTION | ||
| 8 | PRIORITY | ||
| 9 | CONDITION_TIME | ||
| 10 | CONDITION | ||
| PDO::CUBRID_SCH_TABLE_PRIVILEGE / PDO::CUBRID_SCH_COL_PRIVILEGE | 1 | CLASS_NAME / ATTR_NAME | |
| 2 | PRIVILEGE | ||
| 3 | GRANTABLE | ||
| PDO::CUBRID_SCH_PRIMARY_KEY | 1 | CLASS_NAME | |
| 2 | ATTR_NAME | ||
| 3 | KEY_SEQ | base:1 | |
| 4 | KEY_NAME | ||
| PDO::CUBRID_SCH_IMPORTED_KEYS / PDO::CUBRID_SCH_EXPORTED_KEYS / PDO::CUBRID_SCH_CROSS_REFERENCE | 1 | PKTABLE_NAME | |
| 2 | PKCOLUMN_NAME | ||
| 3 | FKTABLE_NAME | base:1 | |
| 4 | FKCOLUMN_NAME | ||
| 5 | KEY_SEQ | base:1 | |
| 6 | UPDATE_ACTION | 0:cascade 1:restrict 2:no action 3:set null | |
| 7 | DELETE_ACTION | 0:cascade 1:restrict 2:no action 3:set null | |
| 8 | FK_NAME | ||
| 9 | PK_NAME |
Parametry
-
schema_type -
Schema type that you want to know.
-
table_name -
Table you want to know the schema of.
-
col_name -
Column you want to know the schema of.
Zwracane wartości
Array containing the schema information, when process is successful;
FALSE, when process is unsuccessful
Przykłady
Przykład #1 A PDO::cubrid_schema() example
This example shows how to get primary key and foreign keys of table game.
<?php
$pk_list = $dbh->cubrid_schema(PDO::CUBRID_SCH_PRIMARY_KEY, "game");
print_r($pk_list);
$fk_list = $dbh->cubrid_schema(PDO::CUBRID_SCH_IMPORTED_KEYS, "game");
print_r($fk_list);
?>
Powyższy przykład wyświetli:
Result:
Array
(
[0] => Array
(
[CLASS_NAME] => game
[ATTR_NAME] => athlete_code
[KEY_SEQ] => 3
[KEY_NAME] => pk_game_host_year_event_code_athlete_code
)
[1] => Array
(
[CLASS_NAME] => game
[ATTR_NAME] => event_code
[KEY_SEQ] => 2
[KEY_NAME] => pk_game_host_year_event_code_athlete_code
)
[2] => Array
(
[CLASS_NAME] => game
[ATTR_NAME] => host_year
[KEY_SEQ] => 1
[KEY_NAME] => pk_game_host_year_event_code_athlete_code
)
)
Array
(
[0] => Array
(
[PKTABLE_NAME] => athlete
[PKCOLUMN_NAME] => code
[FKTABLE_NAME] => game
[FKCOLUMN_NAME] => athlete_code
[KEY_SEQ] => 1
[UPDATE_RULE] => 1
[DELETE_RULE] => 1
[FK_NAME] => fk_game_athlete_code
[PK_NAME] => pk_athlete_code
)
[1] => Array
(
[PKTABLE_NAME] => event
[PKCOLUMN_NAME] => code
[FKTABLE_NAME] => game
[FKCOLUMN_NAME] => event_code
[KEY_SEQ] => 1
[UPDATE_RULE] => 1
[DELETE_RULE] => 1
[FK_NAME] => fk_game_event_code
[PK_NAME] => pk_event_code
)
)
Spis treści
- PDO_CUBRID DSN — Connecting to CUBRID databases
- PDO::cubrid_schema — Get the requested schema information
Microsoft SQL Server and Sybase Functions (PDO_DBLIB)
Wstęp
Ten moduł jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie tych funkcji, ich nazw, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tego modułu na własne ryzyko.
This extension is not available anymore on Windows with PHP 5.3 or later.
On Windows, you should use SqlSrv, an alternative driver for MS SQL is available from Microsoft: » http://msdn.microsoft.com/en-us/sqlserver/ff657782.aspx .
If it is not possible to use SqlSrv, you can use the PDO_ODBC driver to connect to Microsoft SQL Server and Sybase databases, as the native Windows DB-LIB is ancient, thread un-safe and no longer supported by Microsoft.
PDO_DBLIB DSN
(PECL PDO_DBLIB >= 0.9.0)
PDO_DBLIB DSN — Connecting to Microsoft SQL Server and Sybase databases
Opis
The PDO_DBLIB Data Source Name (DSN) is composed of the following elements:
- DSN prefix
-
The DSN prefix is
sybase:if PDO_DBLIB was linked against the Sybase ct-lib libraries,mssql:if PDO_DBLIB was linked against the Microsoft SQL Server libraries, ordblib:if PDO_DBLIB was linked against the FreeTDS libraries. - host
-
The hostname on which the database server resides. Defaults to 127.0.0.1.
- dbname
-
The name of the database.
- charset
-
The client character set.
- appname
-
The application name (used in sysprocesses). Defaults to "PHP Generic DB-lib" or "PHP freetds".
- secure
-
Currently unused.
Przykłady
Przykład #1 PDO_DBLIB DSN examples
The following examples show a PDO_DBLIB DSN for connecting to Microsoft SQL Server and Sybase databases:
mssql:host=localhost;dbname=testdb sybase:host=localhost;dbname=testdb dblib:host=localhost;dbname=testdb
Spis treści
- PDO_DBLIB DSN — Connecting to Microsoft SQL Server and Sybase databases
Firebird/Interbase Functions (PDO_FIREBIRD)
Wstęp
Ten moduł jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie tych funkcji, ich nazw, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tego modułu na własne ryzyko.
Instalacja
Use --with-pdo-firebird[=DIR] to install the PDO Firebird extension, where the optional [=DIR] is the Firebird base install directory.
$ ./configure --with-pdo-firebird
Stałe predefiniowane
Poniższe stałe są definiowane przez ten sterownik, i będą dostępne tylko, gdy
to rozszerzenie będzie skompilowane z PHP lub załadowane dynamicznie przy
starcie. Dodatkowo, te specyficzne dla sterownika stałe powinny być używane
tylko przy użyciu tego konkretnego sterownika. Używanie atrybutów bazy MySQL
przy użyciu sterownika PostgreSQL może prowadzić do nieprzewidzianego zachowania.
Jeśli skrypt korzysta z wielu sterowników, do pobrania atrybutu
PDO_ATTR_DRIVER_NAME, zawierającego
nazwę sterownika, można zastosować funkcję
PDO::getAttribute().
PDO_FIREBIRD DSN
(PECL PDO_FIREBIRD >= 0.1.0)
PDO_FIREBIRD DSN — Connecting to Firebird and Interbase databases
Opis
The PDO_FIREBIRD Data Source Name (DSN) is composed of the following elements:
- DSN prefix
-
The DSN prefix is
firebird:. - dbname
-
The name of the database.
- charset
-
The character set.
- role
-
The SQL role name.
Przykłady
Przykład #1 PDO_FIREBIRD DSN examples
The following example shows a PDO_FIREBIRD DSN for connecting to Firebird and Interbase databases:
firebird:dbname=DATABASE.GDE
Spis treści
- PDO_FIREBIRD DSN — Connecting to Firebird and Interbase databases
IBM Functions (PDO_IBM)
Wstęp
PDO_IBM is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to IBM databases.
Instalacja
To build the PDO_IBM extension, the DB2 Client v9.1 or later must be installed on the same system as PHP. The DB2 Client can be downloaded from the IBM » Application Development Site.
Informacja: Note
The DB2 Client v9.1 or later supports direct access to DB2 for Linux, UNIX, and Windows v8 and v9.1 servers.
The DB2 Client v9.1 also supports access to DB2 UDB for i5 and DB2 UDB for z/OS servers using the separately purchased » DB2 Connect product.
PDO_IBM is a » PECL extension, so follow the instructions in Installation of PECL extensions to install the PDO_IBM extension. Issue the configure command to point to the location of your DB2 Client header files and libraries as follows:
bash$ ./configure --with-pdo-ibm=/path/to/sqllib[,shared]
PDO_IBM DSN
(PECL PDO_IBM >= 0.9.0)
PDO_IBM DSN — Connecting to IBM databases
Opis
The PDO_IBM Data Source Name (DSN) is based on the IBM CLI DSN. The major components of the PDO_IBM DSN are:
- DSN prefix
-
The DSN prefix is
ibm:. - DSN
-
The DSN can be any of the following:
-
a) Data source setup using db2cli.ini or odbc.ini
-
b) Catalogued database name i.e. database alias in the DB2 client catalog
-
c) Complete connection string in the following format:
DRIVER={IBM DB2 ODBC DRIVER};DATABASE=where the parameters represent the following values:database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=username;PWD=password;-
database -
The name of the database.
-
hostname -
The hostname or IP address of the database server.
-
port -
The TCP/IP port on which the database is listening for requests.
-
username -
The username with which you are connecting to the database.
-
password -
The password with which you are connecting to the database.
-
-
Przykłady
Przykład #1 PDO_IBM DSN example using db2cli.ini
The following example shows a PDO_IBM DSN for connecting to an DB2 database cataloged as DB2_9 in db2cli.ini:
$db = new PDO("ibm:DSN=DB2_9", "", "");
[DB2_9]
Database=testdb
Protocol=tcpip
Hostname=11.22.33.444
Servicename=56789
Przykład #2 PDO_IBM DSN example using a connection string
The following example shows a PDO_IBM DSN for connecting to an DB2
database named testdb using the DB2 CLI
connection string syntax.
$db = new PDO("ibm:DRIVER={IBM DB2 ODBC DRIVER};DATABASE=testdb;" .
"HOSTNAME=11.22.33.444;PORT=56789;PROTOCOL=TCPIP;", "testuser", "tespass");
Spis treści
- PDO_IBM DSN — Connecting to IBM databases
Informix Functions (PDO_INFORMIX)
Wstęp
PDO_INFORMIX is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to Informix databases.
Instalacja
To build the PDO_INFORMIX extension, the Informix Client SDK 2.81 UC1 or higher must be installed on the same system as PHP. The Informix Client SDK is available from the » IBM Informix Support Site.
PDO_INFORMIX is a » PECL extension, so follow the instructions in Installation of PECL extensions to install the PDO_INFORMIX extension. Issue the configure command to point to the location of your Informix Client SDK header files and libraries as follows:
bash$ ./configure --with-pdo-informix=/path/to/SDK[,shared]
Scrollable cursors
PDO_INFORMIX supports scrollable cursors; however, they are not enabled
by default. To enable scrollable cursor support, you must either set
ENABLESCROLLABLECURSORS=1 in the corresponding ODBC
connection settings in odbc.ini or pass
the EnableScrollableCursors=1 clause in the DSN
connection string.
PDO_INFORMIX DSN
(PECL PDO_INFORMIX >= 0.1.0)
PDO_INFORMIX DSN — Connecting to Informix databases
Opis
The PDO_INFORMIX Data Source Name (DSN) is based on the Informix ODBC DSN string. Details on configuring an Informix ODBC DSN are available from the » Informix Dynamic Server Information Center. The major components of the PDO_INFORMIX DSN are:
- DSN prefix
-
The DSN prefix is
informix:. - DSN
-
The DSN can be either a data source setup using odbc.ini or a complete » connection string.
Przykłady
Przykład #1 PDO_INFORMIX DSN example using odbc.ini
The following example shows a PDO_INFORMIX DSN for connecting to an Informix database cataloged as Infdrv33 in odbc.ini:
$db = new PDO("informix:DSN=Infdrv33", "", "");
[ODBC Data Sources] Infdrv33=INFORMIX 3.3 32-BIT [Infdrv33] Driver=/opt/informix/csdk_2.81.UC1G2/lib/cli/iclis09b.so Description=INFORMIX 3.3 32-BIT Database=common_db LogonID=testuser pwd=testpass Servername=ids_server DB_LOCALE=en_US.819 OPTIMIZEAUTOCOMMIT=1 ENABLESCROLLABLECURSORS=1
Przykład #2 PDO_INFORMIX DSN example using a connection string
The following example shows a PDO_INFORMIX DSN for connecting to
an Informix database named common_db using the
Informix connection string syntax.
$db = new PDO("informix:host=host.domain.com; service=9800;
database=common_db; server=ids_server; protocol=onsoctcp;
EnableScrollableCursors=1", "testuser", "tespass");
Spis treści
- PDO_INFORMIX DSN — Connecting to Informix databases
MySQL Functions (PDO_MYSQL)
Wstęp
PDO_MYSQL is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to MySQL 3.x, 4.x and 5.x databases.
PDO_MYSQL will take advantage of native prepared statement support present in MySQL 4.1 and higher. If you're using an older version of the mysql client libraries, PDO will emulate them for you.
Beware: Some MySQL table types (storage engines) do not support transactions. When writing transactional database code using a table type that does not support transactions, MySQL will pretend that a transaction was initiated successfully. In addition, any DDL queries issued will implicitly commit any pending transactions.
Instalacja
Use --with-pdo-mysql[=DIR] to install the PDO MySQL extension, where the optional [=DIR] is the MySQL base install directory. If mysqlnd is passed as [=DIR], then the MySQL native driver will be used.
Optionally, the --with-mysql-sock[=DIR] sets to location to the MySQL unix socket pointer for all MySQL extensions, including PDO_MYSQL. If unspecified, the default locations are searched.
Optionally, the --with-zlib-dir[=DIR] is used to set the path to the libz install prefix.
$ ./configure --with-pdo-mysql --with-mysql-sock=/var/mysql/mysql.sock
SSL support is enabled using the appropriate PDO_MySQL constants, which is equivalent to calling the » MySQL C API function mysql_ssl_set(). Also, SSL cannot be enabled with PDO::setAttribute because the connection already exists. See also the MySQL documentation about » connecting to MySQL with SSL.
| Wersja | Opis |
|---|---|
| 5.4.0 | MySQL client libraries 4.1 and below are no longer supported. |
| 5.3.9 | Added SSL support with mysqlnd and OpenSSL. |
| 5.3.7 | Added SSL support with libmysql and OpenSSL. |
Stałe predefiniowane
Poniższe stałe są definiowane przez ten sterownik, i będą dostępne tylko, gdy
to rozszerzenie będzie skompilowane z PHP lub załadowane dynamicznie przy
starcie. Dodatkowo, te specyficzne dla sterownika stałe powinny być używane
tylko przy użyciu tego konkretnego sterownika. Używanie atrybutów bazy MySQL
przy użyciu sterownika PostgreSQL może prowadzić do nieprzewidzianego zachowania.
Jeśli skrypt korzysta z wielu sterowników, do pobrania atrybutu
PDO_ATTR_DRIVER_NAME, zawierającego
nazwę sterownika, można zastosować funkcję
PDO::getAttribute().
-
PDO::MYSQL_ATTR_USE_BUFFERED_QUERY(integer) -
If this attribute is set to
TRUEon a PDOStatement, the MySQL driver will use the buffered versions of the MySQL API. If you're writing portable code, you should use PDOStatement::fetchAll() instead.Przykład #1 Forcing queries to be buffered in mysql
<?php
if ($db->getAttribute(PDO::ATTR_DRIVER_NAME) == 'mysql') {
$stmt = $db->prepare('select * from foo',
array(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY => true));
} else {
die("my application only works with mysql; I should use \$stmt->fetchAll() instead");
}
?> -
PDO::MYSQL_ATTR_LOCAL_INFILE(integer) -
Enable LOAD LOCAL INFILE.
Note, this constant can only be used in the
driver_optionsarray when constructing a new database handle. -
PDO::MYSQL_ATTR_INIT_COMMAND(integer) -
Command to execute when connecting to the MySQL server. Will automatically be re-executed when reconnecting.
Note, this constant can only be used in the
driver_optionsarray when constructing a new database handle. -
PDO::MYSQL_ATTR_READ_DEFAULT_FILE(integer) -
Read options from the named option file instead of from my.cnf. This option is not available if mysqlnd is used, because mysqlnd does not read the mysql configuration files.
-
PDO::MYSQL_ATTR_READ_DEFAULT_GROUP(integer) -
Read options from the named group from my.cnf or the file specified with
MYSQL_READ_DEFAULT_FILE. This option is not available if mysqlnd is used, because mysqlnd does not read the mysql configuration files. -
PDO::MYSQL_ATTR_MAX_BUFFER_SIZE(integer) -
Maximum buffer size. Defaults to 1 MiB. This constant is not supported when compiled against mysqlnd.
-
PDO::MYSQL_ATTR_DIRECT_QUERY(integer) -
Perform direct queries, don't use prepared statements.
-
PDO::MYSQL_ATTR_FOUND_ROWS(integer) -
Return the number of found (matched) rows, not the number of changed rows.
-
PDO::MYSQL_ATTR_IGNORE_SPACE(integer) -
Permit spaces after function names. Makes all functions names reserved words.
-
PDO::MYSQL_ATTR_COMPRESS(integer) -
Enable network communication compression. This is not supported when compiled against mysqlnd.
-
PDO::MYSQL_ATTR_SSL_CA(integer) -
The file path to the SSL certificate authority.
This exists as of PHP 5.3.7.
-
PDO::MYSQL_ATTR_SSL_CAPATH(integer) -
The file path to the directory that contains the trusted SSL CA certificates, which are stored in PEM format.
This exists as of PHP 5.3.7.
-
PDO::MYSQL_ATTR_SSL_CERT(integer) -
The file path to the SSL certificate.
This exists as of PHP 5.3.7.
-
PDO::MYSQL_ATTR_CIPHER(integer) -
A list of one or more permissible ciphers to use for SSL encryption, in a format understood by OpenSSL. For example: DHE-RSA-AES256-SHA:AES128-SHA
This exists as of PHP 5.3.7.
-
PDO::MYSQL_ATTR_KEY(integer) -
The file path to the SSL key.
This exists as of PHP 5.3.7.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian |
|---|---|---|
| pdo_mysql.default_socket | "/tmp/mysql.sock" | PHP_INI_SYSTEM |
| pdo_mysql.debug | NULL | PHP_INI_SYSTEM |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
pdo_mysql.default_socketstring -
Sets a Unix domain socket. This value can either be set at compile time if a domain socket is found at configure. This ini setting is Unix only.
-
pdo_mysql.debugboolean -
Enables debugging for PDO_MYSQL. This setting is only available when PDO_MYSQL is compiled against mysqlnd and in PDO debug mode.
PDO_MYSQL DSN
(PECL PDO_MYSQL >= 0.1.0)
PDO_MYSQL DSN — Connecting to MySQL databases
Opis
The PDO_MYSQL Data Source Name (DSN) is composed of the following elements:
- DSN prefix
-
The DSN prefix is
mysql:. - host
-
The hostname on which the database server resides.
- port
-
The port number where the database server is listening.
- dbname
-
The name of the database.
- unix_socket
-
The MySQL Unix socket (shouldn't be used with host or port).
- charset
-
The character set.
Prior to PHP 5.3.6, this element was silently ignored. The same behaviour can be partly replicated with the
PDO::MYSQL_ATTR_INIT_COMMANDdriver option, as the following example shows.OstrzeżenieThe method in the below example can only be used with character sets that share the same lower 7 bit representation as ASCII, such as ISO-8859-1 and UTF-8. Users using character sets that have different representations (such as UTF-16 or Big5) must use the charset option provided in PHP 5.3.6 and later versions.
Przykład #1 Setting the connection character set to UTF-8 prior to PHP 5.3.6
<?php
$dsn = 'mysql:host=localhost;dbname=testdb';
$username = 'username';
$password = 'password';
$options = array(
PDO::MYSQL_ATTR_INIT_COMMAND => 'SET NAMES utf8',
);
$dbh = new PDO($dsn, $username, $password, $options);
?>
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.6 | Prior to version 5.3.6, charset was ignored. |
Przykłady
Przykład #2 PDO_MYSQL DSN examples
The following example shows a PDO_MYSQL DSN for connecting to MySQL databases:
mysql:host=localhost;dbname=testdb
mysql:host=localhost;port=3307;dbname=testdb mysql:unix_socket=/tmp/mysql.sock;dbname=testdb
Notatki
Informacja: Unix only:
When the host name is set to "localhost", then the connection to the server is made thru a domain socket. If PDO_MYSQL is compiled against libmysql then the location of the socket file is at libmysql's compiled in location. If PDO_MYSQL is compiled against mysqlnd a default socket can be set thru the pdo_mysql.default_socket setting.
Spis treści
- PDO_MYSQL DSN — Connecting to MySQL databases
Microsoft SQL Server Functions (PDO_SQLSRV)
Wstęp
PDO_SQLSRV is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to MS SQL Server (starting with SQL Server 2005) and SQL Azure databases.
Instalacja
The PDO_SQLSRV extension is enabled by adding appropriate DLL file to your PHP extension directory and the corresponding entry to the php.ini file. The PDO_SQLSRV download comes with several driver files. Which driver file you use will depend on 3 factors: the PHP version you are using, whether you are using thread-safe or non-thread-safe PHP, and whether your PHP installation was compiled with the VC6 or VC9 compiler. For example, if you are running PHP 5.3, you are using non-thread-safe PHP, and your PHP installation was compiled with the VC9 compiler, you should use the php_pdo_sqlsrv_53_nts_vc9.dll file. (You should use a non-thread-safe version compiled with the VC9 compiler if you are using IIS as your web server). If you are running PHP 5.2, you are using thread-safe PHP, and your PHP installation was compiled with the VC6 compiler, you should use the php_pdo_sqlsrv_52_ts_vc6.dll file.
For more information about system requirements, see » SQLSRV System Requirements.
The PDO_SQLSRV extension is only compatible with PHP running on Windows. For Linux, see ODBC and » Microsoft's SQL Server ODBC Driver for Linux.
Stałe predefiniowane
Poniższe stałe są definiowane przez ten sterownik, i będą dostępne tylko, gdy
to rozszerzenie będzie skompilowane z PHP lub załadowane dynamicznie przy
starcie. Dodatkowo, te specyficzne dla sterownika stałe powinny być używane
tylko przy użyciu tego konkretnego sterownika. Używanie atrybutów bazy MySQL
przy użyciu sterownika PostgreSQL może prowadzić do nieprzewidzianego zachowania.
Jeśli skrypt korzysta z wielu sterowników, do pobrania atrybutu
PDO_ATTR_DRIVER_NAME, zawierającego
nazwę sterownika, można zastosować funkcję
PDO::getAttribute().
-
PDO::SQLSRV_TXN_READ_UNCOMMITTED(integer) - This constant is an acceptable value for the SQLSRV DSN key TransactionIsolation. This constant sets the transaction isolation level for the connection to Read Uncommitted.
-
PDO::SQLSRV_TXN_READ_COMMITTED(integer) - This constant is an acceptable value for the SQLSRV DSN key TransactionIsolation. This constant sets the transaction isolation level for the connection to Read Committed.
-
PDO::SQLSRV_TXN_REPEATABLE_READ(integer) - This constant is an acceptable value for the SQLSRV DSN key TransactionIsolation. This constant sets the transaction isolation level for the connection to Repeateable Read.
-
PDO::SQLSRV_TXN_SNAPSHOT(integer) - This constant is an acceptable value for the SQLSRV DSN key TransactionIsolation. This constant sets the transaction isolation level for the connection to Snapshot.
-
PDO::SQLSRV_TXN_SERIALIZABLE(integer) - This constant is an acceptable value for the SQLSRV DSN key TransactionIsolation. This constant sets the transaction isolation level for the connection to Serializable.
-
PDO::SQLSRV_ENCODING_BINARY(integer) - Specifies that data is sent/retrieved as a raw byte stream to/from the server without performing encoding or translation. This constant can be passed to PDOStatement::setAttribute, PDO::prepare, PDOStatement::bindColumn, and PDOStatement::bindParam.
-
PDO::SQLSRV_ENCODING_SYSTEM(integer) - Specifies that data is sent/retrieved to/from the server as 8-bit characters as specified in the code page of the Windows locale that is set on the system. Any multi-byte characters or characters that do not map into this code page are substituted with a single byte question mark (?) character. This constant can be passed to PDOStatement::setAttribute, PDO::setAttribute, PDO::prepare, PDOStatement::bindColumn, and PDOStatement::bindParam.
-
PDO::SQLSRV_ENCODING_UTF8(integer) - Specifies that data is sent/retrieved to/from the server in UTF-8 encoding. This is the default encoding. This constant can be passed to PDOStatement::setAttribute, PDO::setAttribute, PDO::prepare, PDOStatement::bindColumn, and PDOStatement::bindParam.
-
PDO::SQLSRV_ENCODING_DEFAULT(integer) - Specifies that data is sent/retrieved to/from the server according to PDO::SQLSRV_ENCODING_SYSTEM if specified during connection. The connection's encoding is used if specified in a prepare statement. This constant can be passed to PDOStatement::setAttribute, PDO::setAttribute, PDO::prepare, PDOStatement::bindColumn, and PDOStatement::bindParam.
-
PDO::SQLSRV_ATTR_QUERY_TIMEOUT(integer) - A non-negative integer representing the timeout period, in seconds. Zero (0) is the default and means no timeout. This constant can be passed to PDOStatement::setAttribute, PDO::setAttribute, and PDO::prepare.
-
PDO::SQLSRV_ATTR_DIRECT_QUERY(integer) - Indicates that a query should be executed directly, without being prepared. This constant can be passed to PDO::setAttribute, and PDO::prepare. For more information, see » Direct and Prepared Statement Execution.
PDO_SQLSRV DSN
(No version information available, might only be in SVN)
PDO_SQLSRV DSN — Connecting to MS SQL Server and SQL Azure databases
Opis
The PDO_SQLSRV Data Source Name (DSN) is composed of the following elements:
- DSN prefix
-
The DSN prefix is
sqlsrv:. - APP
-
The application name used in tracing.
- ConnectionPooling
-
Specifies whether the connection is assigned from a connection pool (1 or
TRUE) or not (0 orFALSE). - Database
-
The name of the database.
- Encrypt
-
Specifies whether the communication with SQL Server is encrypted (1 or
TRUE) or unencrypted (0 orFALSE). - Failover_Partner
-
Specifies the server and instance of the database's mirror (if enabled and configured) to use when the primary server is unavailable.
- LoginTimeout
-
Specifies the number of seconds to wait before failing the connection attempt.
- MultipleActiveResultSets
-
Disables or explicitly enables support for multiple active Result sets (MARS).
- QuotedId
-
Specifies whether to use SQL-92 rules for quoted identifiers (1 or
TRUE) or to use legacy Transact-SQL rules (0 or false). - Server
-
The name of the database server.
- TraceFile
-
Specifies the path for the file used for trace data.
- TraceOn
-
Specifies whether ODBC tracing is enabled (1 or
TRUE) or disabled (0 orFALSE) for the connection being established. - TransactionIsolation
-
Specifies the transaction isolation level. The accepted values for this option are PDO::SQLSRV_TXN_READ_UNCOMMITTED, PDO::SQLSRV_TXN_READ_COMMITTED, PDO::SQLSRV_TXN_REPEATABLE_READ, PDO::SQLSRV_TXN_SNAPSHOT, and PDO::SQLSRV_TXN_SERIALIZABLE.
- TrustServerCertificate
-
Specifies whether the client should trust (1 or
TRUE) or reject (0 orFALSE) a self-signed server certificate. - WSID
-
Specifies the name of the computer for tracing.
Przykłady
Przykład #1 PDO_SQLSRV DSN examples
The following example shows how to connecto to a specified MS SQL Server database:
$c = new PDO("sqlsrv:Server=localhost;Database=testdb", "UserName", "Password");
The following example shows how to connect to a MS SQL Server database on a specified port:
$c = new PDO("sqlsrv:Server=localhost,1521;Database=testdb", "UserName", "Password");
The following example shows how to connecto to a SQL Azure database with server ID 12345abcde. Note that when you connect to SQL Azure with PDO, your username will be UserName@12345abcde (UserName@ServerId).
$c = new PDO("sqlsrv:Server=12345abcde.database.windows.net;Database=testdb", "UserName@12345abcde", "Password");
Spis treści
- PDO_SQLSRV DSN — Connecting to MS SQL Server and SQL Azure databases
Oracle Functions (PDO_OCI)
Wstęp
Ten moduł jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie tych funkcji, ich nazw, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tego modułu na własne ryzyko.
Instalacja
Use --with-pdo-oci[=DIR] to install the PDO Oracle OCI extension, where the optional [=DIR] is the Oracle Home directory. [=DIR] defaults to the $ORACLE_HOME environment variable.
Use --with-pdo-oci=instantclient,prefix,version for an Oracle Instant Client SDK, where prefix and version are configured.
// Using $ORACLE_HOME $ ./configure --with-pdo-oci // Using OIC for Linux with 10.2.0.3 RPMs with a /usr prefix $ ./configure --with-pdo-oci=instantclient,/usr,10.2.0.3
PDO_OCI DSN
(PECL PDO_OCI >= 0.1.0)
PDO_OCI DSN — Connecting to Oracle databases
Opis
The PDO_OCI Data Source Name (DSN) is composed of the following elements:
- DSN prefix
-
The DSN prefix is
oci:. - dbname (Oracle Instant Client)
-
The URI for the Oracle Instant Client connection takes the form of
dbname=//hostname:port-number/database. If you are connecting to a database defined in tnsnames.ora, use only the name of the database:dbname=database. - charset
-
The client-side character set for the current environment handle.
Przykłady
Przykład #1 PDO_OCI DSN examples
The following examples show a PDO_OCI DSN for connecting to Oracle databases:
// Connect to a database defined in tnsnames.ora oci:dbname=mydb // Connect using the Oracle Instant Client oci:dbname=//localhost:1521/mydb
Spis treści
- PDO_OCI DSN — Connecting to Oracle databases
ODBC and DB2 Functions (PDO_ODBC)
Wstęp
PDO_ODBC is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to databases through ODBC drivers or through the IBM DB2 Call Level Interface (DB2 CLI) library. PDO_ODBC currently supports three different "flavours" of database drivers:
- ibm-db2
-
Supports access to IBM DB2 Universal Database, Cloudscape, and Apache Derby servers through the free DB2 client.
- unixODBC
-
Supports access to database servers through the unixODBC driver manager and the database's own ODBC drivers.
- generic
-
Offers a compile option for ODBC driver managers that are not explicitly supported by PDO_ODBC.
On Windows, PDO_ODBC is built into the PHP core by default. It is linked against the Windows ODBC Driver Manager so that PHP can connect to any database cataloged as a System DSN, and is the recommended driver for connecting to Microsoft SQL Server databases.
Instalacja
-
As of PHP 5.1, PDO_ODBC is included in the PHP source. You can compile the PDO_ODBC extension as either a static or shared module using the following configure commands.
- ibm_db2
-
To build PDO_ODBC with the ibm-db2 flavour, you have to have previously installed the DB2 application development headers on the same machine on which you are compiling PDO_ODBC. The DB2 application development headers are an installable option in the DB2 servers, and are also available as part of the DB2 Application Development Client freely available for download from the IBM DB2 Universal Database » support site.
./configure --with-pdo-odbc=ibm-db2,/opt/IBM/db2/V8.1/
If you do not supply a location for the DB2 libraries and headers to the configure command, PDO_ODBC defaults to /home/db2inst1/sqllib.
- unixODBC
-
If you do not supply a location for the unixODBC libraries and headers to the configure command, PDO_ODBC defaults to /usr/local.
./configure --with-pdo-odbc=unixODBC,/usr/local
- generic
-
./configure --with-pdo-odbc=generic,/usr/local,libname,ldflags,cflags
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| pdo_odbc.connection_pooling | "strict" | PHP_INI_ALL | Available since PHP 5.1.0. |
| pdo_odbc.db2_instance_name | NULL | PHP_INI_SYSTEM | Available since PHP 5.1.1. Ta przestarzała funkcja zostanie na pewno w przyszłości usunięta. |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
pdo_odbc.connection_poolingstring -
Whether to pool ODBC connections. Can be one of "strict", "relaxed" or "off" (equals to ""). The parameter describes how strict the connection manager should be when matching connection parameters to existing pooled connections.
strictis the recommend default, and will result in the use of cached connections only when all the connection parameters match exactly.relaxedwill result in the use of cached connections when similar connection parameters are used. This can result in increased use of the cache, at the risk of bleeding connection information between (for example) virtual hosts.This setting can only be changed from the php.ini file, and affects the entire process; any other modules loaded into the process that use the same ODBC libraries will be affected too, including the Unified ODBC extension.
Ostrzeżenierelaxedmatching should not be used on a shared server, for security reasons.WskazówkaLeave this setting at the default
strictsetting unless you have good reason to change it. -
pdo_odbc.db2_instance_namestring -
If you compile PDO_ODBC using the db2 flavour, this setting sets the value of the DB2INSTANCE environment variable on Linux and UNIX operating systems to the specified name of the DB2 instance. This enables PDO_ODBC to resolve the location of the DB2 libraries and make cataloged connections to DB2 databases.
This setting can only be changed from the php.ini file, and affects the entire process; any other modules loaded into the process that use the same ODBC libraries will be affected too, including the Unified ODBC extension.
This setting has no effect on Windows.
PDO_ODBC DSN
(PECL PDO_ODBC >= 0.1.0)
PDO_ODBC DSN — Connecting to ODBC or DB2 databases
Opis
The PDO_ODBC Data Source Name (DSN) is composed of the following elements:
- DSN prefix
-
The DSN prefix is
odbc:. If you are connecting to a database cataloged in the ODBC driver manager or the DB2 catalog, you can append the cataloged name of the database to the DSN. - DSN
-
The name of the database as cataloged in the ODBC driver manager or the DB2 catalog. Alternately, you can provide a complete ODBC connection string to connect to a database as described at » http://www.connectionstrings.com/.
- UID
-
The name of the user for the connection. If you specify the user name in the DSN, PDO ignores the value of the user name argument in the PDO constructor.
- PWD
-
The password of the user for the connection. If you specify the password in the DSN, PDO ignores the value of the password argument in the PDO constructor.
Przykłady
Przykład #1 PDO_ODBC DSN example (ODBC driver manager)
The following example shows a PDO_ODBC DSN for connecting to an ODBC database cataloged as testdb in the ODBC driver manager:
odbc:testdb
Przykład #2 PDO_ODBC DSN example (IBM DB2 uncataloged connection)
The following example shows a PDO_ODBC DSN for connecting to
an IBM DB2 database named SAMPLE using the full
ODBC DSN syntax:
odbc:DRIVER={IBM DB2 ODBC DRIVER};HOSTNAME=localhost;PORT=50000;DATABASE=SAMPLE;PROTOCOL=TCPIP;UID=db2inst1;PWD=ibmdb2;
Przykład #3 PDO_ODBC DSN example (Microsoft Access uncataloged connection)
The following example shows a PDO_ODBC DSN for connecting to
a Microsoft Access database stored at C:\db.mdb using the full
ODBC DSN syntax:
odbc:Driver={Microsoft Access Driver (*.mdb)};Dbq=C:\\db.mdb;Uid=Admin
Spis treści
- PDO_ODBC DSN — Connecting to ODBC or DB2 databases
PostgreSQL Functions (PDO_PGSQL)
Wstęp
PDO_PGSQL is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to PostgreSQL databases.
Typy zasobów
This extension defines a stream resource returned by PDO::pgsqlLOBOpen().
Instalacja
Use --with-pdo-pgsql[=DIR] to install the PDO PostgreSQL extension, where the optional [=DIR] is the PostgreSQL base install directory, or the path to pg_config.
$ ./configure --with-pdo-pgsql
PDO_PGSQL DSN
(PECL PDO_PGSQL >= 0.1.0)
PDO_PGSQL DSN — Connecting to PostgreSQL databases
Opis
The PDO_PGSQL Data Source Name (DSN) is composed of the following elements, delimited by spaces or semicolons:
- DSN prefix
-
The DSN prefix is
pgsql:. - host
-
The hostname on which the database server resides.
- port
-
The port on which the database server is running.
- dbname
-
The name of the database.
- user
-
The name of the user for the connection. If you specify the user name in the DSN, PDO ignores the value of the user name argument in the PDO constructor.
- password
-
The password of the user for the connection. If you specify the password in the DSN, PDO ignores the value of the password argument in the PDO constructor.
Informacja:
The bytea fields are returned as streams.
Przykłady
Przykład #1 PDO_PGSQL DSN examples
The following example shows a PDO_PGSQL DSN for connecting to a PostgreSQL database:
pgsql:host=localhost;port=5432;dbname=testdb;user=bruce;password=mypass
PDO::pgsqlLOBCreate
(PHP 5 >= 5.1.2, PECL pdo_pgsql >= 1.0.2)
PDO::pgsqlLOBCreate — Creates a new large object
Opis
PDO::pgsqlLOBCreate() creates a large object and returns the OID of that object. You may then open a stream on the object using PDO::pgsqlLOBOpen() to read or write data to it. The OID can be stored in columns of type OID and be used to reference the large object, without causing the row to grow arbitrarily large. The large object will continue to live in the database until it is removed by calling PDO::pgsqlLOBUnlink().
Large objects can be up to 2GB in size, but are cumbersome to use; you need to ensure that PDO::pgsqlLOBUnlink() is called prior to deleting the last row that references its OID from your database. In addition, large objects have no access controls. As an alternative, try the bytea column type; recent versions of PostgreSQL allow bytea columns of up to 1GB in size and transparently manage the storage for optimal row size.
Informacja: This function must be called within a transaction.
Parametry
PDO::pgsqlLOBCreate() takes no parameters.
Zwracane wartości
Returns the OID of the newly created large object on success, or FALSE
on failure.
Przykłady
Przykład #1 A PDO::pgsqlLOBCreate() example
This example creates a new large object and copies the contents of a file into it. The OID is then stored into a table.
<?php
$db = new PDO('pgsql:dbname=test host=localhost', $user, $pass);
$db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
$db->beginTransaction();
$oid = $db->pgsqlLOBCreate();
$stream = $db->pgsqlLOBOpen($oid, 'w');
$local = fopen($filename, 'rb');
stream_copy_to_stream($local, $stream);
$local = null;
$stream = null;
$stmt = $db->prepare("INSERT INTO BLOBS (ident, oid) VALUES (?, ?)");
$stmt->execute(array($some_id, $oid));
$db->commit();
?>
Zobacz też:
- PDO::pgsqlLOBOpen() - Opens an existing large object stream
- PDO::pgsqlLOBUnlink() - Deletes the large object
- pg_lo_create() - Tworzy wielki obiekt (Large Object - LO)
PDO::pgsqlLOBOpen
(PHP 5 >= 5.1.2, PECL pdo_pgsql >= 1.0.2)
PDO::pgsqlLOBOpen — Opens an existing large object stream
Opis
$oid
[, string $mode = "rb"
] )
PDO::pgsqlLOBOpen() opens a stream to access the data
referenced by oid. If mode
is r, the stream is opened for reading, if
mode is w, then the stream will
be opened for writing. You can use all the usual filesystem functions,
such as fread(), fwrite() and
fgets() to manipulate the contents of the stream.
Informacja: This function, and all manipulations of the large object, must be called and carried out within a transaction.
Parametry
-
oid -
A large object identifier.
-
mode -
If mode is r, open the stream for reading. If mode is w, open the stream for writing.
Zwracane wartości
Returns a stream resource on success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 A PDO::pgsqlLOBOpen() example
Following on from the PDO::pgsqlLOBCreate() example, this code snippet retrieves the large object from the database and outputs it to the browser.
<?php
$db = new PDO('pgsql:dbname=test host=localhost', $user, $pass);
$db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
$db->beginTransaction();
$stmt = $db->prepare("select oid from BLOBS where ident = ?");
$stmt->execute(array($some_id));
$stmt->bindColumn('oid', $lob, PDO::PARAM_LOB);
$stmt->fetch(PDO::FETCH_BOUND);
fpassthru($lob);
?>
Zobacz też:
- PDO::pgsqlLOBCreate() - Creates a new large object
- PDO::pgsqlLOBUnlink() - Deletes the large object
- pg_lo_open() - Otwiera wielki obiekt (Large Object - LO)
PDO::pgsqlLOBUnlink
(PHP 5 >= 5.1.2, PECL pdo_pgsql >= 1.0.2)
PDO::pgsqlLOBUnlink — Deletes the large object
Opis
$oid
)Deletes a large object from the database identified by OID.
Informacja: This function must be called within a transaction.
Parametry
-
oid -
A large object identifier
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 A PDO::pgsqlLOBUnlink() example
This example unlinks a large object from the database prior to deleting the row that references it from the blobs table we've been using in our PDO::pgsqlLOBCreate() and PDO::pgsqlLOBOpen() examples.
<?php
$db = new PDO('pgsql:dbname=test host=localhost', $user, $pass);
$db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
$db->beginTransaction();
$db->pgsqlLOBUnlink($oid);
$stmt = $db->prepare("DELETE FROM BLOBS where ident = ?");
$stmt->execute(array($some_id));
$db->commit();
?>
Zobacz też:
- PDO::pgsqlLOBOpen() - Opens an existing large object stream
- PDO::pgsqlLOBCreate() - Creates a new large object
Spis treści
- PDO_PGSQL DSN — Connecting to PostgreSQL databases
- PDO::pgsqlLOBCreate — Creates a new large object
- PDO::pgsqlLOBOpen — Opens an existing large object stream
- PDO::pgsqlLOBUnlink — Deletes the large object
SQLite Functions (PDO_SQLITE)
Wstęp
PDO_SQLITE is a driver that implements the PHP Data Objects (PDO) interface to enable access to SQLite 3 databases.
In PHP 5.1, the SQLite extension also provides a driver for SQLite 2 databases; while it is not technically a part of the PDO_SQLITE driver, it behaves similarly, so it is documented alongside it. The SQLite 2 driver for PDO is provided primarily to make it easier to import legacy SQLite 2 database files into an application that uses the faster, more efficient SQLite 3 driver. As a result, the SQLite 2 driver is not as feature-rich as the SQLite 3 driver.
Informacja:
PDO_SQLITE allows using strings apart from streams together with
PDO::PARAM_LOB.
Instalacja
The PDO_SQLITE PDO driver is enabled by default. To disable, --without-pdo-sqlite[=DIR] may be used, where the optional [=DIR] is the sqlite base install directory.
PDO_SQLITE DSN
(PECL PDO_SQLITE >= 0.2.0)
PDO_SQLITE DSN — Connecting to SQLite databases
Opis
The PDO_SQLITE Data Source Name (DSN) is composed of the following elements:
- DSN prefix (SQLite 3)
-
The DSN prefix is
sqlite:.-
To access a database on disk, append the absolute path to the DSN prefix.
-
To create a database in memory, append :memory: to the DSN prefix.
-
- DSN prefix (SQLite 2)
-
The SQLite extension in PHP 5.1 provides a PDO driver that supports accessing and creating SQLite 2 databases. This enables you to access databases you may have created with the SQLite extension in previous versions of PHP.
Informacja:
The sqlite2 driver is only available in PHP 5.1.x if you have enabled both PDO and ext/sqlite. It is not currently available via PECL.
The DSN prefix for connecting to SQLite 2 databases is
sqlite2:.-
To access a database on disk, append the absolute path to the DSN prefix.
-
To create a database in memory, append :memory: to the DSN prefix.
-
Przykłady
Przykład #1 PDO_SQLITE DSN examples
The following examples show PDO_SQLITE DSN for connecting to SQLite databases:
sqlite:/opt/databases/mydb.sq3 sqlite::memory: sqlite2:/opt/databases/mydb.sq2 sqlite2::memory:
PDO::sqliteCreateAggregate
(PHP 5 >= 5.1.0, PECL pdo_sqlite >= 1.0.0)
PDO::sqliteCreateAggregate — Registers an aggregating User Defined Function for use in SQL statements
Opis
$function_name
, callable $step_func
, callable $finalize_func
[, int $num_args
] )Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
This method is similar to PDO::sqliteCreateFunction except that it registers functions that can be used to calculate a result aggregated across all the rows of a query.
The key difference between this method and PDO::sqliteCreateFunction is that two functions are required to manage the aggregate.
Parametry
-
function_name -
The name of the function used in SQL statements.
-
step_func -
Callback function called for each row of the result set. Your PHP function should accumulate the result and store it in the aggregation context.
This function need to be defined as:
context will be
NULLfor the first row; on subsequent rows it will have the value that was previously returned from the step function; you should use this to maintain the aggregate state.rownumber will hold the current row number.
-
finalize_func -
Callback function to aggregate the "stepped" data from each row. Once all the rows have been processed, this function will be called and it should then take the data from the aggregation context and return the result. Callback functions should return a type understood by SQLite (i.e. scalar type).
This function need to be defined as:
context will hold the return value from the very last call to the step function.
rownumber will hold the number of rows over which the aggregate was performed.
The return value of this function will be used as the return value for the aggregate.
-
num_args -
Hint to the SQLite parser if the callback function accepts a predetermined number of arguments.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 max_length aggregation function example
<?php
$data = array(
'one',
'two',
'three',
'four',
'five',
'six',
'seven',
'eight',
'nine',
'ten',
);
$db = new PDO('sqlite::memory:');
$db->exec("CREATE TABLE strings(a)");
$insert = $db->prepare('INSERT INTO strings VALUES (?)');
foreach ($data as $str) {
$insert->execute(array($str));
}
$insert = null;
function max_len_step(&$context, $rownumber, $string)
{
if (strlen($string) > $context) {
$context = strlen($string);
}
return $context;
}
function max_len_finalize(&$context, $rownumber)
{
return $context;
}
$db->sqliteCreateAggregate('max_len', 'max_len_step', 'max_len_finalize');
var_dump($db->query('SELECT max_len(a) from strings')->fetchAll());
?>
In this example, we are creating an aggregating function that will
calculate the length of the longest string in one of the columns of the
table. For each row, the max_len_step function is
called and passed a context parameter. The context
parameter is just like any other PHP variable and be set to hold an array
or even an object value. In this example, we are simply using it to hold
the maximum length we have seen so far; if the
string has a length longer than the current
maximum, we update the context to hold this new maximum length.
After all of the rows have been processed, SQLite calls the
max_len_finalize function to determine the aggregate
result. Here, we could perform some kind of calculation based on the
data found in the context. In our simple example
though, we have been calculating the result as the query progressed, so we
simply need to return the context value.
It is NOT recommended for you to store a copy of the values in the context and then process them at the end, as you would cause SQLite to use a lot of memory to process the query - just think of how much memory you would need if a million rows were stored in memory, each containing a string 32 bytes in length.
You can use PDO::sqliteCreateFunction and PDO::sqliteCreateAggregate to override SQLite native SQL functions.
Informacja:
This method is not available with the SQLite2 driver. Use the old style sqlite API for that instead.
Zobacz też:
- PDO::sqliteCreateFunction
- sqlite_create_function() - Registers a "regular" User Defined Function for use in SQL statements
- sqlite_create_aggregate() - Register an aggregating UDF for use in SQL statements
PDO::sqliteCreateFunction
(PHP 5 >= 5.1.0, PECL pdo_sqlite >= 1.0.0)
PDO::sqliteCreateFunction — Registers a User Defined Function for use in SQL statements
Opis
$function_name
, callable $callback
[, int $num_args
] )Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
This method allows you to register a PHP function with SQLite as an UDF (User Defined Function), so that it can be called from within your SQL statements.
The UDF can be used in any SQL statement that can call functions, such as SELECT and UPDATE statements and also in triggers.
Parametry
-
function_name -
The name of the function used in SQL statements.
-
callback -
Callback function to handle the defined SQL function.
Informacja: Callback functions should return a type understood by SQLite (i.e. scalar type).
-
num_args -
Hint to the SQLite parser if the callback function accepts a predetermined number of arguments.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 PDO::sqliteCreateFunction() example
<?php
function md5_and_reverse($string)
{
return strrev(md5($string));
}
$db = new PDO('sqlite:sqlitedb');
$db->sqliteCreateFunction('md5rev', 'md5_and_reverse', 1);
$rows = $db->query('SELECT md5rev(filename) FROM files')->fetchAll();
?>
In this example, we have a function that calculates the md5 sum of a
string, and then reverses it. When the SQL statement executes, it
returns the value of the filename transformed by our function. The data
returned in $rows contains the processed result.
The beauty of this technique is that you do not need to process the result using a foreach loop after you have queried for the data.
You can use PDO::sqliteCreateFunction and PDO::sqliteCreateAggregate to override SQLite native SQL functions.
Informacja:
This method is not available with the SQLite2 driver. Use the old style sqlite API for that instead.
Zobacz też:
- PDO::sqliteCreateAggregate
- sqlite_create_function() - Registers a "regular" User Defined Function for use in SQL statements
- sqlite_create_aggregate() - Register an aggregating UDF for use in SQL statements
Spis treści
- PDO_SQLITE DSN — Connecting to SQLite databases
- PDO::sqliteCreateAggregate — Registers an aggregating User Defined Function for use in SQL statements
- PDO::sqliteCreateFunction — Registers a User Defined Function for use in SQL statements
4D Functions (PDO_4D)
Wstęp
Ten moduł jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie tych funkcji, ich nazw, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tego modułu na własne ryzyko.
PDO_4D is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to 4D databases.
4D is an integrated platform that speeds and simplifies the development and deployment of business applications, used in over 70 countries, by a community of thousands of developers and vertical solution providers, with millions of end-users worldwide.
By offering a suite of integrated tools such as an ANSI SQL relational and transactional database, a graphical development environment, a fourth-generation language with over 1000 high-level commands, a built-in HTTP server, application server, etc., 4D facilitates the creation and maintenance of applications from one to hundreds of simultaneous users, whether on Windows, Mac or from any Web client.
4D is also an open platform, offering a complete API for plug-in creation, including various connectors that allow it to act as a back-end or front-end for many environments (Oracle via OCI, SOAP client or server, Flex data source, all ODBC databases, XML over HTTP, etc.)
In addition to the ability to interact with 4D applications across Web Services, 4D databases can now be directly accessed using the PDO_4D driver.
More details about the 4D development environment on » http://www.4d.com/.
PDO_4D is known to work with 4D versions 12 beta and up, for Mac OS X and Windows. Older plat-forms may work, but are unsupported.
PDO_4D DSN
(No version information available, might only be in SVN)
PDO_4D DSN — Connecting to 4D SQL server
Opis
The PDO_4D DSN consists of:
- DSN prefix
-
The DSN prefix is
4D:. - host
-
The host on which the 4D SQL server is.
- port
-
The port number for the server. This is optional.
- user
-
The login name when connecting to the database.
- password
-
The password for the above login.
- dbname
-
The name of the database. This parameter is optional, and it is not used.
- charset
-
The 4D character set.
Przykłady
Przykład #1 DSN examples for PDO_4D
The following examples has two DSN for PDO_4D, that connects to a 4D database :
4D:host=localhost;charset=UTF-8
4D:host=localhost 4D:
Constants for PDO_4D
(No version information available, might only be in SVN)
Constants for PDO_4D — Constants for PDO_4D
Stałe predefiniowane
Poniższe stałe są definiowane przez ten sterownik, i będą dostępne tylko, gdy
to rozszerzenie będzie skompilowane z PHP lub załadowane dynamicznie przy
starcie. Dodatkowo, te specyficzne dla sterownika stałe powinny być używane
tylko przy użyciu tego konkretnego sterownika. Używanie atrybutów bazy MySQL
przy użyciu sterownika PostgreSQL może prowadzić do nieprzewidzianego zachowania.
Jeśli skrypt korzysta z wielu sterowników, do pobrania atrybutu
PDO_ATTR_DRIVER_NAME, zawierającego
nazwę sterownika, można zastosować funkcję
PDO::getAttribute().
SQL types with PDO_4D and PHP
(No version information available, might only be in SVN)
SQL types with PDO_4D and PHP — SQL types with PDO_4D and PHP
| Type SQL 4D | Equivalent 4D | Note |
|---|---|---|
| ALPHA_NUMERIC | TEXT | |
| VARCHAR | TEXT | |
| TEXT | TEXT | |
| TIMESTAMP | DATE | |
| INTERVAL | HOUR | |
| DURATION | HOUR | |
| BOOLEAN | BOOLEAN | |
| BIT | BOOLEAN | |
| BYTE | INT32 | |
| INT16 | SMALLINT | |
| SMALLINT | SMALLINT | |
| INT32 | INT32 | |
| INT | INT32 | |
| INT64 | INT64 | |
| NUMERIC | INT64 | |
| REAL | REAL | Unsupported (use VARCHAR conversion) |
| FLOAT | FLOAT | Unsupported (use VARCHAR conversion) |
| DOUBLE PRECISION | FLOAT | |
| BLOB | BLOB | Must use a prepared statement, and PDO::PARAM_LOB |
| BIT VARYING | BLOB | Must use a prepared statement, and PDO::PARAM_LOB |
| CLOB | TEXT | |
| PICTURE | PICTURE | Must use a prepared statement, and PDO::PARAM_LOB |
SQL acceptable by 4D
(No version information available, might only be in SVN)
SQL acceptable by 4D — PDO and SQL 4D
Opis
4D implements strictly the ANSI 89 standard, and have it enforced. It is highly recommended to read the 4D SQL documentation to learn about the available commands. The URL of the manual is : » http://doc.4d.com/. Below is a list of 4D SQL characteristics: it is not exhaustive, but may serve as an introduction.
| Characteristics | Alternative | Note |
|---|---|---|
| INTEGER | Modify the SQL to use INT. | INT is the supported integer type in 4Dv12.0. |
| CHAR | Use VARCHAR instead. | Unsupported in 4Dv12.0 |
| UNION | Unsupported. Make separate queries. | Unsupported in 4Dv12.0 |
| SELECT 1 + 1; | SELECT 1 + 1 FROM _USER_SCHEMAS; | FROM is required |
| FLOAT | Cast the FLOAT value into a FLOAT or STRING, with an SQL 4D function (CAST, ROUND, TRUNC or TRUNCATE) | Unsupported in current versions of the PDO_4D driver |
| Strong typing | Take care your SQL query, or your PHP code provides data with the expected type | One must provide the right type that 4D expect. One can't insert '1' (as a string) in an INTEGER column. |
| PDO::execute($row)() : only works if all the table's column are of type TEXT or VARCHAR | Use the prepared statements, and use the right types. | The PDO extension cast all values through execute() as string, and expect the SQL database to parse the values. |
| SELECT NULL FROM TABLE | Do not use NULL constants. Extract them from the table | It is not allowed to use the NULL constant in the select list |
| SELECT * FROM TABLE WHERE 1 | Use WHERE 1 = 1 | A constant can't be used in a WHERE clause |
| SHOW TABLES | Use system tables | The list of tables, schemas, index, etc. are in these system tables : _USER_TABLES, _USER_COLUMNS, _USER_INDEXES, _USER_CONSTRAINTS, _USER_IND_COLUMNS, _USER_CONS_COLUMNS, and _USER_SCHEMAS. |
| SQL structure delimiter | Use the following function to protect SQL elements: function sqlEscapeElement(elem) { return '[' . str_replace(']',']]', $elem) . ']'; } | To escape SQL elements names (tables, fields, users, groups, schema, primary key, etc.), the whole identifier must be between square brackets, and the closing brackets ']' must be doubled. |
Examples with PDO_4D
(No version information available, might only be in SVN)
Examples with PDO_4D — Examples PDO_4D
This basic example show how to connect, execute a query, read data and disconnect from a 4D SQL server.
Przykład #1 Basic example with PDO_4D
<?php
$dsn = '4D:host=localhost;charset=UTF-8';
$user = 'test';
$pass = 'test';
// Connection to the 4D SQL server
$db = new PDO($dsn, $user, $pass);
try {
$db->exec('CREATE TABLE test(id varCHAR(1) NOT NULL, val VARCHAR(10))');
} catch (PDOException $e) {
die("Erreur 4D : " . $e->getMessage());
}
$db->exec("INSERT INTO test VALUES('A', 'B')");
$db->exec("INSERT INTO test VALUES('C', 'D')");
$db->exec("INSERT INTO test VALUES('E', 'F')");
$stmt = $db->prepare('SELECT id, val from test');
$stmt->execute();
print_r($stmt->fetchAll());
unset($stmt);
unset($db);
?>
Powyższy przykład wyświetli:
Array
(
[0] => Array
(
[ID] => A
[0] => A
[VAL] => B
[1] => B
)
[1] => Array
(
[ID] => C
[0] => C
[VAL] => D
[1] => D
)
[2] => Array
(
[ID] => E
[0] => E
[VAL] => F
[1] => F
)
)
This example shows how to execute a query in 4D language, and how to read the result through PDO_4D.
Przykład #2 Accessing 4D language from pdo_4d
Set up a 4D method, called method. Make sure in the method properties that the option Available via SQL is checked. The 4D code is the following.
C_TEXTE($0) $0:=Version application(*);
The PHP code to use the above 4D method is :
<?php
$dsn = '4D:host=localhost;charset=UTF-8';
$user = 'test';
$pass = 'test';
// Connection to the 4D server
$db = new PDO($dsn, $user, $pass);
$stmt = $db->prepare('SELECT {FN method() AS VARCHAR } FROM _USER_SCHEMAS LIMIT 1');
$stmt->execute();
print_r($stmt->fetchAll());
unset($stmt);
unset($db);
?>
Powyższy przykład wyświetli:
(
[0] => Array
(
[<expression>] => F0011140
[0] => F0011140
)
)
Przykład #3 Escaping 4D table names
This examples illustrates how to escape characters in a 4D SQL query.
<?php
$dsn = '4D:host=localhost;charset=UTF-8';
$user = 'test';
$pass = 'test';
// Connection to 4D server 4D
$db = new PDO($dsn, $user, $pass);
$objects = array('[',']','[]','][','[[',']]','[[[',']]]','TBL ]]32[23');
foreach($objects as $id => $object) {
$object = str_replace(']',']]', $object);
print "$object\n";
$db->exec('CREATE TABLE IF NOT EXISTS ['.$object.'](['.$object.'] FLOAT)');
$req = "INSERT INTO [$object] ([$object]) VALUES ($id);";
$db->query($req);
$q = $db->prepare("SELECT [$object] FROM [$object]");
$q->execute();
$x[] = $q->fetch(PDO::FETCH_NUM);
$db->exec('DROP TABLE ['.$object.'];');
}
?>
Powyższy przykład wyświetli:
[ ]] []] ]][ [[ ]]]] [[[ ]]]]]] TBL ]]]]32[23
Spis treści
- PDO_4D DSN — Connecting to 4D SQL server
- Constants for PDO_4D — Constants for PDO_4D
- SQL types with PDO_4D and PHP — SQL types with PDO_4D and PHP
- SQL acceptable by 4D — PDO and SQL 4D
- Examples with PDO_4D — Examples PDO_4D
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Connections and Connection management
- Transactions and auto-commit
- Prepared statements and stored procedures
- Errors and error handling
- Large Objects (LOBs)
- PDO — The PDO class
- PDO::beginTransaction — Initiates a transaction
- PDO::commit — Commits a transaction
- PDO::__construct — Creates a PDO instance representing a connection to a database
- PDO::errorCode — Fetch the SQLSTATE associated with the last operation on the database handle
- PDO::errorInfo — Fetch extended error information associated with the last operation on the database handle
- PDO::exec — Execute an SQL statement and return the number of affected rows
- PDO::getAttribute — Retrieve a database connection attribute
- PDO::getAvailableDrivers — Return an array of available PDO drivers
- PDO::inTransaction — Checks if inside a transaction
- PDO::lastInsertId — Returns the ID of the last inserted row or sequence value
- PDO::prepare — Prepares a statement for execution and returns a statement object
- PDO::query — Executes an SQL statement, returning a result set as a PDOStatement object
- PDO::quote — Quotes a string for use in a query.
- PDO::rollBack — Rolls back a transaction
- PDO::setAttribute — Set an attribute
- PDOStatement — The PDOStatement class
- PDOStatement::bindColumn — Bind a column to a PHP variable
- PDOStatement::bindParam — Binds a parameter to the specified variable name
- PDOStatement::bindValue — Binds a value to a parameter
- PDOStatement::closeCursor — Closes the cursor, enabling the statement to be executed again.
- PDOStatement::columnCount — Returns the number of columns in the result set
- PDOStatement::debugDumpParams — Dump an SQL prepared command
- PDOStatement::errorCode — Fetch the SQLSTATE associated with the last operation on the statement handle
- PDOStatement::errorInfo — Fetch extended error information associated with the last operation on the statement handle
- PDOStatement::execute — Executes a prepared statement
- PDOStatement::fetch — Fetches the next row from a result set
- PDOStatement::fetchAll — Returns an array containing all of the result set rows
- PDOStatement::fetchColumn — Returns a single column from the next row of a result set
- PDOStatement::fetchObject — Fetches the next row and returns it as an object.
- PDOStatement::getAttribute — Retrieve a statement attribute
- PDOStatement::getColumnMeta — Returns metadata for a column in a result set
- PDOStatement::nextRowset — Advances to the next rowset in a multi-rowset statement handle
- PDOStatement::rowCount — Returns the number of rows affected by the last SQL statement
- PDOStatement::setAttribute — Set a statement attribute
- PDOStatement::setFetchMode — Set the default fetch mode for this statement
- PDOException — The PDOException class
- PDO Drivers
- CUBRID (PDO) — CUBRID Functions (PDO_CUBRID)
- MS SQL Server (PDO) — Microsoft SQL Server and Sybase Functions (PDO_DBLIB)
- Firebird/Interbase (PDO) — Firebird/Interbase Functions (PDO_FIREBIRD)
- IBM (PDO) — IBM Functions (PDO_IBM)
- Informix (PDO) — Informix Functions (PDO_INFORMIX)
- MySQL (PDO) — MySQL Functions (PDO_MYSQL)
- MS SQL Server (PDO) — Microsoft SQL Server Functions (PDO_SQLSRV)
- Oracle (PDO) — Oracle Functions (PDO_OCI)
- ODBC and DB2 (PDO) — ODBC and DB2 Functions (PDO_ODBC)
- PostgreSQL (PDO) — PostgreSQL Functions (PDO_PGSQL)
- SQLite (PDO) — SQLite Functions (PDO_SQLITE)
- 4D (PDO) — 4D Functions (PDO_4D)
- DBA — Database (dbm-style) Abstraction Layer
- dbx
- ODBC — ODBC (Unified)
- PDO — PHP Data Objects
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Connections and Connection management
- Transactions and auto-commit
- Prepared statements and stored procedures
- Errors and error handling
- Large Objects (LOBs)
- PDO — The PDO class
- PDOStatement — The PDOStatement class
- PDOException — The PDOException class
- PDO Drivers
Rozszerzenia producentów baz danych
CUBRID
Wstęp
These functions allow you to access CUBRID database servers. More information about CUBRID can be found at » CUBRID.
Documentation for CUBRID can be found at » CUBRID Documentation.
Instalacja/Konfiguracja
Spis treści
Wymagania
In order to have these functions available, you must install CUBRID, and compile CUBRID PHP Library with CUBRID support.
Instalacja
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/cubrid.
DLL z tym rozszerzeniem PECL można pobrać zarówno ze strony » PHP Downloads lub z » http://pecl4win.php.net/
For information about manual installation on Linux and Windows systems, please read the file build-guide.html included in the package.
Konfiguracja wykonawcza
There is no runtime configuration now.
Typy zasobów
There are three resource types used in CUBRID. The first one is the link identifier for a database connection, the second is the a resource which holds the result of a query, and the third a resource which holds the query results of BLOB/CLOB data types.
connection identifier
A connection identifier returned by cubrid_connect(), cubrid_connect_with_url(), cubrid_pconnect() and cubrid_pconnect_with_url().
request identifier
A request identifier returned by cubrid_prepare() and cubrid_execute().
LOB identifier
A LOB identifier returned by cubrid_lob_get().
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
The following constants can be used when executing SQL statement. They can be passed to cubrid_prepare() and cubrid_execute().
| Constant | Description |
|---|---|
| CUBRID_INCLUDE_OID | Determine whether to get OID during query execution. |
| CUBRID_ASYNC | Execute the query in asynchronous mode. |
| CUBRID_EXEC_QUERY_ALL | Execute the query in synchronous mode. This flag must be set when executing multiple SQL statements. |
The following constants can be used when fetching the results to specify fetch behaviour. They can be passed to cubrid_fetch() and cubrid_fetch_array().
| Constant | Description |
|---|---|
| CUBRID_NUM | Get query result as a numeric array (0-default). |
| CUBRID_ASSOC | Get query result as an associative array. |
| CUBRID_BOTH | Get query result as both numeric and associative arrays (default value). |
| CUBRID_OBJECT | Get query result an object. |
The following constants can be used when positioning the cursor in query results. They can be passed to or returned by cubrid_move_cursor().
| Constant | Description |
|---|---|
| CUBRID_CURSOR_FIRST | Move current cursor to the first position in the result. |
| CUBRID_CURSOR_CURRENT | Move current cursor as a default value if the origin is not specified. |
| CUBRID_CURSOR_LAST | Move current cursor to the last position in the result. |
| CUBRID_CURSOR_SUCCESS | Returned value of cubrid_move_cursor() function in case of success. This flag has been removed from 8.4.1. |
| CUBRID_NO_MORE_DATA | Returned value of cubrid_move_cursor() function in case of failure. This flag has been removed from 8.4.1. |
| CUBRID_CURSOR_ERROR | Returned value of cubrid_move_cursor() function in case of failure. This flag has been removed from 8.4.1. |
The following constants can be used when setting the auto-commit mode for the database connection. They can be passed to cubrid_set_autocommit() or returned by cubrid_get_autocommit().
| Constant | Description |
|---|---|
| CUBRID_AUTOCOMMIT_TRUE | Enable the auto-commit mode. |
| CUBRID_AUTOCOMMIT_FALSE | Disable the auto-commit mode. |
The following constants can be used when setting the database parameter. They can be passed to cubrid_set_db_parameter().
| Constant | Description |
|---|---|
| CUBRID_PARAM_ISOLATION_LEVEL | Transaction isolation level for the database connection. |
| CUBRID_PARAM_LOCK_TIMEOUT | Transaction timeout in seconds. |
The following constants can be used when setting the transaction isolation level. They can be passed to cubrid_set_db_parameter() or returned by cubrid_get_db_parameter().
| Constant | Description |
|---|---|
| TRAN_COMMIT_CLASS_UNCOMMIT_INSTANCE | The lowest isolation level (1). A dirty, non-repeatable or phantom read may occur for the tuple and a non-repeatable read may occur for the table as well. |
| TRAN_COMMIT_CLASS_COMMIT_INSTANCE | A relatively low isolation level (2). A dirty read does not occur, but non-repeatable or phantom read may occur. |
| TRAN_REP_CLASS_UNCOMMIT_INSTANCE | The default isolation of CUBRID (3). A dirty, non-repeatable or phantom read may occur for the tuple, but repeatable read is ensured for the table. |
| TRAN_REP_CLASS_COMMIT_INSTANCE | A relatively low isolation level (4). A dirty read does not occur, but non-repeatable or phantom read may. |
| TRAN_REP_CLASS_REP_INSTANCE | A relatively high isolation level (5). A dirty or non-repeatable read does not occur, but a phantom read may. |
| TRAN_SERIALIZABLE | The highest isolation level (6). Problems concerning concurrency (e.g. dirty read, non-repeatable read, phantom read, etc.) do not occur. |
The following constants can be used when getting schema information. They can be passed to cubrid_schema().
| Constant | Description |
|---|---|
| CUBRID_SCH_CLASS | Get name and type of table in CUBRID. |
| CUBRID_SCH_VCLASS | Get name and type of view in CUBRID. |
| CUBRID_SCH_QUERY_SPEC | Get the query definition of view. |
| CUBRID_SCH_ATTRIBUTE | Get the attributes of table column. |
| CUBRID_SCH_CLASS_ATTRIBUTE | Get the attributes of table. |
| CUBRID_SCH_METHOD | Get the instance method. The instance method is a method called by a class instance. It is used more often than the class method because most operations are executed in the instance. |
| CUBRID_SCH_CLASS_METHOD | Get the class method. The class method is a method called by a class object. It is usually used to create a new class instance or to initialize it. It is also used to access or update class attributes. |
| CUBRID_SCH_METHOD_FILE | Get the information of the file where the method of the table is defined. |
| CUBRID_SCH_SUPERCLASS | Get the name and type of table which table inherites attributes from. |
| CUBRID_SCH_SUBCLASS | Get the name and type of table which inherites attributes from this table. |
| CUBRID_SCH_CONSTRAINT | Get the table constraints. |
| CUBRID_SCH_TRIGGER | Get the table triggers. |
| CUBRID_SCH_CLASS_PRIVILEGE | Get the privilege information of table. |
| CUBRID_SCH_ATTR_PRIVILEGE | Get the privilege information of column. |
| CUBRID_SCH_DIRECT_SUPER_CLASS | Get the direct super table of table. |
| CUBRID_SCH_PRIMARY_KEY | Get the table primary key. |
| CUBRID_SCH_IMPORTED_KEYS | Get imported keys of table. |
| CUBRID_SCH_EXPORTED_KEYS | Get exported keys of table. |
| CUBRID_SCH_CROSS_REFERENCE | Get reference relationship of tow tables. |
The following constants can be used when reporting errors. They can be returned from cubrid_error_code_facility().
| Constant | Description |
|---|---|
| CUBRID_FACILITY_DBMS | The error occured in CUBRID dbms. |
| CUBRID_FACILITY_CAS | The error occured in CUBRID broker cas. |
| CUBRID_FACILITY_CCI | The error occured in CUBRID cci. |
| CUBRID_FACILITY_CLIENT | The error occured in CUBRID PHP client. |
Przykłady
The following is a simple example that establishes a connection between PHP and CUBRID. This section will cover the most basic and notable features. The following code required to connect to CUBRID database, which means CUBRID Server and CUBRID Broker have to be running.
The example below uses the demodb database as an examples. By default it is created during the installation. Make sure it has been created.
Przykład #1 Example of Data Retrieval
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=euc-kr">
</head>
<body>
<center>
<table border=2>
<?php
/**
* Set server information for CUBRID connection. host_ip is the IP
* address where the CUBRID Broker is installed (localhost in this
* example), and host_port is the port number of the CUBRID Broker.
* The port number is the default given during the installation.
* For details, see "Administrator's Guide."
*/
$host_ip = "localhost";
$host_port = 33000;
$db_name = "demodb";
/**
* Connect to CUBRID Server. Do not make the actual connection, but
* only retain the connection information. The reason for not making
* the actual connection is to handle transaction more efficiently
* in the 3-tier architecture.
*/
$cubrid_con = @cubrid_connect($host_ip, $host_port, $db_name);
if (!$cubrid_con) {
echo "Database Connection Error";
exit;
}
?>
<?php
$sql = "select sports, count(players) as players from event group by sports";
/**
* Request the CUBRID Server for the results of the SQL statement.
* Now make the actual connection to the CUBRID Server.
*/
$result = cubrid_execute($cubrid_con, $sql);
if ($result) {
/**
* Get the column names from the result set created by the SQL query.
*/
$columns = cubrid_column_names($result);
/**
* Get the number of columns in the result set created by the SQL query.
*/
$num_fields = cubrid_num_cols($result);
/**
* List the column names of the result set on the screen.
*/
echo("<tr>");
while (list($key, $colname) = each($columns)) {
echo("<td align=center>$colname</td>");
}
echo("</tr>");
/**
* Get the results from the result set.
*/
while ($row = cubrid_fetch($result)) {
echo("<tr>");
for ($i = 0; $i < $num_fields; $i++) {
echo("<td align=center>");
echo($row[$i]);
echo("</td>");
}
echo("</tr>");
}
}
/**
* The PHP module in the CUBRID runs in a 3-tier architecture. Even when
* calling SELECT for transaction processing, it is processed as a part
* of the transaction. Therefore, the transaction needs to be rolled back
* by calling commit or rollback even though SELECT was called for smooth
* performance.
*/
cubrid_commit($cubrid_con);
cubrid_disconnect($cubrid_con);
?>
</body>
</html>
Przykład #2 Example of Data Insertion
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=euc- kr">
</head>
<body>
<center>
<table border=2>
<?php
/**
* host_ip is the IP address where the CUBRID Broker is installed
* host_port is the port number of the CUBRID Broker
* db_name is the name of CUBRID Database
*/
$host_ip = "localhost";
$host_port = 33000;
$db_name = "demodb";
$cubrid_con = @cubrid_connect($host_ip, $host_port, $db_name);
if (!$cubrid_con) {
echo "Database Connection Error";
exit;
}
?>
<?php
$sql = "insert into olympic (host_year,host_nation,host_city,"
. "opening_date,closing_date) values (2008, 'China', 'Beijing',"
. "to_date('08-08-2008','mm-dd- yyyy'),to_date('08-24-2008','mm-dd-yyyy')) ;"
$result = cubrid_execute($cubrid_con, $sql);
if ($result) {
/**
* Handled successfully, so commit.
*/
cubrid_commit($cubrid_con);
echo("Inserted successfully ");
} else {
/**
* Error occurred, so the error message is output and rollback is called.
*/
echo(cubrid_error_msg());
cubrid_rollback($cubrid_con);
}
cubrid_disconnect($cubrid_con);
?>
</body>
</html>
CUBRID Funkcje
cubrid_bind
(PECL CUBRID >= 8.3.0)
cubrid_bind — Bind variables to a prepared statement as parameters
Opis
$req_identifier
, mixed $bind_param
, mixed $bind_value
[, string $bind_value_type
] )
The cubrid_bind() function is used to bind values to a
corresponding named or question mark placeholder in the SQL statement that
was passed to cubrid_prepare(). If
bind_value_type is not given, string will be the
default.
Informacja:
If the type of data to be bound is BLOB/CLOB, CUBRID will try to map the data as a PHP stream. If the actually bind value type is not stream, CUBRID will convert it to string, and use it as the full path and file name of a file on the client filesystem.
The following table shows the types of substitute values.
| Support | Bind Type | Corresponding SQL Type |
|---|---|---|
| Supported | STRING | CHAR, VARCHAR |
| NCHAR | NCHAR, NVARCHAR | |
| BIT | BIT, VARBIT | |
| NUMERIC or NUMBER | SHORT, INT, NUMERIC | |
| FLOAT | FLOAT | |
| DOUBLE | DOUBLE | |
| TIME | TIME | |
| DATE | DATE | |
| TIMESTAMP | TIMESTAMP | |
| OBJECT | OBJECT | |
| BLOB | BLOB | |
| CLOB | CLOB | |
| NULL | NULL | |
| Not supported | SET | SET |
| MULTISET | MULTISET | |
| SEQUENCE | SEQUENCE |
Parametry
-
req_identifier -
Request identifier as a result of cubrid_prepare().
-
bind_param -
Parameter identifier. For a prepared statement using named placeholders, this will be a parameter name of the form :name (Note that the name can only contain digit, alphabet, and underscore, and it can not begin with digit. The name length can not be longer than 32). For a prepared statement using question mark placeholders, this will be the 1-indexed position of the parameter.
-
bind_value -
Actual value for binding.
-
bind_value_type -
A type of the value to bind. (It is omitted by default. Thus, system internally use string by default. However, you need to specify the exact type of the value as an argument when they are NCHAR, BIT, or BLOB/CLOB).
Zwracane wartości
TRUE, when process is successful.
FALSE, when process is unsuccessful.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 8.4.0 | Added named parameter support; When binding the LOB data type, it can directly binding the path name of a file. |
| 8.3.1 | Added BLOB/CLOB data types support. |
Przykłady
Przykład #1 cubrid_bind() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$result = cubrid_execute($conn, "SELECT code FROM event WHERE sports='Basketball' and gender='M'");
$row = cubrid_fetch_array($result, CUBRID_ASSOC);
$event_code = $row["code"];
cubrid_close_request($result);
$game_req = cubrid_prepare($conn, "SELECT athlete_code FROM game WHERE host_year=1992 and event_code=? and nation_code='USA'");
cubrid_bind($game_req, 1, $event_code, "number");
cubrid_execute($game_req);
printf("--- Dream Team (1992 United States men's Olympic basketball team) ---\n");
while ($athlete_code = cubrid_fetch_array($game_req, CUBRID_NUM)) {
$athlete_req = cubrid_prepare($conn, "SELECT name FROM athlete WHERE code=? AND nation_code='USA' AND event='Basketball' AND gender='M'");
cubrid_bind($athlete_req, 1, $athlete_code[0], "number");
cubrid_execute($athlete_req);
$row = cubrid_fetch_assoc($athlete_req);
printf("%s\n", $row["name"]);
}
cubrid_close_request($game_req);
cubrid_close_request($athlete_req);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
--- Dream Team (1992 United States men's Olympic basketball team) --- Stockton John Robinson David Pippen Scottie Mullin C. Malone Karl Laettner C. Jordan Michael Johnson Earvin Ewing Patrick Drexler Clyde Bird Larry Barkley Charles
Przykład #2 cubrid_bind() named parameter example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$sql_stmt = <<<EOD
SELECT s.name FROM stadium s, game g
WHERE s.code = g.stadium_code AND g.medal = :medal_type
GROUP BY g.stadium_code ORDER BY count(medal) DESC LIMIT 1;
EOD;
$req = cubrid_prepare($conn, $sql_stmt);
printf("%-30s %s\n", "Medal Type", "Stadium where most medals were ever won");
cubrid_bind($req, ":medal_type", "G");
cubrid_execute($req);
$row = cubrid_fetch_assoc($req);
printf("%-30s %s\n", "Gold", $row["name"]);
cubrid_bind($req, ":medal_type", "S");
cubrid_execute($req);
$row = cubrid_fetch_assoc($req);
printf("%-30s %s\n", "Silver", $row["name"]);
cubrid_bind($req, ":medal_type", "B");
cubrid_execute($req);
$row = cubrid_fetch_assoc($req);
printf("%-30s %s\n", "Bronze", $row["name"]);
cubrid_close_request($req);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
Medal Type Stadium where most medals were ever won Gold Olympic Aquatic Centre Silver Olympic Aquatic Centre Bronze Sydney Convention and Exhibition Centre
Przykład #3 cubrid_bind() BLOB/CLOB example
<?php
$con = cubrid_connect("localhost", 33000, "foo");
if ($con) {
$sql = "INSERT INTO php_cubrid_lob_test(doc_content) VALUES(?)";
$req = cubrid_prepare($con, $sql);
$fp = fopen("book.txt", "rb");
cubrid_bind($req, 1, $fp, "clob");
cubrid_execute($req);
}
?>
Przykład #4 cubrid_bind() BLOB/CLOB example
<?php
$con = cubrid_connect("localhost", 33000, "foo");
if ($con) {
$sql = "INSERT INTO php_cubrid_lob_test(image) VALUES(?)";
$req = cubrid_prepare($con, $sql);
cubrid_bind($req, 1, "cubrid_logo.png", "blob");
cubrid_execute($req);
}
?>
Zobacz też:
- cubrid_execute() - Execute a prepared SQL statement
- cubrid_prepare() - Prepare an SQL statement for execution
cubrid_close_prepare
(PECL CUBRID >= 8.3.0)
cubrid_close_prepare — Close the request handle
Opis
$req_identifier
)
The cubrid_close_prepare() function closes the request
handle given by the req_identifier argument, and
releases the memory region related to the handle. It is a alias of
cubrid_close_request().
Parametry
-
req_identifier -
Request identifier.
Zwracane wartości
Return TRUE on success.
Przykłady
Przykład #1 cubrid_close_prepare() example
<?php
$con = cubrid_connect ("dbsvr.cubrid.com", 12345, "demodb");
if ($con) {
echo "connected successfully";
$req = cubrid_execute ( $con, "select * from members",
CUBRID_INCLUDE_OID | CUBRID_ASYNC);
if ($req) {
while ( list ($id, $name) = cubrid_fetch ($req) ){
echo $id;
echo $name;
}
cubrid_close_prepare($req); // or you can use cubrid_close_request($req)
}
cubrid_disconnect($con);
}
?>
cubrid_close_request
(PECL CUBRID >= 8.3.0)
cubrid_close_request — Close the request handle
Opis
$req_identifier
)
The cubrid_close_request() function closes the request
handle given by the req_identifier argument, and
releases the memory region related to the handle. It is a alias of
cubrid_close_prepare().
Parametry
-
req_identifier -
Request identifier.
Zwracane wartości
Return TRUE on success.
Przykłady
Przykład #1 cubrid_close_request() example
<?php
$con = cubrid_connect ("dbsvr.cubrid.com", 12345, "demodb");
if ($con) {
echo "connected successfully";
$req = cubrid_execute ( $con, "select * from members",
CUBRID_INCLUDE_OID | CUBRID_ASYNC);
if ($req) {
while ( list ($id, $name) = cubrid_fetch ($req) ){
echo $id;
echo $name;
}
cubrid_close_requst($req); // or you can use cubrid_close_prepare($req)
}
cubrid_disconnect($con);
}
?>
cubrid_col_get
(PECL CUBRID >= 8.3.0)
cubrid_col_get — Get contents of collection type column using OID
Opis
$conn_identifier
, string $oid
, string $attr_name
)The cubrid_col_get() function is used to get contents of the elements of the collection type (set, multiset, sequence) attribute you requested as an array.
Parametry
-
conn_identifier -
Connection identifier.
-
oid -
OID of the instance that you want to read.
-
attr_name -
Attribute name that you want to read from the instance.
Zwracane wartości
Array (0-based numerical array) containing the elements you requested, when process is successful;
FALSE (to distinguish the error from the situation of attribute having
empty collection or NULL, in case of error, a warning message is shown; in
such case you can check the error by using
cubrid_error_code()), when process is unsuccessful.
Przykłady
Przykład #1 cubrid_col_get() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
@cubrid_execute($conn, "DROP TABLE foo");
cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
$req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);
cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$oid = cubrid_current_oid($req);
$attr = cubrid_col_get($conn, $oid, "b");
var_dump($attr);
$size = cubrid_col_size($conn, $oid, "b");
var_dump($size);
cubrid_close_request($req);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
array(3) {
[0]=>
string(1) "1"
[1]=>
string(1) "2"
[2]=>
string(1) "3"
}
int(3)
cubrid_col_size
(PECL CUBRID >= 8.3.0)
cubrid_col_size — Get the number of elements in collection type column using OID
Opis
$conn_identifier
, string $oid
, string $attr_name
)The cubrid_col_size() function is used to get the number of elements in a collection type (set, multiset, sequence) attribute.
Parametry
-
conn_identifier -
Connection identifier.
-
oid -
OID the instance that you want to work with.
-
attr_name -
Name of the attribute that you want to work with.
Zwracane wartości
Number of elements, when process is successful.
FALSE, when process is unsuccessful.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 8.3.1 | Change return value: when process is unsuccessful, return false, not -1. |
Przykłady
Przykład #1 cubrid_col_size() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
@cubrid_execute($conn, "DROP TABLE foo");
cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
$req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);
cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$oid = cubrid_current_oid($req);
$attr = cubrid_col_get($conn, $oid, "b");
var_dump($attr);
$size = cubrid_col_size($conn, $oid, "b");
var_dump($size);
cubrid_close_request($req);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
array(3) {
[0]=>
string(1) "1"
[1]=>
string(1) "2"
[2]=>
string(1) "3"
}
int(3)
cubrid_column_names
(PECL CUBRID >= 8.3.0)
cubrid_column_names — Get the column names in result
Opis
$req_identifier
)
The cubrid_column_names() function is used to get the
column names of the query result by using req_identifier.
Parametry
-
req_identifier -
Request identifier.
Zwracane wartości
Array of string which containing column names, when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_column_names() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");
$column_names = cubrid_column_names($result);
$column_types = cubrid_column_types($result);
printf("%-30s %-30s %-15s\n", "Column Names", "Column Types", "Column Maxlen");
for($i = 0, $size = count($column_names); $i < $size; $i++) {
$column_len = cubrid_field_len($result, $i);
printf("%-30s %-30s %-15s\n", $column_names[$i], $column_types[$i], $column_len);
}
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
Column Names Column Types Column Maxlen host_year integer 11 event_code integer 11 athlete_code integer 11 stadium_code integer 11 nation_code char(3) 3 medal char(1) 1 game_date date 10
Zobacz też:
- cubrid_prepare() - Prepare an SQL statement for execution
- cubrid_execute() - Execute a prepared SQL statement
- cubrid_column_types() - Get column types in result
cubrid_column_types
(PECL CUBRID >= 8.3.0)
cubrid_column_types — Get column types in result
Opis
$req_identifier
)
The cubrid_column_types() function gets column types of
query results by using req_identifier.
Parametry
-
req_identifier -
Request identifier.
Zwracane wartości
Array of string which containing column types, when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_column_types() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");
$column_names = cubrid_column_names($result);
$column_types = cubrid_column_types($result);
printf("%-30s %-30s %-15s\n", "Column Names", "Column Types", "Column Maxlen");
for($i = 0, $size = count($column_names); $i < $size; $i++) {
$column_len = cubrid_field_len($result, $i);
printf("%-30s %-30s %-15s\n", $column_names[$i], $column_types[$i], $column_len);
}
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
Column Names Column Types Column Maxlen host_year integer 11 event_code integer 11 athlete_code integer 11 stadium_code integer 11 nation_code char(3) 3 medal char(1) 1 game_date date 10
Zobacz też:
- cubrid_column_names() - Get the column names in result
- cubrid_prepare() - Prepare an SQL statement for execution
- cubrid_execute() - Execute a prepared SQL statement
cubrid_commit
(PECL CUBRID >= 8.3.0)
cubrid_commit — Commit a transaction
Opis
$conn_identifier )
The cubrid_commit() function is used to execute commit
on the transaction pointed by conn_identifier,
currently on progress. Connection to the server is closed after the
cubrid_commit() function is called; the connection
handle is still valid, however.
In CUBRID PHP, an auto-commit mode is disabled by default for transaction management, and you can set it by using cubrid_set_autocommit(), and get its status by using cubrid_get_autocommit(). Before you start a transaction, remember to disable the auto-commit mode.
Parametry
-
conn_identifier -
Connection identifier.
Zwracane wartości
TRUE, when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_commit() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
@cubrid_execute($conn, "DROP TABLE publishers");
$sql = <<<EOD
CREATE TABLE publishers(
pub_id CHAR(3),
pub_name VARCHAR(20),
city VARCHAR(15),
state CHAR(2),
country VARCHAR(15)
)
EOD;
if (!cubrid_execute($conn, $sql)) {
printf("Error facility: %d\nError code: %d\nError msg: %s\n", cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());
cubrid_disconnect($conn);
exit;
}
$req = cubrid_prepare($conn, "INSERT INTO publishers VALUES(?, ?, ?, ?, ?)");
$id_list = array("P01", "P02", "P03", "P04");
$name_list = array("Abatis Publishers", "Core Dump Books", "Schadenfreude Press", "Tenterhooks Press");
$city_list = array("New York", "San Francisco", "Hamburg", "Berkeley");
$state_list = array("NY", "CA", NULL, "CA");
$country_list = array("USA", "USA", "Germany", "USA");
for ($i = 0, $size = count($id_list); $i < $size; $i++) {
cubrid_bind($req, 1, $id_list[$i]);
cubrid_bind($req, 2, $name_list[$i]);
cubrid_bind($req, 3, $city_list[$i]);
cubrid_bind($req, 4, $state_list[$i]);
cubrid_bind($req, 5, $country_list[$i]);
if (!($ret = cubrid_execute($req))) {
break;
}
}
if (!$ret) {
cubrid_rollback($conn);
} else {
cubrid_commit($conn);
$req = cubrid_execute($conn, "SELECT * FROM publishers");
while ($result = cubrid_fetch_assoc($req)) {
printf("%-3s %-20s %-15s %-3s %-15s\n",
$result["pub_id"], $result["pub_name"], $result["city"], $result["state"], $result["country"]);
}
}
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
P01 Abatis Publishers New York NY USA P02 Core Dump Books San Francisco CA USA P03 Schadenfreude Press Hamburg Germany P04 Tenterhooks Press Berkeley CA USA
Zobacz też:
- cubrid_rollback() - Roll back a transaction
- cubrid_get_autocommit() - Get auto-commit mode of the connection
- cubrid_set_autocommit() - Set autocommit mode of the connection
cubrid_connect_with_url
(PECL CUBRID >= 8.3.1)
cubrid_connect_with_url — Establish the environment for connecting to CUBRID server
Opis
$conn_url
[, string $userid
[, string $passwd
[, bool $new_link = false
]]] )The cubrid_connect_with_url() function is used to establish the environment for connecting to your server by using connection information passed with an url string argument. If the HA feature is enabled in CUBRID, you must specify the connection information of the standby server, which is used for failover when failure occurs, in the url string argument of this function. If the user name and password is not given, then the "PUBLIC" connection will be made by default.
<url> ::= CUBRID:<host>:<db_name>:<db_user>:<db_password>:[?<properties>] <properties> ::= <property> [&<property>] <properties> ::= autocommit=<autocommit_mode> <alternative_hosts> ::= <standby_broker1_host>:<port> [,<standby_broker2_host>:<port>] <host> := HOSTNAME | IP_ADDR <time> := SECOND
or <url> ::= cci:CUBRID:<host>:<db_name>:......
- host : A host name or IP address of the master database
- db_name : A name of the database
- db_user : A name of the database user
- db_password : A database user password
- autocommit : The database connection auto-commit mode
- alhosts: Specifies the broker information of the standby server, which is used for failover when it is impossible to connect to the active server. You can specify multiple brokers for failover, and the connection to the brokers is attempted in the order listed in alhosts
- rctime : An interval between the attempts to connect to the active broker in which failure occurred. After a failure occurs, the system connects to the broker specified by althosts (failover), terminates the transaction, and then attempts to connect to the active broker of the master database at every rctime. The default value is 600 seconds.
Informacja:
? and : that are used as identifiers in PHP connection URL can't be included in the password. The following is an example of a password that is invalid to use as connection URL because it contains "?:".
$url = "CUBRID:localhost:33000:tdb:dba:12?:?autocommit=off";
Passwords that contain ? or : may be passed as a seperate parameter.
$url = "CUBRID:localhost:33000:tbd:::?autocommit=off"; $conn = cubrid_connect_with_url ($url, "dba", "12?");
Parametry
-
conn_url -
A character string that contains server connection information.
-
userid -
User name for the database.
-
passwd -
User password.
-
new_link -
If a second call is made to cubrid_connect_with_url() with the same arguments, no new connection will be established, but instead, the connection identifier of the already opened connection will be returned. The
new_linkparameter modifies this behavior and makes cubrid_connect_with_url() always open a new connection, even if cubrid_connect_with_url() was called before with the same parameters.
Zwracane wartości
Connection identifier, when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_connect_with_url() url without properties example
<?php
$conn_url = "CUBRID:127.0.0.1:33088:demodb:dba:123456:?autocommit=off"
$con = cubrid_connect_with_url ($conn_url);
if ($con) {
echo "connected successfully";
$req =cubrid_execute($con, "insert into person values(1,'James')");
if ($req) {
cubrid_close_request ($req);
cubrid_commit ($con);
} else {
cubrid_rollback ($con);
}
cubrid_disconnect ($con);
}
?>
Przykład #2 cubrid_connect_with_url() url with properties example
<?php
$conn_url = "CUBRID:127.0.0.1:33088:demodb:dba:123456:?autocommit=off&althost=10.34.63.132:33088&rctime=100"
$con = cubrid_connect_with_url ($conn_url);
if ($con) {
echo "connected successfully";
$req =cubrid_execute($con, "insert into person values(1,'James')");
if ($req) {
cubrid_close_request ($req);
cubrid_commit ($con);
} else {
cubrid_rollback ($con);
}
cubrid_disconnect ($con);
}
?>
Zobacz też:
- cubrid_connect() - Open a connection to a CUBRID Server
- cubrid_pconnect() - Open a persistent connection to a CUBRID server
- cubrid_pconnect_with_url() - Open a persistent connection to CUBRID server
- cubrid_disconnect() - Close a database connection
- cubrid_close() - Close CUBRID connection
cubrid_connect
(PECL CUBRID >= 8.3.1)
cubrid_connect — Open a connection to a CUBRID Server
Opis
$host
, int $port
, string $dbname
[, string $userid
[, string $passwd
[, bool $new_link = false
]]] )The cubrid_connect() function is used to establish the environment for connecting to your server by using your server address, port number, database name, user name, and password. If the user name and password is not given, then the "PUBLIC" connection will be made by default.
Parametry
-
host -
Host name or IP address of CUBRID CAS server.
-
port -
Port number of CUBRID CAS server (BROKER_PORT configured in $CUBRID/conf/cubrid_broker.conf).
-
dbname -
Name of database.
-
userid -
User name for the database. If not given, the default value is "public".
-
passwd -
User password. If not given, the default value is "".
-
new_link -
If a second call is made to cubrid_connect() with the same arguments, no new connection will be established, but instead, the connection identifier of the already opened connection will be returned. The
new_linkparameter modifies this behavior and makes cubrid_connect() always open a new connection, even if cubrid_connect() was called before with the same parameters.
Zwracane wartości
Connection identifier, when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_connect() example
<?php
printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());
printf("\n");
$conn = cubrid_connect("localhost", 33000, "demodb");
if (!$conn) {
die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
}
$db_params = cubrid_get_db_parameter($conn);
while (list($param_name, $param_value) = each($db_params)) {
printf("%-30s %s\n", $param_name, $param_value);
}
printf("\n");
$server_info = cubrid_get_server_info($conn);
$client_info = cubrid_get_client_info();
printf("%-30s %s\n", "Server Info:", $server_info);
printf("%-30s %s\n", "Client Info:", $client_info);
printf("\n");
$charset = cubrid_get_charset($conn);
printf("%-30s %s\n", "CUBRID Charset:", $charset);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
CUBRID PHP Version: 8.3.1.0005 PARAM_ISOLATION_LEVEL 3 LOCK_TIMEOUT -1 MAX_STRING_LENGTH 1073741823 PARAM_AUTO_COMMIT 0 Server Info: 8.3.1.0173 Client Info: 8.3.1 CUBRID Charset: iso8859-1
Zobacz też:
- cubrid_pconnect() - Open a persistent connection to a CUBRID server
- cubrid_connect_with_url() - Establish the environment for connecting to CUBRID server
- cubrid_pconnect_with_url() - Open a persistent connection to CUBRID server
- cubrid_disconnect() - Close a database connection
- cubrid_close() - Close CUBRID connection
cubrid_current_oid
(PECL CUBRID >= 8.3.0)
cubrid_current_oid — Get OID of the current cursor location
Opis
$req_identifier
)The cubrid_current_oid() function is used to get the oid of the current cursor location from the query result. To use cubrid_current_oid(), the query executed must be a updatable query, and the CUBRID_INCLUDE_OID option must be included during the query execution.
Parametry
-
req_identifier -
Request identifier.
Zwracane wartości
Oid of current cursor location, when process is successful
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_current_oid() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = cubrid_execute($conn, "SELECT * FROM code", CUBRID_INCLUDE_OID);
$oid = cubrid_current_oid($req);
$res = cubrid_get($conn, $oid);
print_r($res);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
Array
(
[s_name] => X
[f_name] => Mixed
)
cubrid_disconnect
(PECL CUBRID >= 8.3.0)
cubrid_disconnect — Close a database connection
Opis
$conn_identifier
)The cubrid_disconnect() function closes the connection handle and disconnects from server. If there exists any request handle not closed yet at this point, it will be closed. It is similar to the CUBRID MySQL compatible function cubrid_close().
Parametry
-
conn_identifier -
Connection identifier.
Zwracane wartości
TRUE, when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_disconnect() example
<?php
$con = cubrid_connect ("210.211.133.100", 12345, "demodb");
if ($con) {
echo "connected successfully";
$req = cubrid_execute( $con, "insert into person values(1,'James')");
if ($req) {
cubrid_close_request($req);
cubrid_commit($con);
} else {
cubrid_rollback($con);
}
cubrid_disconnect($con);
}
?>
Zobacz też:
- cubrid_close() - Close CUBRID connection
- cubrid_connect() - Open a connection to a CUBRID Server
- cubrid_connect_with_url() - Establish the environment for connecting to CUBRID server
cubrid_drop
(PECL CUBRID >= 8.3.0)
cubrid_drop — Delete an instance using OID
Opis
$conn_identifier
, string $oid
)
The cubrid_drop() function is used to delete an
instance from database by using oid.
Parametry
-
conn_identifier -
Connection identifier.
-
oid -
Oid of the instance that you want to delete.
Zwracane wartości
TRUE, when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_drop() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
@cubrid_execute($conn, "DROP TABLE foo");
cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");
$req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);
cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$oid = cubrid_current_oid($req);
printf("--- Before Drop: ---\n");
$attr = cubrid_get($conn, $oid);
var_dump($attr);
if (cubrid_drop($conn, $oid)) {
cubrid_commit($conn);
} else {
cubrid_rollback($conn);
}
cubrid_close_request($req);
$req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);
cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$oid = cubrid_current_oid($req);
printf("\n--- After Drop: ---\n");
$attr = cubrid_get($conn, $oid);
var_dump($attr);
cubrid_close_request($req);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
--- Before Drop: ---
array(4) {
["a"]=>
string(1) "1"
["b"]=>
array(3) {
[0]=>
string(1) "1"
[1]=>
string(1) "2"
[2]=>
string(1) "3"
}
["c"]=>
array(4) {
[0]=>
string(2) "11"
[1]=>
string(2) "22"
[2]=>
string(2) "33"
[3]=>
string(3) "333"
}
["d"]=>
string(10) "a "
}
--- After Drop: ---
array(4) {
["a"]=>
string(1) "2"
["b"]=>
array(3) {
[0]=>
string(1) "4"
[1]=>
string(1) "5"
[2]=>
string(1) "7"
}
["c"]=>
array(4) {
[0]=>
string(2) "44"
[1]=>
string(2) "55"
[2]=>
string(2) "66"
[3]=>
string(3) "666"
}
["d"]=>
string(10) "b "
}
cubrid_error_code_facility
(PECL CUBRID >= 8.3.0)
cubrid_error_code_facility — Get the facility code of error
Opis
The cubrid_error_code_facility() function is used to get the facility code (level in which the error occurred) from the error code of the error that occurred during the API execution. Usually, you can get the error code when API returns false as its return value.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Facility code of the error code that occurred: CUBRID_FACILITY_DBMS, CUBRID_FACILITY_CAS, CUBRID_FACILITY_CCI, CUBRID_FACILITY_CLIENT
Przykłady
Przykład #1 cubrid_error_code_facility() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = @cubrid_execute($conn, "SELECT * FROM unknown");
if (!$req) {
printf("Error facility: %d\nError code: %d\nError msg: %s\n",
cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());
cubrid_disconnect($conn);
exit;
}
?>
Powyższy przykład wyświetli:
Error facility: 1 Error code: -493 Error msg: Syntax: syntax error, unexpected UNKNOWN
Zobacz też:
- cubrid_error_code() - Get error code for the most recent function call
- cubrid_error_msg() - Get last error message for the most recent function call
cubrid_error_code
(PECL CUBRID >= 8.3.0)
cubrid_error_code — Get error code for the most recent function call
Opis
The cubrid_error_code() function is used to get the error code of the error that occurred during the API execution. Usually, it gets the error code when API returns false as its return value.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Error code of the error that occurred, or 0 (zero) if no error occurred.
Przykłady
Przykład #1 cubrid_error_code() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = cubrid_prepare($conn , "SELECT * FROM code WHERE s_name=?");
$req = @cubrid_execute($req);
if (!$req) {
printf("Error facility: %d\nError code: %d\nError msg: %s\n",
cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());
cubrid_disconnect($conn);
exit;
}
?>
Powyższy przykład wyświetli:
Error facility: 4 Error code: -2015 Error msg: Some parameter not binded
Zobacz też:
- cubrid_error_code_facility() - Get the facility code of error
- cubrid_error_msg() - Get last error message for the most recent function call
cubrid_error_msg
(PECL CUBRID >= 8.3.0)
cubrid_error_msg — Get last error message for the most recent function call
Opis
The cubrid_error_msg() function is used to get the error message that occurred during the use of CUBRID API. Usually, it gets error message when API returns false as its return value.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Error message that occurred.
Przykłady
Przykład #1 cubrid_error_msg() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
if (!@cubrid_schema($conn, 100000)) {
printf("Error facility: %d\nError code: %d\nError msg: %s\n",
cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());
cubrid_disconnect($conn);
exit;
}
?>
Powyższy przykład wyświetli:
Error facility: 2 Error code: -1015 Error msg: Invalid T_CCI_SCH_TYPE value
Zobacz też:
- cubrid_error_code() - Get error code for the most recent function call
- cubrid_error_code_facility() - Get the facility code of error
cubrid_execute
(PECL CUBRID >= 8.3.0)
cubrid_execute — Execute a prepared SQL statement
Opis
$conn_identifier
, string $sql
[, int $option
] )$request_identifier
[, int $option
] )
The cubrid_execute() function is used to execute the
given SQL statement. It executes the query by using
conn_identifier and SQL, and then returns the
request identifier created. It is used for simple execution of query,
where the parameter binding is not needed. In addition, the
cubrid_execute() function is used to execute the
prepared statement by means of cubrid_prepare() and
cubrid_bind(). At this time, you need to specify
arguments of request_identifier and
option.
The option is used to determine whether to get OID
after query execution and whether to execute the query in synchronous or
asynchronous mode. CUBRID_INCLUDE_OID and CUBRID_ASYNC (or
CUBRID_EXEC_QUERY_ALL if you want to execute multiple SQL statements) can
be specified by using a bitwise OR operator. If not specified, neither of
them isselected. If the flag CUBRID_EXEC_QUERY_ALL is set, a synchronous
mode (sync_mode) is used to retrieve query results, and in such cases the
following rules are applied:
- The return value is the result of the first query.
- If an error occurs in any query, the execution is processed as a failure.
- For a query composed of in a query composed of q1 q2 q3 if an error occurs in q2 after q1 succeeds the execution, the result of q1 remains valid. That is, the previous successful query executions are not rolled back when an error occurs.
- If a query is executed successfully, the result of the second query can be obtained using cubrid_next_result().
If the first argument is request_identifier to
execute the cubrid_prepare() function, you can specify
an option, CUBRID_ASYNC only.
Parametry
-
conn_identifier -
Connection identifier.
-
sql -
SQL to be executed.
-
option -
Query execution option CUBRID_INCLUDE_OID, CUBRID_ASYNC, CUBRID_EXEC_QUERY_ALL.
-
request_identifier -
cubrid_prepare() identifier.
Zwracane wartości
Request identifier, when process is successful and first param is
conn_identifier; TRUE, when process is successful and first argument is
request_identifier.
FALSE, when process is unsuccessful.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 8.4.0 | Add new option CUBRID_EXEC_QUERY_ALL. |
Przykłady
Przykład #1 cubrid_execute() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$result = cubrid_execute($conn, "SELECT code FROM event WHERE name='100m Butterfly' and gender='M'", CUBRID_ASYNC);
$row = cubrid_fetch_array($result, CUBRID_ASSOC);
$event_code = $row["code"];
cubrid_close_request($result);
$history_req = cubrid_prepare($conn, "SELECT * FROM history WHERE event_code=?");
cubrid_bind($history_req, 1, $event_code, "number");
cubrid_execute($history_req);
printf("%-20s %-9s %-10s %-5s\n", "athlete", "host_year", "score", "unit");
while ($row = cubrid_fetch_array($history_req, CUBRID_ASSOC)) {
printf("%-20s %-9s %-10s %-5s\n",
$row["athlete"], $row["host_year"], $row["score"], $row["unit"]);
}
cubrid_close_request($history_req);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
athlete host_year score unit Phelps Michael 2004 51.25 time
Zobacz też:
- cubrid_prepare() - Prepare an SQL statement for execution
- cubrid_bind() - Bind variables to a prepared statement as parameters
- cubrid_next_result() - Get result of next query when executing multiple SQL statements
- cubrid_close_request() - Close the request handle
- cubrid_commit() - Commit a transaction
- cubrid_rollback() - Roll back a transaction
cubrid_fetch
(PECL CUBRID >= 8.3.0)
cubrid_fetch — Fetch the next row from a result set
Opis
The cubrid_fetch() function is used to get a single row from the query result. The cursor automatically moves to the next row after getting the result.
Parametry
-
result -
resultcomes from a call to cubrid_execute() -
type -
Array type of the fetched result CUBRID_NUM, CUBRID_ASSOC, CUBRID_BOTH, CUBRID_OBJECT.
Zwracane wartości
Result array or object, when process is successful.
FALSE, when there are no more rows; NULL, when process is unsuccessful.
The result can be received either as an array or as an object, and you can decide which data type to use by setting the type argument. The type variable can be set to one of the following values:
- CUBRID_NUM : Numerical array (0-based)
- CUBRID_ASSOC : Associative array
- CUBRID_BOTH : Numerical & Associative array (default)
- CUBRID_OBJECT : object that has the attribute name as the column name of query result
When type argument is omitted, the result will be received using CUBRID_BOTH option as default. When you want to receive query result in object data type, the column name of the result must obey the naming rules for identifiers in PHP. For example, column name such as "count(*)" cannot be received in object type.
Przykłady
Przykład #1 cubrid_fetch() example
<?php
$conn = cubrid_connect("localhost", 33088, "demodb");
$req = cubrid_execute($conn, "SELECT * FROM stadium WHERE nation_code='GRE' AND seats > 10000");
printf("%-40s %-10s %-6s %-20s\n", "name", "area", "seats", "address");
while ($row = cubrid_fetch($req)) {
printf("%-40s %-10s %-6s %-20s\n",
$row["name"], $row["area"], $row["seats"], $row["address"]);
}
cubrid_close_request($req);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
name area seats address Panathinaiko Stadium 86300.00 50000 Athens, Greece Olympic Stadium 54700.00 13000 Athens, Greece Olympic Indoor Hall 34100.00 18800 Athens, Greece Olympic Hall 52400.00 21000 Athens, Greece Olympic Aquatic Centre 42500.00 11500 Athens, Greece Markopoulo Olympic Equestrian Centre 64000.00 15000 Markopoulo, Athens, Greece Faliro Coastal Zone Olympic Complex 34650.00 12171 Faliro, Athens, Greece Athens Olympic Stadium 120400.00 71030 Maroussi, Athens, Greece Ano Liossia 34000.00 12000 Ano Liosia, Athens, Greece
cubrid_free_result
(PECL CUBRID >= 8.3.0)
cubrid_free_result — Free the memory occupied by the result data
Opis
$req_identifier
)This function frees the memory occupied by the result data. It returns TRUE on success or FALSE on failure. Note that it can only frees the client fetch buffer now, and if you want free all memory, use function cubrid_close_request().
Parametry
-
req_identifier -
This is the request identifier.
Zwracane wartości
TRUE on success.
FALSE on failure.
Przykłady
Przykład #1 cubrid_free_result() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = cubrid_execute($conn, "SELECT * FROM history WHERE host_year=2004 ORDER BY event_code");
$row = cubrid_fetch_assoc($req);
var_dump($row);
cubrid_free_result($req);
cubrid_close_request($req);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
array(5) {
["event_code"]=>
string(5) "20005"
["athlete"]=>
string(12) "Hayes Joanna"
["host_year"]=>
string(4) "2004"
["score"]=>
string(5) "12.37"
["unit"]=>
string(4) "time"
}
cubrid_get_autocommit
(PECL CUBRID >= 8.4.0)
cubrid_get_autocommit — Get auto-commit mode of the connection
Opis
$conn_identifier
)The cubrid_get_autocommit() function is used to get the status of CUBRID database connection auto-commit mode.
For CUBRID 8.4.0, auto-commit mode is disabled by default for transaction management.
For CUBRID 8.4.1, auto-commit mode is enabled by default for transaction management.
Parametry
-
conn_identifier -
Connection identifier.
Zwracane wartości
TRUE, when auto-commit is on.
FALSE, when auto-commit is off.
NULL on error.
Zobacz też:
- cubrid_set_autocommit() - Set autocommit mode of the connection
- cubrid_commit() - Commit a transaction
cubrid_get_charset
(PECL CUBRID >= 8.3.0)
cubrid_get_charset — Return the current CUBRID connection charset
Opis
$conn_identifier
)This function returns the current CUBRID connection charset and is similar to the CUBRID MySQL compatible function cubrid_client_encoding().
Parametry
-
conn_identifier -
The CUBRID connection.
Zwracane wartości
A string that represents the CUBRID connection charset; on success.
FALSE on failure.
Przykłady
Przykład #1 cubrid_get_charset() example
<?php
$con = cubrid_connect("localhost", 33000, "demodb");
if (!$con)
{
die('Could not connect.');
}
printf("CUBRID current charset: %s\n", cubrid_client_encoding($con));
?>
Powyższy przykład wyświetli:
CUBRID current charset: iso8859-1
cubrid_get_class_name
(PECL CUBRID >= 8.3.0)
cubrid_get_class_name — Get the class name using OID
Opis
$conn_identifier
, string $oid
)
The cubrid_get_class_name() function is used to get the
class name from oid.
Parametry
-
conn_identifier -
Connection identifier.
-
oid -
OID of the instance that you want to check the existence.
Zwracane wartości
Class name when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_get_class_name() example
<?php
$conn = cubrid_connect("localhost", 33088, "demodb");
$req = cubrid_execute($conn, "SELECT * FROM code", CUBRID_INCLUDE_OID);
$oid = cubrid_current_oid($req);
$class_name = cubrid_get_class_name($conn, $oid);
print_r($class_name);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
code
Zobacz też:
- cubrid_is_instance() - Check whether the instance pointed by OID exists
- cubrid_drop() - Delete an instance using OID
cubrid_get_client_info
(PECL CUBRID >= 8.3.0)
cubrid_get_client_info — Return the client library version
Opis
This function returns a string that represents the client library version.
Parametry
Zwracane wartości
A string that represents the client library version; on success.
FALSE on failure.
Przykłady
Przykład #1 cubrid_get_client_info() example
<?php
printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());
printf("\n");
$conn = cubrid_connect("localhost", 33088, "demodb");
if (!$conn) {
die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
}
$db_params = cubrid_get_db_parameter($conn);
while (list($param_name, $param_value) = each($db_params)) {
printf("%-30s %s\n", $param_name, $param_value);
}
printf("\n");
$server_info = cubrid_get_server_info($conn);
$client_info = cubrid_get_client_info();
printf("%-30s %s\n", "Server Info:", $server_info);
printf("%-30s %s\n", "Client Info:", $client_info);
printf("\n");
$charset = cubrid_get_charset($conn);
printf("%-30s %s\n", "CUBRID Charset:", $charset);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
CUBRID PHP Version: 8.3.1.0005 PARAM_ISOLATION_LEVEL 3 LOCK_TIMEOUT -1 MAX_STRING_LENGTH 1073741823 PARAM_AUTO_COMMIT 0 Server Info: 8.3.1.0173 Client Info: 8.3.1 CUBRID Charset: iso8859-1
cubrid_get_db_parameter
(PECL CUBRID >= 8.3.0)
cubrid_get_db_parameter — Returns the CUBRID database parameters
Opis
$conn_identifier
)This function returns the CUBRID database parameters or it returns FALSE on failure. It returns an associative array with the values for the following parameters:
PARAM_ISOLATION_LEVELPARAM_LOCK_TIMEOUTPARAM_MAX_STRING_LENGTHPARAM_AUTO_COMMIT
| Parameter | Description |
|---|---|
| PARAM_ISOLATION_LEVEL | The transaction isolation level. |
| LOCK_TIMEOUT | CUBRID provides the lock timeout feature, which sets the waiting time (in seconds) for the lock until the transaction lock setting is allowed. The default value of the lock_timeout_in_secs parameter is -1, which means the application client will wait indefinitely until the transaction lock is allowed. |
| PARAM_AUTO_COMMIT | In CUBRID PHP, an auto-commit mode is disabled by default for transaction management. It can be set by using cubrid_set_autocommit(). |
The following table shows the isolation levels from 1 to 6. It consists of table schema (row) and isolation level:
| Name | Description |
|---|---|
| SERIALIZABLE (6) | In this isolation level, problems concerning concurrency (e.g. dirty read, non-repeatable read, phantom read, etc.) do not occur. |
| REPEATABLE READ CLASS with REPEATABLE READ INSTANCES (5) | Another transaction T2 cannot update the schema of table A while transaction T1 is viewing table A. Transaction T1 may experience phantom read for the record R that was inserted by another transaction T2 when it is repeatedly retrieving a specific record. |
| REPEATABLE READ CLASS with READ COMMITTED INSTANCES (or CURSOR STABILITY) (4) | Another transaction T2 cannot update the schema of table A while transaction T1 is viewing table A. Transaction T1 may experience R read (non-repeatable read) that was updated and committed by another transaction T2 when it is repeatedly retrieving the record R. |
| REPEATABLE READ CLASS with READ UNCOMMITTED INSTANCES (3) | Default isolation level. Another transaction T2 cannot update the schema of table A while transaction T1 is viewing table A. Transaction T1 may experience R' read (dirty read) for the record that was updated but not committed by another transaction T2. |
| READ COMMITTED CLASS with READ COMMITTED INSTANCES (2) | Transaction T1 may experience A' read (non-repeatable read) for the table that was updated and committed by another transaction T2 while it is viewing table A repeatedly. Transaction T1 may experience R' read (non-repeatable read) for the record that was updated and committed by another transaction T2 while it is retrieving the record R repeatedly. |
| READ COMMITTED CLASS with READ UNCOMMITTED INSTANCES (1) | Transaction T1 may experience A' read (non-repeatable read) for the table that was updated and committed by another transaction T2 while it is repeatedly viewing table A. Transaction T1 may experience R' read (dirty read) for the record that was updated but not committed by another transaction T2. |
Parametry
-
conn_identifier -
The CUBRID connection. If the connection identifier is not specified, the last link opened by cubrid_connect() is assumed.
Zwracane wartości
An associative array with CUBRID database parameters; on success.
FALSE on failure.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 8.4.0 | Change LOCK_TIMEOUT to PARAM_LOCK_TIMEOUT, and MAX_STRING_LENGTH to PARAM_MAX_STRING_LENGTH in result. |
Przykłady
Przykład #1 cubrid_get_db_parameter() example
<?php
printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());
printf("\n");
$conn = cubrid_connect("localhost", 33088, "demodb");
if (!$conn) {
die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
}
$db_params = cubrid_get_db_parameter($conn);
while (list($param_name, $param_value) = each($db_params)) {
printf("%-30s %s\n", $param_name, $param_value);
}
printf("\n");
$server_info = cubrid_get_server_info($conn);
$client_info = cubrid_get_client_info();
printf("%-30s %s\n", "Server Info:", $server_info);
printf("%-30s %s\n", "Client Info:", $client_info);
printf("\n");
$charset = cubrid_get_charset($conn);
printf("%-30s %s\n", "CUBRID Charset:", $charset);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
CUBRID PHP Version: 8.3.1.0005 PARAM_ISOLATION_LEVEL 3 PARAM_LOCK_TIMEOUT -1 PARAM_MAX_STRING_LENGTH 1073741823 PARAM_AUTO_COMMIT 0 Server Info: 8.3.1.0173 Client Info: 8.3.1 CUBRID Charset: iso8859-1
Zobacz też:
- cubrid_set_db_parameter() - Sets the CUBRID database parameters
- cubrid_get_autocommit() - Get auto-commit mode of the connection
cubrid_get_query_timeout
(PECL CUBRID >= 8.4.1)
cubrid_get_query_timeout — Get the query timeout value of the request
Opis
$req_identifier
)The cubrid_get_query_timeout() function is used to get the query timeout of the request.
Parametry
-
req_identifier -
Request identifier.
Zwracane wartości
Success: the query timeout value of the current request. Units of msec.
Failure: FALSE
Przykłady
Przykład #1 cubrid_get_query_timeout() example
<?php
$host = "localhost";
$port = 33000;
$db = "demodb";
$conn =
cubrid_connect_with_url("CUBRID:$host:$port:$db:::?&login_timeout=50000&query_timeout=5000&disconnect_on_query_timeout=yes");
$req = cubrid_prepare($conn, "SELECT * FROM code");
$timeout = cubrid_get_query_timeout($req);
var_dump($timeout);
cubrid_set_query_timeout($req, 1000);
$timeout = cubrid_get_query_timeout($req);
var_dump($timeout);
cubrid_close($conn);
?>
Powyższy przykład wyświetli:
int(5000) int(1000)
cubrid_get_server_info
(PECL CUBRID >= 8.3.0)
cubrid_get_server_info — Return the CUBRID server version
Opis
$conn_identifier
)This function returns a string that represents the CUBRID server version.
Parametry
-
conn_identifier -
The CUBRID connection.
Zwracane wartości
A string that represents the CUBRID server version; on success.
FALSE on failure.
Przykłady
Przykład #1 cubrid_get_server_info() example
<?php
printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());
printf("\n");
$conn = cubrid_connect("localhost", 33088, "demodb");
if (!$conn) {
die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
}
$db_params = cubrid_get_db_parameter($conn);
while (list($param_name, $param_value) = each($db_params)) {
printf("%-30s %s\n", $param_name, $param_value);
}
printf("\n");
$server_info = cubrid_get_server_info($conn);
$client_info = cubrid_get_client_info();
printf("%-30s %s\n", "Server Info:", $server_info);
printf("%-30s %s\n", "Client Info:", $client_info);
printf("\n");
$charset = cubrid_get_charset($conn);
printf("%-30s %s\n", "CUBRID Charset:", $charset);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
CUBRID PHP Version: 8.3.1.0005 PARAM_ISOLATION_LEVEL 3 LOCK_TIMEOUT -1 MAX_STRING_LENGTH 1073741823 PARAM_AUTO_COMMIT 0 Server Info: 8.3.1.0173 Client Info: 8.3.1 CUBRID Charset: iso8859-1
cubrid_get
(PECL CUBRID >= 8.3.0)
cubrid_get — Get a column using OID
Opis
The cubrid_get() function is used to get the attribute
of the instance of the given oid. You can get
single attribute by using string data type for the
attr argument, or many attributes by using array
data type for the attr argument.
Parametry
-
conn_identifier -
Connection identifier.
-
oid -
OID of the instance that you want to read.
-
attr -
Name of the attribute that you want to read.
Zwracane wartości
Content of the requested attribute, when process is successful; When
attr is set with string data type, the result is
returned as a string; when attr is set with array
data type (0-based numerical array), then the result is returned in
associative array. When attr is omitted, then all
attributes are received in array form.
FALSE when process is unsuccessful or result is NULL (If error occurs to
distinguish empty string from NULL, then it prints the warning message.
You can check the error by using cubrid_error_code())
Przykłady
Przykład #1 cubrid_get() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
@cubrid_execute($conn, "DROP TABLE foo");
cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");
$req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);
cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$oid = cubrid_current_oid($req);
$attr = cubrid_get($conn, $oid, "b");
var_dump($attr);
$attr = cubrid_get($conn, $oid);
var_dump($attr);
cubrid_close_request($req);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
string(9) "{1, 2, 3}"
array(4) {
["a"]=>
string(1) "1"
["b"]=>
array(3) {
[0]=>
string(1) "1"
[1]=>
string(1) "2"
[2]=>
string(1) "3"
}
["c"]=>
array(4) {
[0]=>
string(2) "11"
[1]=>
string(2) "22"
[2]=>
string(2) "33"
[3]=>
string(3) "333"
}
["d"]=>
string(10) "a "
}
cubrid_insert_id
(PECL CUBRID >= 8.3.0)
cubrid_insert_id — Return the ID generated for the lastest updated AUTO_INCREMENT column
Opis
$conn_identifier
] )The cubrid_insert_id() function retrieves the ID generated for the AUTO_INCREMENT column which is updated by the previous INSERT query. It returns 0 if the previous query does not generate new rows, or FALSE on failure.
Informacja:
CUBRID supports AUTO_INCREMENT for more than one columns in a table. In most cases, there will be a single AUTO_INCREMENT column in a table. If there are multiple AUTO_INCREMENT columns, this function should not be used even if it will return a value.
Parametry
-
conn_identifier -
The connection identifier previously obtained by a call to cubrid_connect().
Zwracane wartości
A string representing the ID generated for an AUTO_INCREMENT column by the previous query, on success.
0, if the previous query does not generate new rows.
FALSE on failure.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 8.4.0 | Change the return value from an array to string; Remove the first parameter class_name. |
Przykłady
Przykład #1 cubrid_insert_id() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
@cubrid_execute($conn, "DROP TABLE cubrid_test");
cubrid_execute($conn, "CREATE TABLE cubrid_test (d int AUTO_INCREMENT(1, 2), t varchar)");
for ($i = 0; $i < 10; $i++) {
cubrid_execute($conn, "INSERT INTO cubrid_test(t) VALUES('cubrid_test')");
}
$id = cubrid_insert_id();
var_dump($id);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
string(2) "19"
cubrid_is_instance
(PECL CUBRID >= 8.3.0)
cubrid_is_instance — Check whether the instance pointed by OID exists
Opis
$conn_identifier
, string $oid
)
The cubrid_is_instance() function is used to check
whether the instance pointed by the given oid
exists or not.
Parametry
-
conn_identifier -
Connection identifier.
-
oid -
OID of the instance that you want to check the existence.
Zwracane wartości
1, if such instance exists;
0, if such instance does not exist;
-1, in case of error
Przykłady
Przykład #1 cubrid_is_instance() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$sql = <<<EOD
SELECT host_year, medal, game_date
FROM game
WHERE athlete_code IN
(SELECT code FROM athlete WHERE name='Thorpe Ian');
EOD;
$req = cubrid_execute($conn, $sql, CUBRID_INCLUDE_OID);
$oid = cubrid_current_oid($req);
$res = cubrid_is_instance ($conn, $oid);
if ($res == 1) {
echo "Instance pointed by $oid exists.\n";
} else if ($res == 0){
echo "Instance pointed by $oid doesn't exist.\n";
} else {
echo "error\n";
}
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
Instance pointed by @0|0|0 doesn't exist.
Zobacz też:
- cubrid_drop() - Delete an instance using OID
- cubrid_get_class_name() - Get the class name using OID
cubrid_lob_close
(PECL CUBRID >= 8.3.1)
cubrid_lob_close — Close BLOB/CLOB data
Opis
$lob_identifier_array
)cubrid_lob_close() is used to close all BLOB/CLOB returned from cubrid_lob_get().
Parametry
-
lob_identifier_array -
LOB identifier array return from cubrid_lob_get.
Zwracane wartości
TRUE, when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_lob_close() example
<?php
$lobs = cubrid_lob_get($con, "SELECT doc_content FROM doc WHERE doc_id=5");
cubrid_lob_export($conn, $lobs[0], "doc_5.txt");
cubrid_lob_close($lobs);
?>
Zobacz też:
- cubrid_lob_get() - Get BLOB/CLOB data
- cubrid_lob_size() - Get BLOB/CLOB data size
- cubrid_lob_export() - Export BLOB/CLOB data to file
- cubrid_lob_send() - Read BLOB/CLOB data and send straight to browser
cubrid_lob_export
(PECL CUBRID >= 8.3.1)
cubrid_lob_export — Export BLOB/CLOB data to file
Opis
$conn_identifier
, resource $lob_identifier
, string $path_name
)cubrid_lob_export() is used to get BLOB/CLOB data from CUBRID database, and saves its contents to a file. To use this function, you must use cubrid_lob_get() first to get BLOB/CLOB info from CUBRID.
Parametry
-
conn_identifier -
Connection identifier.
-
lob_identifier -
LOB identifier.
-
path_name -
Path name of the file.
Zwracane wartości
TRUE, when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_lob_export() example
<?php
$lobs = cubrid_lob_get($con, "SELECT doc_content FROM doc WHERE doc_id=5");
cubrid_lob_export($conn, $lobs[0], "doc_5.txt");
cubrid_lob_close($lobs);
?>
Zobacz też:
- cubrid_lob_get() - Get BLOB/CLOB data
- cubrid_lob_close() - Close BLOB/CLOB data
- cubrid_lob_size() - Get BLOB/CLOB data size
- cubrid_lob_send() - Read BLOB/CLOB data and send straight to browser
cubrid_lob_get
(PECL CUBRID >= 8.3.1)
cubrid_lob_get — Get BLOB/CLOB data
Opis
$conn_identifier
, string $sql
)cubrid_lob_get() is used to get BLOB/CLOB meta info from CUBRID database, CUBRID gets BLOB/CLOB by executing the SQL statement, and returns all LOBs as a resource array. Be sure that the SQL retrieves only one column and its data type is BLOB or CLOB.
Remember to use cubrid_lob_close() to release the LOBs if you don't need it any more.
Parametry
-
conn_identifier -
Connection identifier.
-
sql -
SQL statement to be executed.
Zwracane wartości
Return an array of LOB resources, when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_lob_get() example
<?php
$lobs = cubrid_lob_get($con, "SELECT doc_content FROM doc WHERE doc_id=5");
cubrid_lob_export($conn, $lobs[0], "doc_5.txt");
cubrid_lob_close($lobs);
?>
Zobacz też:
- cubrid_lob_close() - Close BLOB/CLOB data
- cubrid_lob_size() - Get BLOB/CLOB data size
- cubrid_lob_export() - Export BLOB/CLOB data to file
- cubrid_lob_send() - Read BLOB/CLOB data and send straight to browser
cubrid_lob_send
(PECL CUBRID >= 8.3.1)
cubrid_lob_send — Read BLOB/CLOB data and send straight to browser
Opis
$conn_identifier
, resource $lob_identifier
)cubrid_lob_send() reads BLOB/CLOB data and passes it straight through to the browser. To use this function, you must use cubrid_lob_get() first to get BLOB/CLOB info from CUBRID.
Parametry
-
conn_identifier -
Connection identifier.
-
lob_identifier -
LOB identifier.
Zwracane wartości
TRUE, when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_lob_send() example
<?php
$lobs = cubrid_lob_get($con, "SELECT image FROM person WHERE id=1");
Header("Content-type: image/jpeg");
cubrid_lob_send($conn, $lobs[0]);
cubrid_lob_close($lobs);
?>
Zobacz też:
- cubrid_lob_get() - Get BLOB/CLOB data
- cubrid_lob_close() - Close BLOB/CLOB data
- cubrid_lob_size() - Get BLOB/CLOB data size
- cubrid_lob_export() - Export BLOB/CLOB data to file
cubrid_lob_size
(PECL CUBRID >= 8.3.1)
cubrid_lob_size — Get BLOB/CLOB data size
Opis
$lob_identifier
)cubrid_lob_size() is used to get BLOB/CLOB data size.
Parametry
-
lob_identifier -
LOB identifier.
Zwracane wartości
A string representing LOB data size, when process is successful.
FALSE, when process is unsuccessful.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 8.4.0 | Change return value type from int to string. |
Przykłady
Przykład #1 cubrid_lob_size() example
<?php
$lobs = cubrid_lob_get($con, "SELECT doc_content FROM doc WHERE doc_id=5");
echo "Doc size:".cubrid_lob_size($lobs[0]);
cubrid_lob_export($conn, $lobs[0], "doc_5.txt");
cubrid_lob_close($lobs);
?>
Zobacz też:
- cubrid_lob_get() - Get BLOB/CLOB data
- cubrid_lob_close() - Close BLOB/CLOB data
- cubrid_lob_export() - Export BLOB/CLOB data to file
- cubrid_lob_send() - Read BLOB/CLOB data and send straight to browser
cubrid_lock_read
(PECL CUBRID >= 8.3.0)
cubrid_lock_read — Set a read lock on the given OID
Opis
$conn_identifier
, string $oid
)
The cubrid_lock_read() function is used to put read
lock on the instance pointed by given oid.
Parametry
-
conn_identifier -
Connection identifier.
-
oid -
OID of the instance that you want to put read lock on.
Zwracane wartości
TRUE, when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_lock_read() example
<?php
$conn = cubrid_connect("localhost", 33088, "demodb");
@cubrid_execute($conn, "DROP TABLE foo");
cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");
$req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);
cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$oid = cubrid_current_oid($req);
cubrid_lock_read($conn, $oid);
$attr = cubrid_get($conn, $oid, "b");
var_dump($attr);
$attr = cubrid_get($conn, $oid);
var_dump($attr);
cubrid_close_request($req);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
string(9) "{1, 2, 3}"
array(4) {
["a"]=>
string(1) "1"
["b"]=>
array(3) {
[0]=>
string(1) "1"
[1]=>
string(1) "2"
[2]=>
string(1) "3"
}
["c"]=>
array(4) {
[0]=>
string(2) "11"
[1]=>
string(2) "22"
[2]=>
string(2) "33"
[3]=>
string(3) "333"
}
["d"]=>
string(10) "a "
}
cubrid_lock_write
(PECL CUBRID >= 8.3.0)
cubrid_lock_write — Set a write lock on the given OID
Opis
$conn_identifier
, string $oid
)
The cubrid_lock_write() function is used to put write
lock on the instance pointed by the given oid.
Parametry
-
conn_identifier -
Connection identifier.
-
oid -
OID of the instance that you want to put write lock on.
Zwracane wartości
TRUE, when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_lock_write() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
@cubrid_execute($conn, "DROP TABLE foo");
cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");
$req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);
cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$oid = cubrid_current_oid($req);
cubrid_lock_write($conn, $oid);
$attr = cubrid_col_get($conn, $oid, "b");
var_dump($attr);
cubrid_put($conn, $oid, "b", array(2, 4, 8));
$attr = cubrid_col_get($conn, $oid, "b");
var_dump($attr);
cubrid_close_request($req);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
array(3) {
[0]=>
string(1) "1"
[1]=>
string(1) "2"
[2]=>
string(1) "3"
}
array(3) {
[0]=>
string(1) "2"
[1]=>
string(1) "4"
[2]=>
string(1) "8"
}
cubrid_move_cursor
(PECL CUBRID >= 8.3.0)
cubrid_move_cursor — Move the cursor in the result
Opis
$req_identifier
, int $offset
[, int $origin = CUBRID_CURSOR_CURRENT
] )
The cubrid_move_cursor() function is used to move the
current cursor location of req_identifier by the
value set in the offset argument, to the direction
set in the origin argument. To set the
origin argument, you can use CUBRID_CURSOR_FIRST
for the first part of the result, CUBRID_CURSOR_CURRENT for the current
location of the result, or CUBRID_CURSOR_LAST for the last part of the
result. If origin argument is not explicitly
designated, then the function uses CUBRID_CURSOR_CURRENT as its default
value.
If the value of cursor movement range goes over the valid limit, then the cursor moves to the next location after the valid range for the cursor. For example, if you move 20 units in the result with the size of 10, then the cursor will move to 11th place and return CUBRID_NO_MORE_DATA.
Parametry
-
req_identifier -
Request identifier.
-
offset -
Number of units you want to move the cursor.
-
origin -
Location where you want to move the cursor from CUBRID_CURSOR_FIRST, CUBRID_CURSOR_CURRENT, CUBRID_CURSOR_LAST.
Zwracane wartości
TRUE, when process is successful.
FALSE, when process is unsucceful.
Przykłady
Przykład #1 cubrid_move_cursor() example
<?php
$conn = cubrid_connect("127.0.0.1", 33000, "demodb");
$req = cubrid_execute($conn, "SELECT * FROM code");
cubrid_move_cursor($req, 1, CUBRID_CURSOR_LAST);
$result = cubrid_fetch_row($req);
var_dump($result);
cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$result = cubrid_fetch_row($req);
var_dump($result);
cubrid_move_cursor($req, 1, CUBRID_CURSOR_CURRENT);
$result = cubrid_fetch_row($req);
var_dump($result);
cubrid_close_request($req);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
array(2) {
[0]=>
string(1) "G"
[1]=>
string(4) "Gold"
}
array(2) {
[0]=>
string(1) "X"
[1]=>
string(5) "Mixed"
}
array(2) {
[0]=>
string(1) "M"
[1]=>
string(3) "Man"
}
cubrid_next_result
(PECL CUBRID >= 8.4.0)
cubrid_next_result — Get result of next query when executing multiple SQL statements
Opis
$result
)The cubrid_next_result() function is used to get results of next query if multiple SQL statements are executed and CUBRID_EXEC_QUERY_ALL flag is set upon cubrid_execute().
Zwracane wartości
TRUE, when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_next_result() example
<?php
$conn = cubrid_connect("127.0.0.1", 33000, "demodb");
$sql_stmt = "SELECT * FROM code; SELECT * FROM history WHERE host_year=2004 AND event_code=20281";
$res = cubrid_execute($conn, $sql_stmt, CUBRID_EXEC_QUERY_ALL);
get_result_info($res);
cubrid_next_result($res);
get_result_info($res);
function get_result_info($req)
{
printf("\n------------ get_result_info --------------------\n");
$row_num = cubrid_num_rows($req);
$col_num = cubrid_num_cols($req);
$column_name_list = cubrid_column_names($req);
$column_type_list = cubrid_column_types($req);
$column_last_name = cubrid_field_name($req, $col_num - 1);
$column_last_table = cubrid_field_table($req, $col_num - 1);
$column_last_type = cubrid_field_type($req, $col_num - 1);
$column_last_len = cubrid_field_len($req, $col_num - 1);
$column_1_flags = cubrid_field_flags($req, 1);
printf("%-30s %d\n", "Row count:", $row_num);
printf("%-30s %d\n", "Column count:", $col_num);
printf("\n");
printf("%-30s %-30s %-15s\n", "Column Names", "Column Types", "Column Len");
printf("------------------------------------------------------------------------------\n");
$size = count($column_name_list);
for($i = 0; $i < $size; $i++) {
$column_len = cubrid_field_len($req, $i);
printf("%-30s %-30s %-15s\n", $column_name_list[$i], $column_type_list[$i], $column_len);
}
printf("\n\n");
printf("%-30s %s\n", "Last Column Name:", $column_last_name);
printf("%-30s %s\n", "Last Column Table:", $column_last_table);
printf("%-30s %s\n", "Last Column Type:", $column_last_type);
printf("%-30s %d\n", "Last Column Len:", $column_last_len);
printf("%-30s %s\n", "Second Column Flags:", $column_1_flags);
printf("\n\n");
}
?>
Powyższy przykład wyświetli:
------------ get_result_info -------------------- Row count: 6 Column count: 2 Column Names Column Types Column Len ------------------------------------------------------------------------------ s_name char(1) 1 f_name varchar(6) 6 Last Column Name: f_name Last Column Table: code Last Column Type: varchar(6) Last Column Len: 6 Second Column Flags: ------------ get_result_info -------------------- Row count: 4 Column count: 5 Column Names Column Types Column Len ------------------------------------------------------------------------------ event_code integer 11 athlete varchar(40) 40 host_year integer 11 score varchar(10) 10 unit varchar(5) 5 Last Column Name: unit Last Column Table: history Last Column Type: varchar(5) Last Column Len: 5 Second Column Flags: not_null primary_key unique_key
cubrid_num_cols
(PECL CUBRID >= 8.3.0)
cubrid_num_cols — Return the number of columns in the result set
Opis
$result
)The cubrid_num_cols() function is used to get the number of columns from the query result. It can only be used when the query executed is a select statement.
Parametry
-
result -
Result.
Zwracane wartości
Number of columns, when process is successful.
FALSE, if SQL statement is not SELECT.
Przykłady
Przykład #1 cubrid_num_cols() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = cubrid_execute($conn, "SELECT * FROM code");
$row_num = cubrid_num_rows($req);
$col_num = cubrid_num_cols($req);
printf("Row Num: %d\nColumn Num: %d\n", $row_num, $col_num);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
Row Num: 6 Column Num: 2
Zobacz też:
- cubrid_execute() - Execute a prepared SQL statement
- cubrid_num_rows() - Get the number of rows in the result set
cubrid_num_rows
(PECL CUBRID >= 8.3.0)
cubrid_num_rows — Get the number of rows in the result set
Opis
$result
)The cubrid_num_rows() function is used to get the number of rows from the query result. You can use it only when the query executed is a select statement. When you want to know such value for INSERT, UPDATE, or DELETE query, you have to use the cubrid_affected_rows() function.
Note: The cubrid_num_rows() function can only be used for synchronous query; it returns 0 when it is used for asynchronous query.
Zwracane wartości
Number of rows, when process is successful.
0 when the query was done in async mode.
-1, if SQL statement is not SELECT.
FALSE when process is unsuccessful.
Przykłady
Przykład #1 cubrid_num_rows() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = cubrid_execute($conn, "SELECT * FROM code");
$row_num = cubrid_num_rows($req);
$col_num = cubrid_num_cols($req);
printf("Row Num: %d\nColumn Num: %d\n", $row_num, $col_num);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
Row Num: 6 Column Num: 2
Zobacz też:
- cubrid_execute() - Execute a prepared SQL statement
- cubrid_num_cols() - Return the number of columns in the result set
- cubrid_affected_rows() - Return the number of rows affected by the last SQL statement
cubrid_pconnect_with_url
(PECL CUBRID >= 8.3.1)
cubrid_pconnect_with_url — Open a persistent connection to CUBRID server
Opis
$conn_url
[, string $userid
[, string $passwd
]] )Establishes a persistent connection to a CUBRID server.
cubrid_pconnect_with_url() acts very much like cubrid_connect_with_url() with two major differences.
First, when connecting, the function would first try to find a (persistent) link that's already open with the same host, port, dbname and userid. If one is found, an identifier for it will be returned instead of opening a new connection.
Second, the connection to the SQL server will not be closed when the execution of the script ends. Instead, the link will remain open for future use (cubrid_close() or cubrid_disconnect() will not close links established by cubrid_pconnect_with_url()).
This type of link is therefore called 'persistent'.
<url> ::= CUBRID:<host>:<db_name>:<db_user>:<db_password>:[?<properties>] <properties> ::= <property> [&<property>] <properties> ::= autocommit=<autocommit_mode> <alternative_hosts> ::= <standby_broker1_host>:<port> [,<standby_broker2_host>:<port>] <host> := HOSTNAME | IP_ADDR <time> := SECOND
or <url> ::= cci:CUBRID:<host>:<db_name>:......
- host : A host name or IP address of the master database
- db_name : A name of the database
- db_user : A name of the database user
- db_password : A database user password
- autocommit : The database connection auto-commit mode
- alhosts: Specifies the broker information of the standby server, which is used for failover when it is impossible to connect to the active server. You can specify multiple brokers for failover, and the connection to the brokers is attempted in the order listed in alhosts
- rctime : An interval between the attempts to connect to the active broker in which failure occurred. After a failure occurs, the system connects to the broker specified by althosts (failover), terminates the transaction, and then attempts to connect to the active broker of the master database at every rctime. The default value is 600 seconds.
Informacja:
? and : that are used as identifiers in PHP connection URL can't be included in the password. The following is an example of a password that is invalid to use as connection URL because it contains "?:".
$url = "CUBRID:localhost:33000:tdb:dba:12?:?autocommit=off";
Passwords that contain ? or : may be passed as a seperate parameter.
$url = "CUBRID:localhost:33000:tbd:::?autocommit=off"; $conn = cubrid_connect_with_url ($url, "dba", "12?");
Parametry
-
conn_url -
A character string that contains server connection information.
-
userid -
User name for the database.
-
passwd -
User password.
Zwracane wartości
Connection identifier, when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_connect_with_url() url without properties example
<?php
$conn_url = "CUBRID:127.0.0.1:33000:demodb:dba:123456:?autocommit=off"
$con = cubrid_pconnect_with_url ($conn_url);
if ($con) {
echo "connected successfully";
$req =cubrid_execute($con, "insert into person values(1,'James')");
if ($req) {
cubrid_close_request ($req);
cubrid_commit ($con);
} else {
cubrid_rollback ($con);
}
cubrid_disconnect ($con);
}
?>
Przykład #2 cubrid_connect_with_url() url with properties example
<?php
$conn_url = "CUBRID:127.0.0.1:33000:demodb:dba:123456:?autocommit=off&althost=10.34.63.132:33088&rctime=100"
$con = cubrid_connect_with_url ($conn_url);
if ($con) {
echo "connected successfully";
$req =cubrid_execute($con, "insert into person values(1,'James')");
if ($req) {
cubrid_close_request ($req);
cubrid_commit ($con);
} else {
cubrid_rollback ($con);
}
cubrid_disconnect ($con);
}
?>
Zobacz też:
- cubrid_connect() - Open a connection to a CUBRID Server
- cubrid_pconnect() - Open a persistent connection to a CUBRID server
- cubrid_pconnect_with_url()
- cubrid_disconnect() - Close a database connection
- cubrid_close() - Close CUBRID connection
cubrid_pconnect
(PECL CUBRID >= 8.3.1)
cubrid_pconnect — Open a persistent connection to a CUBRID server
Opis
$host
, int $port
, string $dbname
[, string $userid
[, string $passwd
]] )Establishes a persistent connection to a CUBRID server.
cubrid_pconnect() acts very much like cubrid_connect() with two major differences.
First, when connecting, the function would first try to find a (persistent) link that's already open with the same host, port, dbname and userid. If one is found, an identifier for it will be returned instead of opening a new connection.
Second, the connection to the SQL server will not be closed when the execution of the script ends. Instead, the link will remain open for future use (cubrid_close() or cubrid_disconnect() will not close links established by cubrid_pconnect()).
This type of link is therefore called 'persistent'.
Parametry
-
host -
Host name or IP address of CUBRID CAS server.
-
port -
Port number of CUBRID CAS server (BROKER_PORT configured in $CUBRID/conf/cubrid_broker.conf).
-
dbname -
Name of database.
-
userid -
User name for the database.
-
passwd -
User password.
Zwracane wartości
Connection identifier, when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_connect() example
<?php
printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());
printf("\n");
$conn = cubrid_pconnect("localhost", 33000, "demodb");
if (!$conn) {
die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
}
$db_params = cubrid_get_db_parameter($conn);
while (list($param_name, $param_value) = each($db_params)) {
printf("%-30s %s\n", $param_name, $param_value);
}
printf("\n");
$server_info = cubrid_get_server_info($conn);
$client_info = cubrid_get_client_info();
printf("%-30s %s\n", "Server Info:", $server_info);
printf("%-30s %s\n", "Client Info:", $client_info);
printf("\n");
$charset = cubrid_get_charset($conn);
printf("%-30s %s\n", "CUBRID Charset:", $charset);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
CUBRID PHP Version: 8.4.1.0001 PARAM_ISOLATION_LEVEL 3 LOCK_TIMEOUT 0 MAX_STRING_LENGTH 1073741823 PARAM_AUTO_COMMIT 0 Server Info: 8.4.1.0508 Client Info: 8.4.1 CUBRID Charset: iso8859-1
Zobacz też:
- cubrid_connect() - Open a connection to a CUBRID Server
- cubrid_connect_with_url() - Establish the environment for connecting to CUBRID server
- cubrid_pconnect_with_url() - Open a persistent connection to CUBRID server
- cubrid_disconnect() - Close a database connection
- cubrid_close() - Close CUBRID connection
cubrid_prepare
(PECL CUBRID >= 8.3.0)
cubrid_prepare — Prepare an SQL statement for execution
Opis
$conn_identifier
, string $prepare_stmt
[, int $option = 0
] )The cubrid_prepare() function is a sort of API which represents SQL statements compiled previously to a given connection handle. This pre-compiled SQL statement will be included in the cubrid_prepare().
Accordingly, you can use this statement effectively to execute several times repeatedly or to process long data. Only a single statement can be used and a parameter may put a question mark (?) to appropriate area in the SQL statement. Add a parameter when you bind a value in the VALUES clause of INSERT statement or in the WHERE clause. Note that it is allowed to bind a value to a MARK(?) by the cubrid_bind() only.
Parametry
-
conn_identifier -
Connection identifier.
-
prepare_stmt -
Prepare query.
-
option -
OID return option CUBRID_INCLUDE_OID.
Zwracane wartości
Request identifier, if process is successful;
FALSE, if process is unsuccessful.
Przykłady
Przykład #1 cubrid_prepare() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$sql = <<<EOD
SELECT g.event_code, e.name
FROM game g
JOIN event e ON g.event_code=e.code
WHERE host_year = ? AND event_code NOT IN (SELECT event_code FROM game WHERE host_year=?) GROUP BY event_code;
EOD;
$req = cubrid_prepare($conn, $sql);
cubrid_bind($req, 1, 2004);
cubrid_bind($req, 2, 2000);
cubrid_execute($req);
$row_num = cubrid_num_rows($req);
printf("There are %d event that exits in 2004 olympic but not in 2000. For example:\n\n", $row_num);
printf("%-15s %s\n", "Event_code", "Event_name");
printf("----------------------------\n");
$row = cubrid_fetch_assoc($req);
printf("%-15d %s\n", $row["event_code"], $row["name"]);
$row = cubrid_fetch_assoc($req);
printf("%-15d %s\n", $row["event_code"], $row["name"]);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
There are 27 event that exits in 2004 olympic but not in 2000. For example: Event_code Event_name ---------------------------- 20063 +91kg 20070 64kg
Zobacz też:
- cubrid_execute() - Execute a prepared SQL statement
- cubrid_bind() - Bind variables to a prepared statement as parameters
cubrid_put
(PECL CUBRID >= 8.3.0)
cubrid_put — Update a column using OID
Opis
The cubrid_put() function is used to update an
attribute of the instance of the given oid.
You can update single attribute by using string data type to set
attr. In such case, you can use integer,
float-point, or string type data for the value
argument. To update multiple number of attributes, you can disregard the
attr argument, and set
value argument with associative array data type.
Parametry
-
conn_identifier -
Connection identifier.
-
oid -
OID of the instance that you want to update.
-
attr -
Name of the attribute that you want to update.
-
value -
New value that you want to assign to the attribute.
Zwracane wartości
TRUE, when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_put() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
@cubrid_execute($conn, "DROP TABLE foo");
cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");
$req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);
cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$oid = cubrid_current_oid($req);
$attr = cubrid_col_get($conn, $oid, "b");
var_dump($attr);
cubrid_put($conn, $oid, "b", array(2, 4, 8));
$attr = cubrid_col_get($conn, $oid, "b");
var_dump($attr);
cubrid_close_request($req);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
array(3) {
[0]=>
string(1) "1"
[1]=>
string(1) "2"
[2]=>
string(1) "3"
}
array(3) {
[0]=>
string(1) "2"
[1]=>
string(1) "4"
[2]=>
string(1) "8"
}
Zobacz też:
- cubrid_get() - Get a column using OID
- cubrid_set_add() - Insert a single element to set type column using OID
- cubrid_set_drop() - Delete an element from set type column using OID
- cubrid_seq_insert() - Insert an element to a sequence type column using OID
- cubrid_seq_drop() - Delete an element from sequence type column using OID
- cubrid_seq_put() - Update the element value of sequence type column using OID
cubrid_rollback
(PECL CUBRID >= 8.3.0)
cubrid_rollback — Roll back a transaction
Opis
$conn_identifier
)
The cubrid_rollback() function executes rollback on the
transaction pointed by conn_identifier, currently in
progress.
Connection to server is closed after calling cubrid_rollback(). Connection handle, however, is still valid.
Parametry
-
conn_identifier -
Connection identifier.
Zwracane wartości
TRUE, when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_rollback() example
<?php
$conn = cubrid_connect("127.0.0.1", 33000, "demodb");
@cubrid_execute($conn, "DROP TABLE publishers");
$sql = <<<EOD
CREATE TABLE publishers(
pub_id CHAR(3),
pub_name VARCHAR(20),
city VARCHAR(15),
state CHAR(2),
country VARCHAR(15)
)
EOD;
if (!cubrid_execute($conn, $sql)) {
printf("Error facility: %d\nError code: %d\nError msg: %s\n", cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());
cubrid_disconnect($conn);
exit;
}
$req = cubrid_prepare($conn, "INSERT INTO publishers VALUES(?, ?, ?, ?, ?)");
$id_list = array("P01", "P02", "P03", "P04");
$name_list = array("Abatis Publishers", "Core Dump Books", "Schadenfreude Press", "Tenterhooks Press");
$city_list = array("New York", "San Francisco", "Hamburg", "Berkeley");
$state_list = array("NY", "CA", NULL, "CA");
$country_list = array("USA", "USA", "Germany", "USA");
for ($i = 0, $size = count($id_list); $i < $size; $i++) {
cubrid_bind($req, 1, $id_list[$i]);
cubrid_bind($req, 2, $name_list[$i]);
cubrid_bind($req, 3, $city_list[$i]);
cubrid_bind($req, 4, $state_list[$i]);
cubrid_bind($req, 5, $country_list[$i]);
if (!($ret = cubrid_execute($req))) {
break;
}
}
if (!$ret) {
cubrid_rollback($conn);
} else {
cubrid_commit($conn);
$req = cubrid_execute($conn, "SELECT * FROM publishers");
while ($result = cubrid_fetch_assoc($req)) {
printf("%-3s %-20s %-15s %-3s %-15s\n",
$result["pub_id"], $result["pub_name"], $result["city"], $result["state"], $result["country"]);
}
}
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
P01 Abatis Publishers New York NY USA P02 Core Dump Books San Francisco CA USA P03 Schadenfreude Press Hamburg Germany P04 Tenterhooks Press Berkeley CA USA
Zobacz też:
- cubrid_commit() - Commit a transaction
- cubrid_disconnect() - Close a database connection
cubrid_schema
(PECL CUBRID >= 8.3.0)
cubrid_schema — Get the requested schema information
Opis
$conn_identifier
, int $schema_type
[, string $class_name
[, string $attr_name
]] )
The cubrid_schema() function is used to get the
requested schema information from database. You have to designate
class_name, if you want to get information on
certain class, attr_name, if you want to get
information on certain attribute (can be used only with CUBRID_
SCH_ATTR_PRIVILEGE).
The result of the cubrid_schema function is returned as a two-dimensional array (column (associative array) * row (numeric array)). The following tables shows types of schema and the column structure of the result array to be returned based on the schema type.
| Schema | Column Number | Column Name | Value |
|---|---|---|---|
| CUBRID_SCH_CLASS | 1 | NAME | |
| 2 | TYPE | 0:system class 1:vclass 2:class | |
| CUBRID_SCH_VCLASS | 1 | NAME | |
| 2 | TYPE | 1:vclass | |
| CUBRID_SCH_QUERY_SPEC | 1 | QUERY_SPEC | |
| CUBRID_SCH_ATTRIBUTE / CUBRID_SCH_CLASS_ATTRIBUTE | 1 | ATTR_NAME | |
| 2 | DOMAIN | ||
| 3 | SCALE | ||
| 4 | PRECISION | ||
| 5 | INDEXED | 1:indexed | |
| 6 | NOT NULL | 1:not null | |
| 7 | SHARED | 1:shared | |
| 8 | UNIQUE | 1:unique | |
| 9 | DEFAULT | ||
| 10 | ATTR_ORDER | base:1 | |
| 11 | CLASS_NAME | ||
| 12 | SOURCE_CLASS | ||
| 13 | IS_KEY | 1:key | |
| CUBRID_SCH_METHOD / CUBRID_SCH_CLASS_METHOD | 1 | NAME | |
| 2 | RET_DOMAIN | ||
| 3 | ARG_DOMAIN | ||
| CUBRID_SCH_METHOD_FILE | 1 | METHOD_FILE | |
| CUBRID_SCH_SUPERCLASS / CUBRID_SCH_DIRECT_SUPER_CLASS / CUBRID_SCH_SUBCLASS | 1 | CLASS_NAME | |
| 2 | TYPE | 0:system class 1:vclass 2:class | |
| CUBRID_SCH_CONSTRAINT | 1 | TYPE | 0:unique 1:index 2:reverse unique 3:reverse index |
| 2 | NAME | ||
| 3 | ATTR_NAME | ||
| 4 | NUM_PAGES | ||
| 5 | NUM_KEYS | ||
| 6 | PRIMARY_KEY | 1:primary key | |
| 7 | KEY_ORDER | base:1 | |
| CUBRID_SCH_TRIGGER | 1 | NAME | |
| 2 | STATUS | ||
| 3 | EVENT | ||
| 4 | TARGET_CLASS | ||
| 5 | TARGET_ATTR | ||
| 6 | ACTION_TIME | ||
| 7 | ACTION | ||
| 8 | PRIORITY | ||
| 9 | CONDITION_TIME | ||
| 10 | CONDITION | ||
| CUBRID_SCH_CLASS_PRIVILEGE / CUBRID_SCH_ATTR_PRIVILEGE | 1 | CLASS_NAME / ATTR_NAME | |
| 2 | PRIVILEGE | ||
| 3 | GRANTABLE | ||
| CUBRID_SCH_PRIMARY_KEY | 1 | CLASS_NAME | |
| 2 | ATTR_NAME | ||
| 3 | KEY_SEQ | base:1 | |
| 4 | KEY_NAME | ||
| CUBRID_SCH_IMPORTED_KEYS / CUBRID_SCH_EXPORTED_KEYS / CUBRID_SCH_CROSS_REFERENCE | 1 | PKTABLE_NAME | |
| 2 | PKCOLUMN_NAME | ||
| 3 | FKTABLE_NAME | base:1 | |
| 4 | FKCOLUMN_NAME | ||
| 5 | KEY_SEQ | base:1 | |
| 6 | UPDATE_ACTION | 0:cascade 1:restrict 2:no action 3:set null | |
| 7 | DELETE_ACTION | 0:cascade 1:restrict 2:no action 3:set null | |
| 8 | FK_NAME | ||
| 9 | PK_NAME |
Parametry
-
conn_identifier -
Connection identifier.
-
schema_type -
Schema data that you want to know.
-
class_name -
Class you want to know the schema of.
-
attr_name -
Attribute you want to know the schema of.
Zwracane wartości
Array containing the schema information, when process is successful;
FALSE, when process is unsuccessful
Rejestr zmian
| Wersja | Opis |
|---|---|
| 8.3.1 | Change return value: when process is unsuccessful, return false, not -1. |
Przykłady
Przykład #1 cubrid_schema() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
printf("\n--- Primary Key ---\n");
$pk = cubrid_schema($conn, CUBRID_SCH_PRIMARY_KEY, "game");
var_dump($pk);
printf("\n--- Foreign Keys ---\n");
$fk = cubrid_schema($conn, CUBRID_SCH_IMPORTED_KEYS, "game");
var_dump($fk);
printf("\n--- Column Attribute ---\n");
$attr = cubrid_schema($conn, CUBRID_SCH_ATTRIBUTE, "stadium", "area");
var_dump($attr);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
--- Primary Key ---
array(3) {
[0]=>
array(4) {
["CLASS_NAME"]=>
string(4) "game"
["ATTR_NAME"]=>
string(12) "athlete_code"
["KEY_SEQ"]=>
string(1) "3"
["KEY_NAME"]=>
string(41) "pk_game_host_year_event_code_athlete_code"
}
[1]=>
array(4) {
["CLASS_NAME"]=>
string(4) "game"
["ATTR_NAME"]=>
string(10) "event_code"
["KEY_SEQ"]=>
string(1) "2"
["KEY_NAME"]=>
string(41) "pk_game_host_year_event_code_athlete_code"
}
[2]=>
array(4) {
["CLASS_NAME"]=>
string(4) "game"
["ATTR_NAME"]=>
string(9) "host_year"
["KEY_SEQ"]=>
string(1) "1"
["KEY_NAME"]=>
string(41) "pk_game_host_year_event_code_athlete_code"
}
}
--- Foreign Keys ---
array(2) {
[0]=>
array(9) {
["PKTABLE_NAME"]=>
string(7) "athlete"
["PKCOLUMN_NAME"]=>
string(4) "code"
["FKTABLE_NAME"]=>
string(4) "game"
["FKCOLUMN_NAME"]=>
string(12) "athlete_code"
["KEY_SEQ"]=>
string(1) "1"
["UPDATE_RULE"]=>
string(1) "1"
["DELETE_RULE"]=>
string(1) "1"
["FK_NAME"]=>
string(20) "fk_game_athlete_code"
["PK_NAME"]=>
string(15) "pk_athlete_code"
}
[1]=>
array(9) {
["PKTABLE_NAME"]=>
string(5) "event"
["PKCOLUMN_NAME"]=>
string(4) "code"
["FKTABLE_NAME"]=>
string(4) "game"
["FKCOLUMN_NAME"]=>
string(10) "event_code"
["KEY_SEQ"]=>
string(1) "1"
["UPDATE_RULE"]=>
string(1) "1"
["DELETE_RULE"]=>
string(1) "1"
["FK_NAME"]=>
string(18) "fk_game_event_code"
["PK_NAME"]=>
string(13) "pk_event_code"
}
}
--- Column Attribute ---
array(1) {
[0]=>
array(13) {
["ATTR_NAME"]=>
string(4) "area"
["DOMAIN"]=>
string(1) "7"
["SCALE"]=>
string(1) "2"
["PRECISION"]=>
string(2) "10"
["INDEXED"]=>
string(1) "0"
["NON_NULL"]=>
string(1) "0"
["SHARED"]=>
string(1) "0"
["UNIQUE"]=>
string(1) "0"
["DEFAULT"]=>
NULL
["ATTR_ORDER"]=>
string(1) "4"
["CLASS_NAME"]=>
string(7) "stadium"
["SOURCE_CLASS"]=>
string(7) "stadium"
["IS_KEY"]=>
string(1) "0"
}
}
cubrid_seq_drop
(PECL CUBRID >= 8.3.0)
cubrid_seq_drop — Delete an element from sequence type column using OID
Opis
$conn_identifier
, string $oid
, string $attr_name
, int $index
)The cubrid_seq_drop() function is used to delete an element you request from the given sequence type attribute in the database.
Parametry
-
conn_identifier -
Connection identifier.
-
oid -
OID of the instance you want to work with.
-
attr_name -
Name of the attribute that you want to delete an element from.
-
index -
Index of the element that you want to delete (1-based).
Zwracane wartości
TRUE, when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_seq_drop() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
@cubrid_execute($conn, "DROP TABLE foo");
cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c sequence(int), d char(10))");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
$req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);
cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$oid = cubrid_current_oid($req);
$attr = cubrid_col_get($conn, $oid, "c");
var_dump($attr);
cubrid_seq_drop($conn, $oid, "c", 4);
$attr = cubrid_col_get($conn, $oid, "c");
var_dump($attr);
cubrid_close_request($req);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
array(4) {
[0]=>
string(2) "11"
[1]=>
string(2) "22"
[2]=>
string(2) "33"
[3]=>
string(3) "333"
}
array(3) {
[0]=>
string(2) "11"
[1]=>
string(2) "22"
[2]=>
string(2) "33"
}
Zobacz też:
- cubrid_seq_insert() - Insert an element to a sequence type column using OID
- cubrid_seq_put() - Update the element value of sequence type column using OID
cubrid_seq_insert
(PECL CUBRID >= 8.3.0)
cubrid_seq_insert — Insert an element to a sequence type column using OID
Opis
$conn_identifier
, string $oid
, string $attr_name
, int $index
, string $seq_element
)The cubrid_col_insert() function is used to insert an element to a sequence type attribute in a requested location.
Parametry
-
conn_identifier -
Connection identifier.
-
oid -
OID of the instance you want to work with.
-
attr_name -
Name of the attribute you want to insert an instance to.
-
index -
Location of the element, you want to insert the element to (1-based).
-
seq_element -
Content of the element that you want to insert.
Zwracane wartości
TRUE, when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_seq_insert() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
@cubrid_execute($conn, "DROP TABLE foo");
cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c sequence(int), d char(10))");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
$req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);
cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$oid = cubrid_current_oid($req);
$attr = cubrid_col_get($conn, $oid, "c");
var_dump($attr);
cubrid_seq_insert($conn, $oid, "c", 5, "44");
$attr = cubrid_col_get($conn, $oid, "c");
var_dump($attr);
cubrid_close_request($req);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
array(4) {
[0]=>
string(2) "11"
[1]=>
string(2) "22"
[2]=>
string(2) "33"
[3]=>
string(3) "333"
}
array(5) {
[0]=>
string(2) "11"
[1]=>
string(2) "22"
[2]=>
string(2) "33"
[3]=>
string(3) "333"
[4]=>
string(2) "44"
}
Zobacz też:
- cubrid_seq_drop() - Delete an element from sequence type column using OID
- cubrid_seq_put() - Update the element value of sequence type column using OID
cubrid_seq_put
(PECL CUBRID >= 8.3.0)
cubrid_seq_put — Update the element value of sequence type column using OID
Opis
$conn_identifier
, string $oid
, string $attr_name
, int $index
, string $seq_element
)The cubrid_seq_put() function is used to update the content of the requested element in a sequent type attribute using OID.
Parametry
-
conn_identifier -
Connection identifier.
-
oid -
OID of the instance you want to work with.
-
attr_name -
Name of the attribute that you want to update an element.
-
index -
Index (1-based) of the element that you want to update.
-
seq_element -
New content that you want to use for the update.
Zwracane wartości
TRUE, when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_seq_put() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
@cubrid_execute($conn, "DROP TABLE foo");
cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c sequence(int), d char(10))");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
$req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);
cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$oid = cubrid_current_oid($req);
$attr = cubrid_col_get($conn, $oid, "c");
var_dump($attr);
cubrid_seq_put($conn, $oid, "c", 1, "111");
$attr = cubrid_col_get($conn, $oid, "c");
var_dump($attr);
cubrid_close_request($req);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
array(4) {
[0]=>
string(2) "11"
[1]=>
string(2) "22"
[2]=>
string(2) "33"
[3]=>
string(3) "333"
}
array(4) {
[0]=>
string(3) "111"
[1]=>
string(2) "22"
[2]=>
string(2) "33"
[3]=>
string(3) "333"
}
Zobacz też:
- cubrid_seq_drop() - Delete an element from sequence type column using OID
- cubrid_seq_insert() - Insert an element to a sequence type column using OID
cubrid_set_add
(PECL CUBRID >= 8.3.0)
cubrid_set_add — Insert a single element to set type column using OID
Opis
$conn_identifier
, string $oid
, string $attr_name
, string $set_element
)The cubrid_set_add() function is used to insert a single element to a set type attribute (set, multiset, sequence) you requested.
Parametry
-
conn_identifier -
Connection identifier.
-
oid -
OID of the instance you want to work with.
-
attr_name -
Name of the attribute you want to insert an element.
-
set_element -
Content of the element you want to insert.
Zwracane wartości
TRUE, when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_set_add() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
@cubrid_execute($conn, "DROP TABLE foo");
cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
$req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);
cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$oid = cubrid_current_oid($req);
$attr = cubrid_col_get($conn, $oid, "b");
var_dump($attr);
cubrid_set_add($conn, $oid, "b", "4");
$attr = cubrid_col_get($conn, $oid, "b");
var_dump($attr);
cubrid_close_request($req);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
array(3) {
[0]=>
string(1) "1"
[1]=>
string(1) "2"
[2]=>
string(1) "3"
}
array(4) {
[0]=>
string(1) "1"
[1]=>
string(1) "2"
[2]=>
string(1) "3"
[3]=>
string(1) "4"
}
cubrid_set_autocommit
(PECL CUBRID >= 8.4.0)
cubrid_set_autocommit — Set autocommit mode of the connection
Opis
$conn_identifier
, bool $mode
)The cubrid_set_autocommit() function is used to set the CUBRID database auto-commit mode of the current database connection.
In CUBRID PHP, an auto-commit mode is disabled by default for transaction management. When auto-commit mode is truned from off to on, any pending work is automatically committed.
Parametry
-
conn_identifier -
Connection identifier.
-
mode -
Auto-commit mode. The following constants can be used:
CUBRID_AUTOCOMMIT_FALSECUBRID_AUTOCOMMIT_TRUE
Zwracane wartości
TRUE, when process is successful.
FALSE, when process is unsuccessful.
Zobacz też:
- cubrid_get_autocommit() - Get auto-commit mode of the connection
- cubrid_commit() - Commit a transaction
cubrid_set_db_parameter
(PECL CUBRID >= 8.4.0)
cubrid_set_db_parameter — Sets the CUBRID database parameters
Opis
$conn_identifier
, int $param_type
, int $param_value
)The cubrid_set_db_parameter() function is used to set the CUBRID database parameters. It can set the following CUBRID database parameters:
PARAM_ISOLATION_LEVELPARAM_LOCK_TIMEOUT
Informacja:
The auto-commit mode can be set by using cubrid_set_autocommit().
Parametry
-
conn_identifier -
The CUBRID connection. If the connection identifier is not specified, the last link opened by cubrid_connect() is assumed.
-
param_type -
Database parameter type.
-
param_value -
Isolation level value (1-6) or lock timeout (in seconds) value.
Zwracane wartości
TRUE on success.
FALSE on failure.
Przykłady
Przykład #1 cubrid_get_db_parameter() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$params = cubrid_get_db_parameter($conn);
var_dump($params);
cubrid_set_autocommit($conn, CUBRID_AUTOCOMMIT_TRUE);
cubrid_set_db_parameter($conn, CUBRID_PARAM_ISOLATION_LEVEL, 2);
$params_new = cubrid_get_db_parameter($conn);
var_dump($params_new);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
array(4) {
["PARAM_ISOLATION_LEVEL"]=>
int(3)
["PARAM_LOCK_TIMEOUT"]=>
int(-1)
["PARAM_MAX_STRING_LENGTH"]=>
int(1073741823)
["PARAM_AUTO_COMMIT"]=>
int(0)
}
array(4) {
["PARAM_ISOLATION_LEVEL"]=>
int(2)
["PARAM_LOCK_TIMEOUT"]=>
int(-1)
["PARAM_MAX_STRING_LENGTH"]=>
int(1073741823)
["PARAM_AUTO_COMMIT"]=>
int(1)
}
Zobacz też:
- cubrid_get_db_parameter() - Returns the CUBRID database parameters
- cubrid_set_autocommit() - Set autocommit mode of the connection
cubrid_set_drop
(PECL CUBRID >= 8.3.0)
cubrid_set_drop — Delete an element from set type column using OID
Opis
$conn_identifier
, string $oid
, string $attr_name
, string $set_element
)The cubrid_set_drop() function is used to delete an element that you request from the given set type (set, multiset) attribute of the database.
Parametry
-
conn_identifier -
Connection identifier.
-
oid -
OID of the instance you want to work with.
-
attr_name -
Name of the attribute you want to delete an element from.
-
set_element -
Content of the element you want to delete.
Zwracane wartości
TRUE, when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_set_drop() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
@cubrid_execute($conn, "DROP TABLE foo");
cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
$req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);
cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$oid = cubrid_current_oid($req);
$attr = cubrid_col_get($conn, $oid, "b");
var_dump($attr);
cubrid_set_drop($conn, $oid, "b", "1");
$attr = cubrid_col_get($conn, $oid, "b");
var_dump($attr);
cubrid_close_request($req);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
array(3) {
[0]=>
string(1) "1"
[1]=>
string(1) "2"
[2]=>
string(1) "3"
}
array(2) {
[0]=>
string(1) "2"
[1]=>
string(1) "3"
}
cubrid_set_query_timeout
(PECL CUBRID >= 8.4.1)
cubrid_set_query_timeout — Set the timeout time of query execution
Opis
The cubrid_set_query_timeout() function is used to set the timeout time of query execution.
Parametry
-
req_identifier -
Request identifier.
-
timeout -
Timeout time, unit of msec.
Zwracane wartości
TRUE, when process is successful.
FALSE, when process is unsuccessful.
cubrid_version
(PECL CUBRID >= 8.3.0)
cubrid_version — Get the CUBRID PHP module's version
Opis
The cubrid_version() function is used to get the CUBRID PHP module's version.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Version information (eg. "8.3.1.0001").
Przykłady
Przykład #1 cubrid_version() example
<?php
printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());
printf("\n");
$conn = cubrid_connect("localhost", 33088, "demodb");
if (!$conn) {
die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
}
$db_params = cubrid_get_db_parameter($conn);
while (list($param_name, $param_value) = each($db_params)) {
printf("%-30s %s\n", $param_name, $param_value);
}
printf("\n");
$server_info = cubrid_get_server_info($conn);
$client_info = cubrid_get_client_info();
printf("%-30s %s\n", "Server Info:", $server_info);
printf("%-30s %s\n", "Client Info:", $client_info);
printf("\n");
$charset = cubrid_get_charset($conn);
printf("%-30s %s\n", "CUBRID Charset:", $charset);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
CUBRID PHP Version: 8.3.1.0005 PARAM_ISOLATION_LEVEL 3 LOCK_TIMEOUT -1 MAX_STRING_LENGTH 1073741823 PARAM_AUTO_COMMIT 0 Server Info: 8.3.1.0173 Client Info: 8.3.1 CUBRID Charset: iso8859-1
Zobacz też:
- cubrid_error_code() - Get error code for the most recent function call
- cubrid_error_code_facility() - Get the facility code of error
Spis treści
- cubrid_bind — Bind variables to a prepared statement as parameters
- cubrid_close_prepare — Close the request handle
- cubrid_close_request — Close the request handle
- cubrid_col_get — Get contents of collection type column using OID
- cubrid_col_size — Get the number of elements in collection type column using OID
- cubrid_column_names — Get the column names in result
- cubrid_column_types — Get column types in result
- cubrid_commit — Commit a transaction
- cubrid_connect_with_url — Establish the environment for connecting to CUBRID server
- cubrid_connect — Open a connection to a CUBRID Server
- cubrid_current_oid — Get OID of the current cursor location
- cubrid_disconnect — Close a database connection
- cubrid_drop — Delete an instance using OID
- cubrid_error_code_facility — Get the facility code of error
- cubrid_error_code — Get error code for the most recent function call
- cubrid_error_msg — Get last error message for the most recent function call
- cubrid_execute — Execute a prepared SQL statement
- cubrid_fetch — Fetch the next row from a result set
- cubrid_free_result — Free the memory occupied by the result data
- cubrid_get_autocommit — Get auto-commit mode of the connection
- cubrid_get_charset — Return the current CUBRID connection charset
- cubrid_get_class_name — Get the class name using OID
- cubrid_get_client_info — Return the client library version
- cubrid_get_db_parameter — Returns the CUBRID database parameters
- cubrid_get_query_timeout — Get the query timeout value of the request
- cubrid_get_server_info — Return the CUBRID server version
- cubrid_get — Get a column using OID
- cubrid_insert_id — Return the ID generated for the lastest updated AUTO_INCREMENT column
- cubrid_is_instance — Check whether the instance pointed by OID exists
- cubrid_lob_close — Close BLOB/CLOB data
- cubrid_lob_export — Export BLOB/CLOB data to file
- cubrid_lob_get — Get BLOB/CLOB data
- cubrid_lob_send — Read BLOB/CLOB data and send straight to browser
- cubrid_lob_size — Get BLOB/CLOB data size
- cubrid_lock_read — Set a read lock on the given OID
- cubrid_lock_write — Set a write lock on the given OID
- cubrid_move_cursor — Move the cursor in the result
- cubrid_next_result — Get result of next query when executing multiple SQL statements
- cubrid_num_cols — Return the number of columns in the result set
- cubrid_num_rows — Get the number of rows in the result set
- cubrid_pconnect_with_url — Open a persistent connection to CUBRID server
- cubrid_pconnect — Open a persistent connection to a CUBRID server
- cubrid_prepare — Prepare an SQL statement for execution
- cubrid_put — Update a column using OID
- cubrid_rollback — Roll back a transaction
- cubrid_schema — Get the requested schema information
- cubrid_seq_drop — Delete an element from sequence type column using OID
- cubrid_seq_insert — Insert an element to a sequence type column using OID
- cubrid_seq_put — Update the element value of sequence type column using OID
- cubrid_set_add — Insert a single element to set type column using OID
- cubrid_set_autocommit — Set autocommit mode of the connection
- cubrid_set_db_parameter — Sets the CUBRID database parameters
- cubrid_set_drop — Delete an element from set type column using OID
- cubrid_set_query_timeout — Set the timeout time of query execution
- cubrid_version — Get the CUBRID PHP module's version
CUBRID MySQL Compatibility Functions
cubrid_affected_rows
(PECL CUBRID >= 8.3.0)
cubrid_affected_rows — Return the number of rows affected by the last SQL statement
Opis
$conn_identifier
] )The cubrid_affected_rows() function is used to get the number of rows affected by the SQL statement (INSERT, DELETE, UPDATE).
Parametry
-
conn_identifier -
The CUBRID connection. If the connection identifier is not specified, the last link opend by cubrid_connect() is assumed.
Zwracane wartości
Number of rows affected by the SQL statement, when process is successful.
-1, when SQL statement is not INSERT, DELETE or UPDATE.
FALSE, when the request identifier is not specified, and there is no last
request.
Przykłady
Przykład #1 cubrid_affected_rows() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
@cubrid_execute($conn, "DROP TABLE cubrid_test");
cubrid_execute($conn, "CREATE TABLE cubrid_test (t varchar)");
for ($i = 0; $i < 5; $i++) {
cubrid_execute($conn, "INSERT INTO cubrid_test(t) VALUES('cubrid_test')");
}
cubrid_execute($conn, "DELETE FROM cubrid_test");
$affected_num = cubrid_affected_rows();
printf("Rows deleted: %d\n", $affected_num);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
Rows deleted: 5
cubrid_client_encoding
(PECL CUBRID >= 8.3.1)
cubrid_client_encoding — Return the current CUBRID connection charset
Opis
$conn_identifier
] )This function returns the current CUBRID connection charset and is similar to the CUBRID function cubrid_get_charset().
Parametry
-
conn_identifier -
The CUBRID connection. If the connection identifier is not specified, the last link opened by cubrid_connect() is assumed.
Zwracane wartości
A string that represents the CUBRID connection charset; on success.
FALSE on failure.
Przykłady
Przykład #1 cubrid_client_encoding() example
<?php
$con = cubrid_connect("localhost", 33000, "demodb");
if (!$con)
{
die('Could not connect.');
}
printf("CUBRID current charset: %s\n", cubrid_client_encoding($con));
?>
Powyższy przykład wyświetli:
CUBRID current charset: iso8859-1
cubrid_close
(PECL CUBRID >= 8.3.1)
cubrid_close — Close CUBRID connection
Opis
$conn_identifier
] )The cubrid_close() function ends the transaction currently on process, closes the connection handle and disconnects from server. If there exists any request handle not closed yet at this point, it will be closed. It is similar to the CUBRID function cubrid_disconnect().
Parametry
-
conn_identifier -
The CUBRID connection identifier. If the connection identifier is not specified, the last connection opened by cubrid_connect() is assumed.
Zwracane wartości
TRUE, when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_close() example
<?php
$con = cubrid_connect ("210.211.133.100", 12345, "demodb");
if ($con) {
echo "connected successfully";
$req = cubrid_execute ( $con, "insert into person values(1,'James')");
if ($req) {
cubrid_close_request ($req);
cubrid_commit ($con);
} else {
cubrid_rollback ($con);
}
cubrid_close ($con);
}
?>
Zobacz też:
- cubrid_disconnect() - Close a database connection
- cubrid_connect() - Open a connection to a CUBRID Server
- cubrid_connect_with_url() - Establish the environment for connecting to CUBRID server
cubrid_data_seek
(PECL CUBRID >= 8.3.0)
cubrid_data_seek — Move the internal row pointer of the CUBRID result
Opis
$result
, int $row_number
)
This function performs the moving of the internal row pointer of the
CUBRID result (associated with the specified result identifier) to point
to a specific row number. There are functions, such as
cubrid_fetch_assoc(), which use the current stored
value of row number.
Parametry
-
result -
The result.
-
row_number -
This is the desired row number of the new result pointer.
Zwracane wartości
Returns TRUE on success or FALSE on failure.
Przykłady
Przykład #1 cubrid_data_seek() example
<?php
$conn = cubrid_connect("127.0.0.1", 33000, "demodb");
$req = cubrid_execute($conn, "SELECT * FROM code");
cubrid_data_seek($req, 0);
$result = cubrid_fetch_row($req);
var_dump($result);
cubrid_data_seek($req, 2);
$result = cubrid_fetch_row($req);
var_dump($result);
cubrid_data_seek($req, 4);
$result = cubrid_fetch_row($req);
var_dump($result);
cubrid_close_request($req);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
array(2) {
[0]=>
string(1) "X"
[1]=>
string(5) "Mixed"
}
array(2) {
[0]=>
string(1) "M"
[1]=>
string(3) "Man"
}
array(2) {
[0]=>
string(1) "S"
[1]=>
string(6) "Silver"
}
cubrid_db_name
(PECL CUBRID >= 8.3.1)
cubrid_db_name — Get db name from results of cubrid_list_dbs
Opis
$result
, int $index
)Retrieve the database name from a call to cubrid_list_dbs().
Parametry
-
result -
The result pointer from a call to cubrid_list_dbs().
-
index -
The index into the result set.
Zwracane wartości
Returns the database name on success, and FALSE on failure. If FALSE
is returned, use cubrid_error() to determine the nature
of the error.
Przykłady
Przykład #1 cubrid_db_name() example
<?php
error_reporting(E_ALL);
$conn = cubrid_connect('dbhost', 33000, 'demodb', 'username', 'password');
$db_list = cubrid_list_dbs($conn);
$i = 0;
$cnt = count($db_list);
while ($i < $cnt) {
echo cubrid_db_name($db_list, $i) . "\n";
$i++;
}
?>
cubrid_errno
(PECL CUBRID >= 8.3.1)
cubrid_errno — Return the numerical value of the error message from previous CUBRID operation
Opis
$conn_identifier
] )Returns the error number from the last CUBRID function.
The cubrid_errno() function is used to get the error code of the error that occurred during the API execution. Usually, it gets the error code when API returns false as its return value.
Parametry
-
conn_identifier -
The CUBRID connection identifier. If the connection identifier is not specified, the last connection opened by cubrid_connect() is assumed.
Zwracane wartości
Returns the error number from the last CUBRID function, or 0 (zero) if no error occurred.
Przykłady
Przykład #1 cubrid_errno() example
<?php
$req = cubrid_execute($con, "select id, name from person");
if ($req) {
while (list ($id, $name) = cubrid_fetch($req))
echo $id, $name;
} else {
echo "Error Code: ", cubrid_errno($con);
echo "Error Message: ", cubrid_error($con);
}
?>
Zobacz też:
- cubrid_error() - Get the error message
- cubrid_error_code() - Get error code for the most recent function call
- cubrid_error_msg() - Get last error message for the most recent function call
cubrid_error
(PECL CUBRID >= 8.3.1)
cubrid_error — Get the error message
Opis
$connection
] )The cubrid_error() function is used to get the error message that occurred during the use of CUBRID API. Usually, it gets error message when API returns false as its return value.
Parametry
-
connection -
The CUBRID connection.
Zwracane wartości
Error message that occurred.
Przykłady
Przykład #1 cubrid_error() example
<?php
$req = cubrid_execute($con, "select id, name from person");
if ($req) {
while (list ($id, $name) = cubrid_fetch($req))
echo $id, $name;
} else {
echo "Error Code: ", cubrid_errno($con);
echo "Error Message: ", cubrid_error($con);
}
?>
Zobacz też:
- cubrid_errno() - Return the numerical value of the error message from previous CUBRID operation
- cubrid_error_code() - Get error code for the most recent function call
- cubrid_error_msg() - Get last error message for the most recent function call
cubrid_fetch_array
(PECL CUBRID >=8.3.0)
cubrid_fetch_array — Fetch a result row as an associative array, a numeric array, or both
Opis
$result
[, int $type = CUBRID_BOTH
] )The cubrid_fetch_array() function is used to get a single row from the query result and returns an array. The cursor automatically moves to the next row after getting the result.
Parametry
-
result -
Resultcomes from a call to cubrid_execute() -
type -
Array type of the fetched result CUBRID_NUM, CUBRID_ASSOC, CUBRID_BOTH.
Zwracane wartości
Returns an array of strings that corresponds to the fetched row, when process is successful.
FALSE, when there are no more rows; NULL, when process is unsuccessful.
The type of returned array depends on how type is defined. By using CUBRID_BOTH (default), you'll get an array with both associative and number indices, and you can decide which data type to use by setting the type argument. The type variable can be set to one of the following values:
- CUBRID_NUM : Numerical array (0-based)
- CUBRID_ASSOC : Associative array
- CUBRID_BOTH : Numerical & Associative array (default)
Przykłady
Przykład #1 cubrid_fetch_array() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = cubrid_execute($conn, "SELECT name,area,seats,address FROM stadium WHERE nation_code='GRE' AND seats > 10000");
printf("%-40s %-10s %-6s %-20s\n", "name", "area", "seats", "address");
while ($row = cubrid_fetch_array($req, CUBRID_NUM)) {
printf("%-40s %-10s %-6s %-20s\n", $row[0], $row[1], $row[2], $row[3]);
}
cubrid_close_request($req);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
name area seats address Panathinaiko Stadium 86300.00 50000 Athens, Greece Olympic Stadium 54700.00 13000 Athens, Greece Olympic Indoor Hall 34100.00 18800 Athens, Greece Olympic Hall 52400.00 21000 Athens, Greece Olympic Aquatic Centre 42500.00 11500 Athens, Greece Markopoulo Olympic Equestrian Centre 64000.00 15000 Markopoulo, Athens, Greece Faliro Coastal Zone Olympic Complex 34650.00 12171 Faliro, Athens, Greece Athens Olympic Stadium 120400.00 71030 Maroussi, Athens, Greece Ano Liossia 34000.00 12000 Ano Liosia, Athens, Greece
cubrid_fetch_assoc
(PECL CUBRID >= 8.3.0)
cubrid_fetch_assoc — Return the associative array that corresponds to the fetched row
Opis
$result
)This function returns the associative array, that corresponds to the fetched row, and then moves the internal data pointer ahead, or returns FALSE when the end is reached.
Zwracane wartości
Associative array, when process is successful.
FALSE, when there are no more rows; NULL, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_fetch_assoc() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = cubrid_execute($conn, "SELECT name,area,seats,address FROM stadium WHERE nation_code='GRE' AND seats > 10000");
printf("%-40s %-10s %-6s %-20s\n", "name", "area", "seats", "address");
while ($row = cubrid_fetch_assoc($req)) {
printf("%-40s %-10s %-6s %-20s\n",
$row["name"], $row["area"], $row["seats"], $row["address"]);
}
cubrid_close_request($req);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
name area seats address Panathinaiko Stadium 86300.00 50000 Athens, Greece Olympic Stadium 54700.00 13000 Athens, Greece Olympic Indoor Hall 34100.00 18800 Athens, Greece Olympic Hall 52400.00 21000 Athens, Greece Olympic Aquatic Centre 42500.00 11500 Athens, Greece Markopoulo Olympic Equestrian Centre 64000.00 15000 Markopoulo, Athens, Greece Faliro Coastal Zone Olympic Complex 34650.00 12171 Faliro, Athens, Greece Athens Olympic Stadium 120400.00 71030 Maroussi, Athens, Greece Ano Liossia 34000.00 12000 Ano Liosia, Athens, Greece
cubrid_fetch_field
(PECL CUBRID >= 8.3.1)
cubrid_fetch_field — Get column information from a result and return as an object
Opis
$result
[, int $field_offset = 0
] )This function returns an object with certain properties of the specific column. The properties of the object are:
-
name -
column name
-
table -
name of the table that the column belongs to
-
def -
default value of the column
-
max_length -
maximum length of the column
-
not_null -
1 if the column cannot be NULL
-
primary_key -
1 if the column is a primary key
-
unique_key -
1 if the column is an unique key
-
multiple_key -
1 if the column is a non-unique key
-
numeric -
1 if the column is numeric
-
blob -
1 if the column is a BLOB
-
type -
the type of the column
-
unsigned -
1 if the column is unsigned
-
zerofill -
1 if the column is zero-filled
Parametry
-
result -
resultcomes from a call to cubrid_execute() -
field_offset -
The numerical field offset. If the field offset is not specified, the next field (that was not yet retrieved by this function) is retrieved. The
field_offsetstarts at 0.
Zwracane wartości
Object with certain properties of the specific column, when process is successful.
FALSE on failure.
Przykłady
Przykład #1 cubrid_fetch_field() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = cubrid_execute($conn, "SELECT event_code,athlete_code,nation_code,game_date FROM game WHERE host_year=1988 and event_code=20001;");
var_dump(cubrid_fetch_row($req));
cubrid_field_seek($req, 1);
$field = cubrid_fetch_field($req);
printf("\n--- Field Properties ---\n");
printf("%-30s %s\n", "name:", $field->name);
printf("%-30s %s\n", "table:", $field->table);
printf("%-30s \"%s\"\n", "default value:", $field->def);
printf("%-30s %d\n", "max length:", $field->max_length);
printf("%-30s %d\n", "not null:", $field->not_null);
printf("%-30s %d\n", "primary key:", $field->primary_key);
printf("%-30s %d\n", "unique key:", $field->unique_key);
printf("%-30s %d\n", "multiple key:", $field->multiple_key);
printf("%-30s %d\n", "numeric:", $field->numeric);
printf("%-30s %d\n", "blob:", $field->blob);
printf("%-30s %s\n", "type:", $field->type);
printf("%-30s %d\n", "unsigned:", $field->unsigned);
printf("%-30s %d\n", "zerofill:", $field->zerofill);
cubrid_close_request($req);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
array(4) {
[0]=>
string(5) "20001"
[1]=>
string(5) "16681"
[2]=>
string(3) "KOR"
[3]=>
string(9) "1988-9-30"
}
--- Field Properties ---
name: athlete_code
table: game
default value: ""
max length: 0
not null: 1
primary key: 1
unique key: 1
multiple key: 0
numeric: 1
blob: 0
type: integer
unsigned: 0
zerofill: 0
cubrid_fetch_lengths
(PECL CUBRID >= 8.3.0)
cubrid_fetch_lengths — Return an array with the lengths of the values of each field from the current row
Opis
$result
)This function returns an numeric array with the lengths of the values of each field from the current row of the result set or it returns FALSE on failure.
Informacja:
If field data type is BLOB/CLOB, you should get its length by using cubrid_lob_size().
Zwracane wartości
An numeric array, when process is successful.
FALSE on failure.
Przykłady
Przykład #1 cubrid_fetch_lengths() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");
$row = cubrid_fetch_row($result);
print_r($row);
$lens = cubrid_fetch_lengths($result);
print_r($lens);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
Array
(
[0] => 2004
[1] => 20085
[2] => 15118
[3] => 30134
[4] => AUS
[5] => G
[6] => 2004-8-20
)
Array
(
[0] => 4
[1] => 5
[2] => 5
[3] => 5
[4] => 3
[5] => 1
[6] => 9
)
cubrid_fetch_object
(PECL CUBRID >= 8.3.0)
cubrid_fetch_object — Fetche the next row and returns it as an object
Opis
$result
[, string $class_name
[, array $params
]] )This function returns an object with the column names of the result set as properties. The values of these properties are extracted from the current row of the result.
Parametry
-
result -
resultcomes from a call to cubrid_execute() -
class_name -
The name of the class to instantiate. If not specified, a stdClass (stdClass is PHP's generic empty class that's used when casting other types to objects) object is returned.
-
params -
An optional array of parameters to pass to the constructor for
class_nameobjects.
Zwracane wartości
An object, when process is successful.
FALSE, when there are no more rows; NULL, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_fetch_object() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$res = cubrid_execute($conn, "SELECT * FROM code");
var_dump(cubrid_fetch_object($res));
class demodb_code {
public $s_name = null;
public $f_name = null;
public function toString() {
var_dump($this);
}
}
var_dump(cubrid_fetch_object($res, "demodb_code"));
class demodb_code_construct extends demodb_code {
public function __construct($s, $f) {
$this->s_name = $s;
$this->f_name = $f;
}
}
var_dump(cubrid_fetch_object($res, 'demodb_code_construct', array('s_name', 'f_name')));
var_dump(cubrid_fetch_object($res));
cubrid_close_request($res);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
object(stdClass)#1 (2) {
["s_name"]=>
string(1) "X"
["f_name"]=>
string(5) "Mixed"
}
object(demodb_code)#1 (2) {
["s_name"]=>
string(1) "W"
["f_name"]=>
string(5) "Woman"
}
object(demodb_code_construct)#1 (2) {
["s_name"]=>
string(6) "s_name"
["f_name"]=>
string(6) "f_name"
}
object(stdClass)#1 (2) {
["s_name"]=>
string(1) "B"
["f_name"]=>
string(6) "Bronze"
}
cubrid_fetch_row
(PECL CUBRID >= 8.3.0)
cubrid_fetch_row — Return a numerical array with the values of the current row
Opis
$result
)This function returns a numerical array with the values of the current row from the result set, starting from 0, and moves the internal data pointer ahead.
Zwracane wartości
A numerical array, when process is successful.
FALSE, when there are no more rows; NULL, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_fetch_row() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = cubrid_execute($conn, "SELECT name,area,seats,address FROM stadium WHERE nation_code='GRE' AND seats > 10000");
printf("%-40s %-10s %-6s %-20s\n", "name", "area", "seats", "address");
while ($row = cubrid_fetch_row($req)) {
printf("%-40s %-10s %-6s %-20s\n", $row[0], $row[1], $row[2], $row[3]);
}
cubrid_close_request($req);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
name area seats address Panathinaiko Stadium 86300.00 50000 Athens, Greece Olympic Stadium 54700.00 13000 Athens, Greece Olympic Indoor Hall 34100.00 18800 Athens, Greece Olympic Hall 52400.00 21000 Athens, Greece Olympic Aquatic Centre 42500.00 11500 Athens, Greece Markopoulo Olympic Equestrian Centre 64000.00 15000 Markopoulo, Athens, Greece Faliro Coastal Zone Olympic Complex 34650.00 12171 Faliro, Athens, Greece Athens Olympic Stadium 120400.00 71030 Maroussi, Athens, Greece Ano Liossia 34000.00 12000 Ano Liosia, Athens, Greece
cubrid_field_flags
(PECL CUBRID >= 8.3.0)
cubrid_field_flags — Return a string with the flags of the given field offset
Opis
$result
, int $field_offset
)
This function returns a string with the flags of the given field offset
separated by space. You can split the returned value using explode. The
possible flags could be: not_null,
primary_key, unique_key,
foreign_key, auto_increment,
shared, reverse_index,
reverse_unique and timestamp.
Parametry
-
result -
resultcomes from a call to cubrid_execute() -
field_offset -
The numerical field offset. The
field_offsetstarts at 0. Iffield_offsetdoes not exist, an error of levelE_WARNINGis also issued.
Zwracane wartości
A string with flags, when process is successful.
FALSE when invalid field_offset value.
-1 if SQL sentence is not SELECT.
Przykłady
Przykład #1 cubrid_field_flags() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");
$col_num = cubrid_num_cols($result);
printf("%-30s %s\n", "Field Name", "Field Flags");
for($i = 0; $i < $col_num; $i++) {
printf("%-30s %s\n", cubrid_field_name($result, $i), cubrid_field_flags($result, $i));
}
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
Field Name Field Flags host_year not_null primary_key unique_key event_code not_null primary_key unique_key foreign_key athlete_code not_null primary_key unique_key foreign_key stadium_code not_null nation_code medal game_date
cubrid_field_len
(PECL CUBRID >= 8.3.0)
cubrid_field_len — Get the maximum length of the specified field
Opis
$result
, int $field_offset
)This function returns the maximum length of the specified field on success, or it returns FALSE on failure.
Parametry
-
result -
resultcomes from a call to cubrid_execute() -
field_offset -
The numerical field offset. The
field_offsetstarts at 0. Iffield_offsetdoes not exist, an error of levelE_WARNINGis also issued.
Zwracane wartości
Maximum length, when process is successful.
FALSE on failure.
Przykłady
Przykład #1 cubrid_field_len() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");
$column_names = cubrid_column_names($result);
$column_types = cubrid_column_types($result);
printf("%-30s %-30s %-15s\n", "Column Names", "Column Types", "Column Maxlen");
for($i = 0, $size = count($column_names); $i < $size; $i++) {
$column_len = cubrid_field_len($result, $i);
printf("%-30s %-30s %-15s\n", $column_names[$i], $column_types[$i], $column_len);
}
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
Column Names Column Types Column Maxlen host_year integer 11 event_code integer 11 athlete_code integer 11 stadium_code integer 11 nation_code char(3) 3 medal char(1) 1 game_date date 10
cubrid_field_name
(PECL CUBRID >= 8.3.0)
cubrid_field_name — Return the name of the specified field index
Opis
$result
, int $field_offset
)This function returns the name of the specified field index on success or it returns FALSE on failure.
Parametry
-
result -
resultcomes from a call to cubrid_execute() -
field_offset -
The numerical field offset. The
field_offsetstarts at 0. Iffield_offsetdoes not exist, an error of levelE_WARNINGis also issued.
Zwracane wartości
Name of specified field index, on success.
FALSE on failure.
Przykłady
Przykład #1 cubrid_field_name() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");
$col_num = cubrid_num_cols($result);
printf("%-30s %s\n", "Field Name", "Field Flags");
for($i = 0; $i < $col_num; $i++) {
printf("%-30s %s\n", cubrid_field_name($result, $i), cubrid_field_flags($result, $i));
}
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
Field Name Field Flags host_year not_null primary_key unique_key event_code not_null primary_key unique_key foreign_key athlete_code not_null primary_key unique_key foreign_key stadium_code not_null nation_code medal game_date
cubrid_field_seek
(PECL CUBRID >= 8.3.0)
cubrid_field_seek — Move the result set cursor to the specified field offset
Opis
$result
[, int $field_offset = 0
] )This function moves the result set cursor to the specified field offset. This offset is used by cubrid_fetch_field() if it doesn't include a field offset. It returns TRUE on success or FALSE on failure.
Parametry
-
result -
resultcomes from a call to cubrid_execute() -
field_offset -
The numerical field offset. The
field_offsetstarts at 0. Iffield_offsetdoes not exist, an error of levelE_WARNINGis also issued.
Zwracane wartości
TRUE on success.
FALSE on failure.
Przykłady
Przykład #1 cubrid_field_seek() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = cubrid_execute($conn, "SELECT event_code,athlete_code,nation_code,game_date FROM game WHERE host_year=1988 and event_code=20001;");
var_dump(cubrid_fetch_row($req));
cubrid_field_seek($req, 1);
$field = cubrid_fetch_field($req);
printf("\n--- Field Properties ---\n");
printf("%-30s %s\n", "name:", $field->name);
printf("%-30s %s\n", "table:", $field->table);
printf("%-30s \"%s\"\n", "default value:", $field->def);
printf("%-30s %d\n", "max lenght:", $field->max_length);
printf("%-30s %d\n", "not null:", $field->not_null);
printf("%-30s %d\n", "unique key:", $field->unique_key);
printf("%-30s %d\n", "multiple key:", $field->multiple_key);
printf("%-30s %d\n", "numeric:", $field->numeric);
printf("%-30s %s\n", "type:", $field->type);
cubrid_close_request($req);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
array(4) {
[0]=>
string(5) "20001"
[1]=>
string(5) "16681"
[2]=>
string(3) "KOR"
[3]=>
string(9) "1988-9-30"
}
--- Field Properties ---
name: athlete_code
table: game
default value: ""
max lenght: 5
not null: 1
unique key: 1
multiple key: 0
numeric: 1
type: integer
cubrid_field_table
(PECL CUBRID >= 8.3.0)
cubrid_field_table — Return the name of the table of the specified field
Opis
$result
, int $field_offset
)This function returns the name of the table of the specified field. This is useful when using large select queries with JOINS.
Parametry
-
result -
Array type of the fetched result CUBRID_NUM, CUBRID_ASSOC, CUBRID_BOTH.
-
field_offset -
The numerical field offset. The
field_offsetstarts at 0. Iffield_offsetdoes not exist, an error of levelE_WARNINGis also issued.
Zwracane wartości
Name of the table of the specified field, on success.
FALSE when invalid field_offset value.
-1 if SQL sentence is not SELECT.
Przykłady
Przykład #1 cubrid_field_table() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$result = cubrid_execute($conn, "SELECT * FROM code");
$col_num = cubrid_num_cols($result);
printf("%-15s %-15s %s\n", "Field Table", "Field Name", "Field Type");
for($i = 0; $i < $col_num; $i++) {
printf("%-15s %-15s %s\n",
cubrid_field_table($result, $i), cubrid_field_name($result, $i), cubrid_field_type($result, $i));
}
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
Field Table Field Name Field Type code s_name char(1) code f_name varchar(6)
cubrid_field_type
(PECL CUBRID >= 8.3.0)
cubrid_field_type — Return the type of the column corresponding to the given field offset
Opis
$result
, int $field_offset
)This function returns the type of the column corresponding to the given field offset. The returned field type could be one of the following: "int", "real", "string", etc.
Parametry
-
result -
Array type of the fetched result CUBRID_NUM, CUBRID_ASSOC, CUBRID_BOTH.
-
field_offset -
The numerical field offset. The
field_offsetstarts at 0. Iffield_offsetdoes not exist, an error of levelE_WARNINGis also issued.
Zwracane wartości
Type of the column, on success.
FALSE when invalid field_offset value.
-1 if SQL sentence is not SELECT.
Przykłady
Przykład #1 cubrid_field_type() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$result = cubrid_execute($conn, "SELECT * FROM code");
$col_num = cubrid_num_cols($result);
printf("%-15s %-15s %s\n", "Field Table", "Field Name", "Field Type");
for($i = 0; $i < $col_num; $i++) {
printf("%-15s %-15s %s\n",
cubrid_field_table($result, $i), cubrid_field_name($result, $i), cubrid_field_type($result, $i));
}
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
Field Table Field Name Field Type code s_name char(1) code f_name varchar(6)
cubrid_list_dbs
(PECL CUBRID >= 8.3.0)
cubrid_list_dbs — Return an array with the list of all existing CUBRID databases
Opis
$conn_identifier
] )This function returns an array with the list of all existing Cubrid databases.
Parametry
-
conn_identifier -
The CUBRID connection.
Zwracane wartości
An numeric array with all existing Cubrid databases; on success.
FALSE on failure.
Przykłady
Przykład #1 cubrid_list_dbs() example
<?php
$conn = cubrid_connect("localhost", 33088, "demodb");
$db_list = cubrid_list_dbs($conn);
var_dump($db_list);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
array(1) {
[0]=>
string(6) "demodb"
}
cubrid_num_fields
(PECL CUBRID >= 8.3.0)
cubrid_num_fields — Return the number of columns in the result set
Opis
$result
)This function returns the number of columns in the result set, on success, or it returns FALSE on failure.
Zwracane wartości
Number of columns, on success.
-1 if SQL sentence is not SELECT.
FALSE when process is unsuccessful.
Przykłady
Przykład #1 cubrid_num_fields() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = cubrid_execute($conn, "SELECT * FROM code");
$row_num = cubrid_num_rows($req);
$col_num = cubrid_num_fields($req);
printf("Row Num: %d\nColumn Num: %d\n", $row_num, $col_num);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
Row Num: 6 Column Num: 2
cubrid_ping
(PECL CUBRID >= 8.3.1)
cubrid_ping — Ping a server connection or reconnect if there is no connection
Opis
$conn_identifier
] )Checks whether or not the connection to the server is working.
Parametry
-
conn_identifier -
The CUBRID connection identifier. If the connection identifier is not specified, the last connection opened by cubrid_connect() is assumed.
Zwracane wartości
Returns TRUE if the connection to the server CUBRID server is working, otherwise FALSE.
Przykłady
Przykład #1 cubrid_ping() example
<?php
set_time_limit(0);
$conn = cubrid_connect('localhost', 33000, 'demodb');
/* Assuming this query will take a long time */
$result = cubrid_query($sql);
if (!$result) {
echo 'Query #1 failed, exiting.';
exit;
}
/* Make sure the connection is still alive, if not, try to reconnect */
if (!cubrid_ping($conn)) {
echo 'Lost connection, exiting after query #1';
exit;
}
cubrid_free_result($result);
/* So the connection is still alive, let's run another query */
$result2 = cubrid_query($sql2);
?>
cubrid_query
(PECL CUBRID >= 8.3.1)
cubrid_query — Send a CUBRID query
Opis
$query
[, resource $conn_identifier
] )
cubrid_query() sends a unique query (multiple queries are not supported) to the
currently active database on the server that's associated with the specified conn_identifier.
Parametry
-
query -
An SQL query
Data inside the query should be properly escaped.
-
conn_identifier -
The CUBRID connection. If the connection identifier is not specified, the last connection opened by cubrid_connect() is assumed.
Zwracane wartości
For SELECT, SHOW, DESCRIBE, EXPLAIN and other statements returning resultset,
cubrid_query() returns a resource on success, or FALSE on error.
For other type of SQL statements, INSERT, UPDATE, DELETE, DROP, etc,
cubrid_query() returns TRUE on success or FALSE on error.
The returned result resource should be passed to cubrid_fetch_array(), and other functions for dealing with result tables, to access the returned data.
Use cubrid_num_rows() to find out how many rows were returned for a SELECT statement or cubrid_affected_rows() to find out how many rows were affected by a DELETE, INSERT, REPLACE, or UPDATE statement.
cubrid_query() will also fail and return FALSE
if the user does not have permission to access the table(s) referenced by the query.
Przykłady
Przykład #1 Invalid Query
The following query is syntactically invalid, so cubrid_query() fails and returns FALSE.
<?php
$conn = cubrid_connect('localhost', 33000, 'foo');
$result = cubrid_query('SELECT * WHERE 1=1');
if (!$result) {
die('Invalid query: ' . cubrid_error());
}
?>
Przykład #2 Valid Query
The following query is valid, so cubrid_query() returns a resource.
<?php
// This could be supplied by a user, for example
$firstname = 'fred';
$lastname = 'fox';
$conn = cubrid_connect('localhost', 33000, 'foo');
// Formulate Query
// This is the best way to perform an SQL query
// For more examples, see cubrid_real_escape_string()
$query = sprintf("SELECT firstname, lastname, address, age FROM friends WHERE firstname='%s' AND lastname='%s'",
cubrid_real_escape_string($firstname),
cubrid_real_escape_string($lastname));
// Perform Query
$result = cubrid_query($query);
// Check result
// This shows the actual query sent to CUBRID, and the error. Useful for debugging.
if (!$result) {
$message = 'Invalid query: ' . cubrid_error() . "\n";
$message .= 'Whole query: ' . $query;
die($message);
}
// Use result
// Attempting to print $result won't allow access to information in the resource
// One of the cubrid result functions must be used
// See also cubrid_result(), cubrid_fetch_array(), cubrid_fetch_row(), etc.
while ($row = cubrid_fetch_assoc($result)) {
echo $row['firstname'];
echo $row['lastname'];
echo $row['address'];
echo $row['age'];
}
// Free the resources associated with the result set
// This is done automatically at the end of the script
cubrid_free_result($result);
?>
Zobacz też:
- cubrid_connect() - Open a connection to a CUBRID Server
- cubrid_error() - Get the error message
- cubrid_real_escape_string() - Escape special characters in a string for use in an SQL statement
- cubrid_result() - Return the value of a specific field in a specific row
- cubrid_fetch_assoc() - Return the associative array that corresponds to the fetched row
- cubrid_unbuffered_query() - Perform a query without fetching the results into memory
cubrid_real_escape_string
(PECL CUBRID >= 8.3.0)
cubrid_real_escape_string — Escape special characters in a string for use in an SQL statement
Opis
$unescaped_string
[, resource $conn_identifier
] )
This function returns the escaped string version of the given string. It
will escape the following characters: '.
In general, single quotations are used to enclose character string. Double
quotations may be used as well depending on the value of ansi_quotes,
which is a parameter related to SQL statement. If the ansi_quotes value is
set to no, character string enclosed by double quotations is handled as
character string, not as an identifier. The default value is yes.
If you want to include a single quote as part of a character string, enter
two single quotes in a row.
Parametry
-
unescaped_string -
The string that is to be escaped.
-
conn_identifier -
The CUBRID connection. If the connection identifier is not specified, the last connection opened by cubrid_connect() is assumed.
Zwracane wartości
Escaped string version of the given string, on success.
FALSE on failure.
Przykłady
Przykład #1 cubrid_real_escape_string() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$unescaped_str = ' !"#$%&\'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~';
$escaped_str = cubrid_real_escape_string($unescaped_str);
$len = strlen($unescaped_str);
@cubrid_execute($conn, "DROP TABLE cubrid_test");
cubrid_execute($conn, "CREATE TABLE cubrid_test (t char($len))");
cubrid_execute($conn, "INSERT INTO cubrid_test (t) VALUES('$escaped_str')");
$req = cubrid_execute($conn, "SELECT * FROM cubrid_test");
$row = cubrid_fetch_assoc($req);
var_dump($row);
cubrid_close_request($req);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
array(1) {
["t"]=>
string(95) " !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~"
}
cubrid_result
(PECL CUBRID >= 8.3.0)
cubrid_result — Return the value of a specific field in a specific row
Opis
This function returns the value of a specific field in a specific row from a result set.
Parametry
-
result -
resultcomes from a call to cubrid_execute() -
row -
The row number from the result that is being retrieved. Row numbers start at 0.
-
field -
The name or offset of the
fieldbeing retrieved. It can be the field's offset, the field's name, or the field's table dot field name (tablename.fieldname). If the column name has been aliased ('select foo as bar from...'), use the alias instead of the column name. If undefined, the first field is retrieved.
Zwracane wartości
Value of a specific field, on success (NULL if value if null).
FALSE on failure.
Przykłady
Przykład #1 cubrid_result() example
<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = cubrid_execute($conn, "SELECT * FROM code");
$result = cubrid_result($req, 0);
var_dump($result);
$result = cubrid_result($req, 0, 1);
var_dump($result);
$result = cubrid_result($req, 5, "f_name");
var_dump($result);
cubrid_close_request($req);
cubrid_disconnect($conn);
?>
Powyższy przykład wyświetli:
string(1) "X" string(5) "Mixed" string(4) "Gold"
cubrid_unbuffered_query
(PECL CUBRID >= 8.3.0)
cubrid_unbuffered_query — Perform a query without fetching the results into memory
Opis
$query
[, resource $conn_identifier
] )This function performs a query without waiting for that all query results have been complete. It will return when the results are being generated.
Parametry
-
query -
A SQL query.
-
conn_identifier -
The CUBRID connection. If the connection identifier is not specified, the last connection opened by cubrid_connect() is assumed.
Zwracane wartości
For SELECT, SHOW, DESCRIBE or EXPLAIN statements returns a connection identifier resource on success.
For other type of SQL statements, UPDATE, DELETE, DROP, etc, returns TRUE on success.
FALSE on failure.
Notatki
Informacja:
The benefits of cubrid_unbuffered_query() come at a cost: you cannot use cubrid_num_rows() and cubrid_data_seek() on a result set returned from cubrid_unbuffered_query().
Przykłady
Przykład #1 cubrid_unbuffered_query() example
<?php
$link = cubrid_connect("localhost", 30000, "demodb2", "dba", "");
if (!$link)
{
die('Could not connect.');
}
$query = "select * from code";
$result = cubrid_unbuffered_query($query, $link);
while ($row = cubrid_fetch($result))
{
var_dump($row);
}
cubrid_close_request($result);
cubrid_disconnect($link);
?>
Spis treści
- cubrid_affected_rows — Return the number of rows affected by the last SQL statement
- cubrid_client_encoding — Return the current CUBRID connection charset
- cubrid_close — Close CUBRID connection
- cubrid_data_seek — Move the internal row pointer of the CUBRID result
- cubrid_db_name — Get db name from results of cubrid_list_dbs
- cubrid_errno — Return the numerical value of the error message from previous CUBRID operation
- cubrid_error — Get the error message
- cubrid_fetch_array — Fetch a result row as an associative array, a numeric array, or both
- cubrid_fetch_assoc — Return the associative array that corresponds to the fetched row
- cubrid_fetch_field — Get column information from a result and return as an object
- cubrid_fetch_lengths — Return an array with the lengths of the values of each field from the current row
- cubrid_fetch_object — Fetche the next row and returns it as an object
- cubrid_fetch_row — Return a numerical array with the values of the current row
- cubrid_field_flags — Return a string with the flags of the given field offset
- cubrid_field_len — Get the maximum length of the specified field
- cubrid_field_name — Return the name of the specified field index
- cubrid_field_seek — Move the result set cursor to the specified field offset
- cubrid_field_table — Return the name of the table of the specified field
- cubrid_field_type — Return the type of the column corresponding to the given field offset
- cubrid_list_dbs — Return an array with the list of all existing CUBRID databases
- cubrid_num_fields — Return the number of columns in the result set
- cubrid_ping — Ping a server connection or reconnect if there is no connection
- cubrid_query — Send a CUBRID query
- cubrid_real_escape_string — Escape special characters in a string for use in an SQL statement
- cubrid_result — Return the value of a specific field in a specific row
- cubrid_unbuffered_query — Perform a query without fetching the results into memory
CUBRID Obsolete Aliases and Functions
cubrid_load_from_glo
(PECL CUBRID >= 8.3.0)
cubrid_load_from_glo — Read data from a GLO instance and save it in a file
Opis
$conn_identifier
, string $oid
, string $file_name
)The cubrid_load_from_glo() function is used to read a data from a glo instance, and saves it in a designated file.
Parametry
-
conn_identifier -
Connection identifier.
-
oid -
Oid of the glo instance that you want to read the data from.
-
file_name -
Name of the file where you want to save the data in.
Zwracane wartości
TRUE, when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_load_from_glo() example
<?php
$req = cubrid_execute ($con, "select image from person where id=1");
if ($req) {
list ($oid) = cubrid_fetch($req);
cubrid_close_request($req);
$res = cubrid_load_from_glo ($con, $oid, "output.jpg");
if ($res) {
echo "image changed successfully";
}
}
?>
Notatki
Informacja:
Dla zachowania zgodności z poprzednimi wersjami PHP możliwe jest używanie aliasów: cubrid_load_from_glo()
Informacja:
This function is removed from CUBRID 3.1.
Zobacz też:
- cubrid_new_glo() - Create a glo instance
- cubrid_save_to_glo() - Save requested file in a GLO instance
- cubrid_send_glo() - Read data from glo and send it to std output
cubrid_new_glo
(PECL CUBRID >= 8.3.0)
cubrid_new_glo — Create a glo instance
Opis
$conn_identifier
, string $class_name
, string $file_name
)
The cubrid_new_glo() function is used to create a glo instance in the requested class (glo class). The glo created is a LO type, and is stored in the file_name file.
Parametry
-
conn_identifier -
Connection identifier.
-
class_name -
Name of the class that you want to create a glo in.
-
file_name -
The file name that you want to save in the newly created glo.
Zwracane wartości
Oid of the instance created, when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_new_glo() example
<?php
$oid = cubrid_new_glo ($con, "glo", "input.jpg");
if ($oid){
// the type of column "image" is "object"
$req = cubrid_execute ($con, "insert into person(image) values($oid)");
if ($req) {
echo "image inserted successfully";
cubrid_close_request ($req);
cubrid_commit($con);
}
}
?>
Notatki
Informacja:
Dla zachowania zgodności z poprzednimi wersjami PHP możliwe jest używanie aliasów: cubrid_new_glo()
Informacja:
This function is removed from CUBRID 3.1.
Zobacz też:
- cubrid_save_to_glo() - Save requested file in a GLO instance
- cubrid_load_from_glo() - Read data from a GLO instance and save it in a file
- cubrid_send_glo() - Read data from glo and send it to std output
cubrid_save_to_glo
(PECL CUBRID >= 8.3.0)
cubrid_save_to_glo — Save requested file in a GLO instance
Opis
$conn_identifier
, string $oid
, string $file_name
)The cubrid_save_to_glo() function is used to save requested file in a glo instance.
Parametry
-
conn_identifier -
Connection identifier.
-
oid -
Oid of the glo instance that you want to save a file in.
-
file_name -
The name of the file that you want to save.
Zwracane wartości
TRUE, when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_save_to_glo() example
<?php
$req = cubrid_execute ($con, "select image from person where id=1");
if ($req) {
list ($oid) = cubrid_fetch($req);
cubrid_close_request($req);
$res = cubrid_save_to_glo ($con, $oid, "input.jpg");
if ($res) {
echo "image changed successfully";
}
}
?>
Notatki
Informacja:
Dla zachowania zgodności z poprzednimi wersjami PHP możliwe jest używanie aliasów: cubrid_save_to_glo()
Informacja:
This function is removed from CUBRID 3.1.
Zobacz też:
- cubrid_new_glo() - Create a glo instance
- cubrid_load_from_glo() - Read data from a GLO instance and save it in a file
- cubrid_send_glo() - Read data from glo and send it to std output
cubrid_send_glo
(PECL CUBRID >= 8.3.0)
cubrid_send_glo — Read data from glo and send it to std output
Opis
$conn_identifier
, string $oid
)The cubrid_send_glo() function is used to read data from glo instance and sends it to the PHP standard output.
Parametry
-
conn_identifier -
Connection identifier.
-
oid -
Oid of the glo instance that you want to read data from.
Zwracane wartości
TRUE, when process is successful.
FALSE, when process is unsuccessful.
Przykłady
Przykład #1 cubrid_send_glo() example
<?php
$req = cubrid_execute ($con, "select image from person where id =1");
if ($req) {
list ($oid) = cubrid_fetch($req);
cubrid_close_request($req);
Header ("Content-type: image/jpeg");
cubrid_send_glo ($con, $oid);
}
?>
Notatki
Informacja:
Dla zachowania zgodności z poprzednimi wersjami PHP możliwe jest używanie aliasów: cubrid_send_glo()
Informacja:
This function is removed from CUBRID 3.1.
Zobacz też:
- cubrid_new_glo() - Create a glo instance
- cubrid_save_to_glo() - Save requested file in a GLO instance
- cubrid_load_from_glo() - Read data from a GLO instance and save it in a file
Spis treści
- cubrid_load_from_glo — Read data from a GLO instance and save it in a file
- cubrid_new_glo — Create a glo instance
- cubrid_save_to_glo — Save requested file in a GLO instance
- cubrid_send_glo — Read data from glo and send it to std output
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Przykłady
- CUBRID Funkcje
- cubrid_bind — Bind variables to a prepared statement as parameters
- cubrid_close_prepare — Close the request handle
- cubrid_close_request — Close the request handle
- cubrid_col_get — Get contents of collection type column using OID
- cubrid_col_size — Get the number of elements in collection type column using OID
- cubrid_column_names — Get the column names in result
- cubrid_column_types — Get column types in result
- cubrid_commit — Commit a transaction
- cubrid_connect_with_url — Establish the environment for connecting to CUBRID server
- cubrid_connect — Open a connection to a CUBRID Server
- cubrid_current_oid — Get OID of the current cursor location
- cubrid_disconnect — Close a database connection
- cubrid_drop — Delete an instance using OID
- cubrid_error_code_facility — Get the facility code of error
- cubrid_error_code — Get error code for the most recent function call
- cubrid_error_msg — Get last error message for the most recent function call
- cubrid_execute — Execute a prepared SQL statement
- cubrid_fetch — Fetch the next row from a result set
- cubrid_free_result — Free the memory occupied by the result data
- cubrid_get_autocommit — Get auto-commit mode of the connection
- cubrid_get_charset — Return the current CUBRID connection charset
- cubrid_get_class_name — Get the class name using OID
- cubrid_get_client_info — Return the client library version
- cubrid_get_db_parameter — Returns the CUBRID database parameters
- cubrid_get_query_timeout — Get the query timeout value of the request
- cubrid_get_server_info — Return the CUBRID server version
- cubrid_get — Get a column using OID
- cubrid_insert_id — Return the ID generated for the lastest updated AUTO_INCREMENT column
- cubrid_is_instance — Check whether the instance pointed by OID exists
- cubrid_lob_close — Close BLOB/CLOB data
- cubrid_lob_export — Export BLOB/CLOB data to file
- cubrid_lob_get — Get BLOB/CLOB data
- cubrid_lob_send — Read BLOB/CLOB data and send straight to browser
- cubrid_lob_size — Get BLOB/CLOB data size
- cubrid_lock_read — Set a read lock on the given OID
- cubrid_lock_write — Set a write lock on the given OID
- cubrid_move_cursor — Move the cursor in the result
- cubrid_next_result — Get result of next query when executing multiple SQL statements
- cubrid_num_cols — Return the number of columns in the result set
- cubrid_num_rows — Get the number of rows in the result set
- cubrid_pconnect_with_url — Open a persistent connection to CUBRID server
- cubrid_pconnect — Open a persistent connection to a CUBRID server
- cubrid_prepare — Prepare an SQL statement for execution
- cubrid_put — Update a column using OID
- cubrid_rollback — Roll back a transaction
- cubrid_schema — Get the requested schema information
- cubrid_seq_drop — Delete an element from sequence type column using OID
- cubrid_seq_insert — Insert an element to a sequence type column using OID
- cubrid_seq_put — Update the element value of sequence type column using OID
- cubrid_set_add — Insert a single element to set type column using OID
- cubrid_set_autocommit — Set autocommit mode of the connection
- cubrid_set_db_parameter — Sets the CUBRID database parameters
- cubrid_set_drop — Delete an element from set type column using OID
- cubrid_set_query_timeout — Set the timeout time of query execution
- cubrid_version — Get the CUBRID PHP module's version
- CUBRID MySQL Compatibility Functions
- cubrid_affected_rows — Return the number of rows affected by the last SQL statement
- cubrid_client_encoding — Return the current CUBRID connection charset
- cubrid_close — Close CUBRID connection
- cubrid_data_seek — Move the internal row pointer of the CUBRID result
- cubrid_db_name — Get db name from results of cubrid_list_dbs
- cubrid_errno — Return the numerical value of the error message from previous CUBRID operation
- cubrid_error — Get the error message
- cubrid_fetch_array — Fetch a result row as an associative array, a numeric array, or both
- cubrid_fetch_assoc — Return the associative array that corresponds to the fetched row
- cubrid_fetch_field — Get column information from a result and return as an object
- cubrid_fetch_lengths — Return an array with the lengths of the values of each field from the current row
- cubrid_fetch_object — Fetche the next row and returns it as an object
- cubrid_fetch_row — Return a numerical array with the values of the current row
- cubrid_field_flags — Return a string with the flags of the given field offset
- cubrid_field_len — Get the maximum length of the specified field
- cubrid_field_name — Return the name of the specified field index
- cubrid_field_seek — Move the result set cursor to the specified field offset
- cubrid_field_table — Return the name of the table of the specified field
- cubrid_field_type — Return the type of the column corresponding to the given field offset
- cubrid_list_dbs — Return an array with the list of all existing CUBRID databases
- cubrid_num_fields — Return the number of columns in the result set
- cubrid_ping — Ping a server connection or reconnect if there is no connection
- cubrid_query — Send a CUBRID query
- cubrid_real_escape_string — Escape special characters in a string for use in an SQL statement
- cubrid_result — Return the value of a specific field in a specific row
- cubrid_unbuffered_query — Perform a query without fetching the results into memory
- CUBRID Obsolete Aliases and Functions
- cubrid_load_from_glo — Read data from a GLO instance and save it in a file
- cubrid_new_glo — Create a glo instance
- cubrid_save_to_glo — Save requested file in a GLO instance
- cubrid_send_glo — Read data from glo and send it to std output
DB++
Wstęp
db++, made by the German company » Concept asa, is a relational database system with high performance and low memory and disk usage in mind. While providing SQL as an additional language interface, it is not really an SQL database in the first place but provides its own AQL query language which is much more influenced by the relational algebra than SQL is.
Concept asa always had an interest in supporting open source languages, db++ has had Perl and Tcl call interfaces for years now and uses Tcl as its internal stored procedure language.
Ten moduł jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie tych funkcji, ich nazw, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tego modułu na własne ryzyko.
Instalacja/Konfiguracja
Spis treści
Wymagania
This extension relies on external client libraries so you have to have a db++ client installed on the system you want to use this extension on.
» Concept asa provides » db++ Demo versions and » documentation for Linux, some other Unix versions. There is also a Windows version of db++, but this extension doesn't support it (yet).
Instalacja
In order to build this extension yourself you need the db++ client libraries and header files to be installed on your system (these are included in the db++ installation archives by default). You have to run configure with option --with-dbplus to build this extension.
configure looks for the client libraries and header files under the default paths /usr/dbplus, /usr/local/dbplus and /opt/dblus. If you have installed db++ in a different place you have add the installation path to the configure option like this: --with-dbplus=/your/installation/path .
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
dbplus_relation
Most db++ functions operate on or return
dbplus_relation resources. A
dbplus_relation is a handle to a stored
relation or a relation generated as the result of a query.
Stałe predefiniowane
Spis treści
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
db++ error codes
| PHP Constant | db++ constant | meaning |
|---|---|---|
DBPLUS_ERR_NOERR
(integer)
|
ERR_NOERR | Null error condition |
DBPLUS_ERR_DUPLICATE
(integer)
|
ERR_DUPLICATE | Tried to insert a duplicate tuple |
DBPLUS_ERR_EOSCAN
(integer)
|
ERR_EOSCAN | End of scan from rget() |
DBPLUS_ERR_EMPTY
(integer)
|
ERR_EMPTY | Relation is empty (server) |
DBPLUS_ERR_CLOSE
(integer)
|
ERR_CLOSE | The server can't close |
DBPLUS_ERR_WLOCKED
(integer)
|
ERR_WLOCKED | The record is write locked |
DBPLUS_ERR_LOCKED
(integer)
|
ERR_LOCKED | Relation was already locked |
DBPLUS_ERR_NOLOCK
(integer)
|
ERR_NOLOCK | Relation cannot be locked |
DBPLUS_ERR_READ
(integer)
|
ERR_READ | Read error on relation |
DBPLUS_ERR_WRITE
(integer)
|
ERR_WRITE | Write error on relation |
DBPLUS_ERR_CREATE
(integer)
|
ERR_CREATE | Create() system call failed |
DBPLUS_ERR_LSEEK
(integer)
|
ERR_LSEEK | Lseek() system call failed |
DBPLUS_ERR_LENGTH
(integer)
|
ERR_LENGTH | Tuple exceeds maximum length |
DBPLUS_ERR_OPEN
(integer)
|
ERR_OPEN | Open() system call failed |
DBPLUS_ERR_WOPEN
(integer)
|
ERR_WOPEN | Relation already opened for writing |
DBPLUS_ERR_MAGIC
(integer)
|
ERR_MAGIC | File is not a relation |
DBPLUS_ERR_VERSION
(integer)
|
ERR_VERSION | File is a very old relation |
DBPLUS_ERR_PGSIZE
(integer)
|
ERR_PGSIZE | Relation uses a different page size |
DBPLUS_ERR_CRC
(integer)
|
ERR_CRC | Invalid crc in the superpage |
DBPLUS_ERR_PIPE
(integer)
|
ERR_PIPE | Piped relation requires lseek() |
DBPLUS_ERR_NIDX
(integer)
|
ERR_NIDX | Too many secondary indices |
DBPLUS_ERR_MALLOC
(integer)
|
ERR_MALLOC | Malloc() call failed |
DBPLUS_ERR_NUSERS
(integer)
|
ERR_NUSERS | Error use of max users |
DBPLUS_ERR_PREEXIT
(integer)
|
ERR_PREEXIT | Caused by invalid usage |
DBPLUS_ERR_ONTRAP
(integer)
|
ERR_ONTRAP | Caused by a signal |
DBPLUS_ERR_PREPROC
(integer)
|
ERR_PREPROC | Error in the preprocessor |
DBPLUS_ERR_DBPARSE
(integer)
|
ERR_DBPARSE | Error in the parser |
DBPLUS_ERR_DBRUNERR
(integer)
|
ERR_DBRUNERR | Run error in db |
DBPLUS_ERR_DBPREEXIT
(integer)
|
ERR_DBPREEXIT | Exit condition caused by prexit() * procedure |
DBPLUS_ERR_WAIT
(integer)
|
ERR_WAIT | Wait a little (Simple only) |
DBPLUS_ERR_CORRUPT_TUPLE
(integer)
|
ERR_CORRUPT_TUPLE | A client sent a corrupt tuple |
DBPLUS_ERR_WARNING0
(integer)
|
ERR_WARNING0 | The Simple routines encountered a non fatal error which was corrected |
DBPLUS_ERR_PANIC
(integer)
|
ERR_PANIC | The server should not really die but after a disaster send ERR_PANIC to all its clients |
DBPLUS_ERR_FIFO
(integer)
|
ERR_FIFO | Can't create a fifo |
DBPLUS_ERR_PERM
(integer)
|
ERR_PERM | Permission denied |
DBPLUS_ERR_TCL
(integer)
|
ERR_TCL | TCL_error |
DBPLUS_ERR_RESTRICTED
(integer)
|
ERR_RESTRICTED | Only two users |
DBPLUS_ERR_USER
(integer)
|
ERR_USER | An error in the use of the library by an application programmer |
DBPLUS_ERR_UNKNOWN
(integer)
|
ERR_UNKNOWN |
DB++ Funkcje
dbplus_add
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_add — Add a tuple to a relation
Opis
$relation
, array $tuple
)
Adds a tuple to a relation.
Parametry
-
relation -
-
tuple -
An array of attribute/value pairs to be inserted into the given
relation.After successful execution this array will contain the complete data of the newly created tuple, including all implicitly set domain fields like sequences.
Zwracane wartości
The function will return DBPLUS_ERR_NOERR on success
or a db++ error code on failure.
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_aql
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_aql — Perform AQL query
Opis
$query
[, string $server
[, string $dbpath
]] )
Executes an AQL query on the given
server and dbpath.
Parametry
-
query -
The AQL query to be executed. Further information on the AQL (Algebraic Query Language) is provided in the original db++ manual.
-
server -
-
dbpath -
Zwracane wartości
Returns a relation handle on success. The result data may be fetched from this relation by calling dbplus_next() and dbplus_curr(). Other relation access functions will not work on a result relation.
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_chdir
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_chdir — Get/Set database virtual current directory
Opis
$newdir
] )Changes the virtual current directory where relation files will be looked for by dbplus_open().
Parametry
-
newdir -
The new directory for relation files. You can omit this parameter to query the current working directory.
Zwracane wartości
Returns the absolute path of the current directory.
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_close
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_close — Close a relation
Opis
Closes a relation previously opened by dbplus_open().
Zwracane wartości
Returns TRUE on success or DBPLUS_ERR_UNKNOWN on
failure.
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_curr
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_curr — Get current tuple from relation
Opis
$relation
, array &$tuple
)
Reads the data for the current tuple for the given
relation.
Parametry
-
relation -
A relation opened by dbplus_open().
-
tuple -
The data will be passed back in this parameter, as an associative array.
Zwracane wartości
The function will return zero (aka. DBPLUS_ERR_NOERR) on success
or a db++ error code on failure.
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Zobacz też:
- dbplus_first() - Get first tuple from relation
- dbplus_prev() - Get previous tuple from relation
- dbplus_next() - Get next tuple from relation
- dbplus_last() - Get last tuple from relation
- dbplus_errcode() - Get error string for given errorcode or last error
dbplus_errcode
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_errcode — Get error string for given errorcode or last error
Opis
$errno
] )Returns a clear error string for the given error code.
Parametry
-
errno -
The error code. If not provided, the result code of the last db++ operation is assumed.
Zwracane wartości
Returns the error message.
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_errno
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_errno — Get error code for last operation
Opis
Returns the error code returned by the last db++ operation.
Zwracane wartości
Returns the error code, as an integer.
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_find
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_find — Set a constraint on a relation
Opis
Places a constraint on the given relation.
Further calls to functions like dbplus_curr() or dbplus_next() will only return tuples matching the given constraints.
Parametry
-
relation -
A relation opened by dbplus_open().
-
constraints -
Constraints are triplets of strings containing of a domain name, a comparison operator and a comparison value. The
constraintsparameter array may consist of a collection of string arrays, each of which contains a domain, an operator and a value, or of a single string array containing a multiple of three elements.The comparison operator may be one of the following strings: '==', '>', '>=', '<', '<=', '!=', '~' for a regular expression match and 'BAND' or 'BOR' for bitwise operations.
-
tuple -
Zwracane wartości
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_first
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_first — Get first tuple from relation
Opis
$relation
, array &$tuple
)
Reads the data for the first tuple for the given
relation, makes it the current tuple and pass it
back as an associative array in tuple.
Zwracane wartości
Returns DBPLUS_ERR_NOERR on success or a db++ error
code on failure.
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Zobacz też:
- dbplus_curr() - Get current tuple from relation
- dbplus_prev() - Get previous tuple from relation
- dbplus_next() - Get next tuple from relation
- dbplus_last() - Get last tuple from relation
- dbplus_errcode() - Get error string for given errorcode or last error
dbplus_flush
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_flush — Flush all changes made on a relation
Opis
$relation
)
Writes all changes applied to relation since the
last flush to disk.
Zwracane wartości
Returns DBPLUS_ERR_NOERR on success or a db++ error
code on failure.
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_freealllocks
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_freealllocks — Free all locks held by this client
Opis
Frees all tuple locks held by this client.
Zwracane wartości
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Zobacz też:
- dbplus_getlock() - Get a write lock on a tuple
- dbplus_freelock() - Release write lock on tuple
- dbplus_freerlocks() - Free all tuple locks on given relation
dbplus_freelock
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_freelock — Release write lock on tuple
Opis
$relation
, string $tuple
)
Releases a write lock on the given tuple previously
obtained by dbplus_getlock().
Zwracane wartości
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Zobacz też:
- dbplus_getlock() - Get a write lock on a tuple
- dbplus_freerlocks() - Free all tuple locks on given relation
- dbplus_freealllocks() - Free all locks held by this client
dbplus_freerlocks
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_freerlocks — Free all tuple locks on given relation
Opis
$relation
)
Frees all tuple locks held on the given relation.
Zwracane wartości
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Zobacz też:
- dbplus_getlock() - Get a write lock on a tuple
- dbplus_freelock() - Release write lock on tuple
- dbplus_freealllocks() - Free all locks held by this client
dbplus_getlock
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_getlock — Get a write lock on a tuple
Opis
$relation
, string $tuple
)
Requests a write lock on the specified tuple.
Zwracane wartości
Returns zero on success or a non-zero error code, especially
DBPLUS_ERR_WLOCKED on failure.
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Zobacz też:
- dbplus_freelock() - Release write lock on tuple
- dbplus_freerlocks() - Free all tuple locks on given relation
- dbplus_freealllocks() - Free all locks held by this client
dbplus_getunique
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_getunique — Get an id number unique to a relation
Opis
$relation
, int $uniqueid
)
Obtains a number guaranteed to be unique for the given
relation and will pass it back in the variable
given as uniqueid.
Zwracane wartości
Returns DBPLUS_ERR_NOERR on success or a db++ error
code on failure.
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_info
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_info — Get information about a relation
Opis
$relation
, string $key
, array &$result
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_last
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_last — Get last tuple from relation
Opis
$relation
, array &$tuple
)
Reads the data for the last tuple for the given
relation, makes it the current tuple and pass it
back as an associative array in tuple.
Zwracane wartości
Returns DBPLUS_ERR_NOERR on success or a db++ error
code on failure.
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Zobacz też:
- dbplus_first() - Get first tuple from relation
- dbplus_curr() - Get current tuple from relation
- dbplus_prev() - Get previous tuple from relation
- dbplus_next() - Get next tuple from relation
dbplus_lockrel
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_lockrel — Request write lock on relation
Opis
$relation
)
Requests a write lock on the given relation.
Other clients may still query the relation, but can't alter it while it is locked.
Zwracane wartości
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_next
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_next — Get next tuple from relation
Opis
$relation
, array &$tuple
)
Reads the data for the next tuple for the given
relation, makes it the current tuple and will pass
it back as an associative array in tuple.
Zwracane wartości
Returns DBPLUS_ERR_NOERR on success or a db++ error
code on failure.
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Zobacz też:
- dbplus_first() - Get first tuple from relation
- dbplus_curr() - Get current tuple from relation
- dbplus_prev() - Get previous tuple from relation
- dbplus_last() - Get last tuple from relation
dbplus_open
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_open — Open relation file
Opis
$name
)Opens the given relation file.
Parametry
-
name -
Can be either a file name or a relative or absolute path name. This will be mapped in any case to an absolute relation file path on a specific host machine and server.
Zwracane wartości
On success a relation file resource (cursor) is returned which must be used in any subsequent commands referencing the relation. Failure leads to a zero return value, the actual error code may be asked for by calling dbplus_errno().
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_prev
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_prev — Get previous tuple from relation
Opis
$relation
, array &$tuple
)
Reads the data for the previous tuple for the given
relation, makes it the current tuple and will pass
it back as an associative array in tuple.
Zwracane wartości
Returns DBPLUS_ERR_NOERR on success or a db++ error
code on failure.
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Zobacz też:
- dbplus_first() - Get first tuple from relation
- dbplus_curr() - Get current tuple from relation
- dbplus_next() - Get next tuple from relation
- dbplus_last() - Get last tuple from relation
dbplus_rchperm
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_rchperm — Change relation permissions
Opis
$relation
, int $mask
, string $user
, string $group
)
Changes access permissions as specified by mask,
user and group. The
values for these are operating system specific.
Zwracane wartości
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_rcreate
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_rcreate — Creates a new DB++ relation
Opis
Creates a new relation. Any existing relation sharing the same
name will be overwritten if the relation is
currently not in use and overwrite is set to TRUE.
Parametry
-
name -
-
domlist -
A combination of domains. May be passed as a single domain name string or as an array of domain names.
This parameter should contain the domain specification for the new relation within an array of domain description strings. A domain description string consists of a domain name unique to this relation, a slash and a type specification character. See the db++ documentation, especially the dbcreate(1) manpage, for a description of available type specifiers and their meanings.
Informacja:
This function will also accept a string with space delimited domain description strings, but it is recommended to use an array
-
overwrite -
Zwracane wartości
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_rcrtexact
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_rcrtexact — Creates an exact but empty copy of a relation including indices
Opis
dbplus_rcrtexact() will create an exact but
empty copy of the given relation under a
new name.
Parametry
-
name -
-
relation -
The copied relation, opened by dbplus_open().
-
overwrite -
An existing relation by the same
namewill only be overwritten if this parameter is set toTRUEand no other process is currently using the relation.
Zwracane wartości
Returns resource on success or DBPLUS_ERR_UNKNOWN on
failure.
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_rcrtlike
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_rcrtlike — Creates an empty copy of a relation with default indices
Opis
dbplus_rcrtexact() will create an empty copy
of the given relation under a new
name, but with default indices.
Parametry
-
name -
-
relation -
The copied relation, opened by dbplus_open().
-
overwrite -
An existing relation by the same
namewill only be overwritten if this parameter is set toTRUEand no other process is currently using the relation.
Zwracane wartości
Returns resource on success or DBPLUS_ERR_UNKNOWN on
failure.
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_resolve
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_resolve — Resolve host information for relation
Opis
$relation_name
)
dbplus_resolve() will try to resolve the given
relation_name and find out internal server
id, real hostname and the database path on this host.
Parametry
-
relation_name -
The relation name.
Zwracane wartości
Returns an array containing these values under the keys
sid, host and
host_path or FALSE on error.
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_restorepos
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_restorepos — Restore position
Opis
$relation
, array $tuple
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_rkeys
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_rkeys — Specify new primary key for a relation
Opis
dbplus_rkeys() will replace the current
primary key for relation with the
combination of domains specified by domlist.
Parametry
-
relation -
A relation opened by dbplus_open().
-
domlist -
A combination of domains. May be passed as a single domain name string or as an array of domain names.
Zwracane wartości
Returns resource on success or DBPLUS_ERR_UNKNOWN on
failure.
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_ropen
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_ropen — Open relation file local
Opis
$name
)
dbplus_ropen() will open the relation
file locally for quick access without any
client/server overhead. Access is read only and only
dbplus_curr() and
dbplus_next() may be applied to the returned
relation.
Parametry
-
name -
Zwracane wartości
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_rquery
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_rquery — Perform local (raw) AQL query
Opis
$query
[, string $dbpath
] )dbplus_rquery() performs a local (raw) AQL query using an AQL interpreter embedded into the db++ client library. dbplus_rquery() is faster than dbplus_aql() but will work on local data only.
Parametry
-
query -
-
dbpath -
Zwracane wartości
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_rrename
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_rrename — Rename a relation
Opis
$relation
, string $name
)
dbplus_rrename() will change the name of
relation to name.
Zwracane wartości
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_rsecindex
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_rsecindex — Create a new secondary index for a relation
Opis
dbplus_rsecindex() will create a new secondary
index for relation with consists of the
domains specified by domlist and is of
type type
Parametry
-
relation -
A relation opened by dbplus_open().
-
domlist -
A combination of domains. May be passed as a single domain name string or as an array of domain names.
-
type -
Zwracane wartości
Returns resource on success or DBPLUS_ERR_UNKNOWN on
failure.
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_runlink
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_runlink — Remove relation from filesystem
Opis
$relation
)
dbplus_runlink() will close and remove the
relation.
Zwracane wartości
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_rzap
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_rzap — Remove all tuples from relation
Opis
$relation
)
dbplus_rzap() will remove all tuples from
relation.
Zwracane wartości
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_savepos
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_savepos — Save position
Opis
$relation
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_setindex
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_setindex — Set index
Opis
$relation
, string $idx_name
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_setindexbynumber
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_setindexbynumber — Set index by number
Opis
$relation
, int $idx_number
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_sql
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_sql — Perform SQL query
Opis
$query
[, string $server
[, string $dbpath
]] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
query -
-
server -
-
dbpath -
Zwracane wartości
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_tcl
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_tcl — Execute TCL code on server side
Opis
$sid
, string $script
)A db++ server will prepare a TCL interpreter for each client connection. This interpreter will enable the server to execute TCL code provided by the client as a sort of stored procedures to improve the performance of database operations by avoiding client/server data transfers and context switches.
dbplus_tcl() needs to pass the client
connection id the TCL script code should
be executed by. dbplus_resolve() will provide
this connection id. The function will return whatever the TCL
code returns or a TCL error message if the TCL code fails.
Parametry
-
sid -
-
script -
Zwracane wartości
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_tremove
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_tremove — Remove tuple and return new current tuple
Opis
$relation
, array $tuple
[, array &$current
] )
dbplus_tremove() removes
tuple from relation
if it perfectly matches a tuple within the
relation. current, if given, will contain
the data of the new current tuple after calling
dbplus_tremove().
Zwracane wartości
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_undo
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_undo — Undo
Opis
$relation
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_undoprepare
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_undoprepare — Prepare undo
Opis
$relation
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_unlockrel
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_unlockrel — Give up write lock on relation
Opis
$relation
)Release a write lock previously obtained by dbplus_lockrel().
Zwracane wartości
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_unselect
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_unselect — Remove a constraint from relation
Opis
$relation
)
Calling dbplus_unselect() will remove a
constraint previously set by dbplus_find() on
relation.
Zwracane wartości
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_update
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_update — Update specified tuple in relation
Opis
$relation
, array $old
, array $new
)
dbplus_update() replaces the old
tuple with the data from the new one, only if the
old completely matches a tuple within
relation.
Zwracane wartości
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_xlockrel
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_xlockrel — Request exclusive lock on relation
Opis
$relation
)
Request an exclusive lock on relation preventing
even read access from other clients.
Zwracane wartości
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
dbplus_xunlockrel
(PHP 4 <= 4.1.0, PECL dbplus >= 0.9)
dbplus_xunlockrel — Free exclusive lock on relation
Opis
$relation
)Releases an exclusive lock previously obtained by dbplus_xlockrel().
Zwracane wartości
Notatki
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Spis treści
- dbplus_add — Add a tuple to a relation
- dbplus_aql — Perform AQL query
- dbplus_chdir — Get/Set database virtual current directory
- dbplus_close — Close a relation
- dbplus_curr — Get current tuple from relation
- dbplus_errcode — Get error string for given errorcode or last error
- dbplus_errno — Get error code for last operation
- dbplus_find — Set a constraint on a relation
- dbplus_first — Get first tuple from relation
- dbplus_flush — Flush all changes made on a relation
- dbplus_freealllocks — Free all locks held by this client
- dbplus_freelock — Release write lock on tuple
- dbplus_freerlocks — Free all tuple locks on given relation
- dbplus_getlock — Get a write lock on a tuple
- dbplus_getunique — Get an id number unique to a relation
- dbplus_info — Get information about a relation
- dbplus_last — Get last tuple from relation
- dbplus_lockrel — Request write lock on relation
- dbplus_next — Get next tuple from relation
- dbplus_open — Open relation file
- dbplus_prev — Get previous tuple from relation
- dbplus_rchperm — Change relation permissions
- dbplus_rcreate — Creates a new DB++ relation
- dbplus_rcrtexact — Creates an exact but empty copy of a relation including indices
- dbplus_rcrtlike — Creates an empty copy of a relation with default indices
- dbplus_resolve — Resolve host information for relation
- dbplus_restorepos — Restore position
- dbplus_rkeys — Specify new primary key for a relation
- dbplus_ropen — Open relation file local
- dbplus_rquery — Perform local (raw) AQL query
- dbplus_rrename — Rename a relation
- dbplus_rsecindex — Create a new secondary index for a relation
- dbplus_runlink — Remove relation from filesystem
- dbplus_rzap — Remove all tuples from relation
- dbplus_savepos — Save position
- dbplus_setindex — Set index
- dbplus_setindexbynumber — Set index by number
- dbplus_sql — Perform SQL query
- dbplus_tcl — Execute TCL code on server side
- dbplus_tremove — Remove tuple and return new current tuple
- dbplus_undo — Undo
- dbplus_undoprepare — Prepare undo
- dbplus_unlockrel — Give up write lock on relation
- dbplus_unselect — Remove a constraint from relation
- dbplus_update — Update specified tuple in relation
- dbplus_xlockrel — Request exclusive lock on relation
- dbplus_xunlockrel — Free exclusive lock on relation
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- DB++ Funkcje
- dbplus_add — Add a tuple to a relation
- dbplus_aql — Perform AQL query
- dbplus_chdir — Get/Set database virtual current directory
- dbplus_close — Close a relation
- dbplus_curr — Get current tuple from relation
- dbplus_errcode — Get error string for given errorcode or last error
- dbplus_errno — Get error code for last operation
- dbplus_find — Set a constraint on a relation
- dbplus_first — Get first tuple from relation
- dbplus_flush — Flush all changes made on a relation
- dbplus_freealllocks — Free all locks held by this client
- dbplus_freelock — Release write lock on tuple
- dbplus_freerlocks — Free all tuple locks on given relation
- dbplus_getlock — Get a write lock on a tuple
- dbplus_getunique — Get an id number unique to a relation
- dbplus_info — Get information about a relation
- dbplus_last — Get last tuple from relation
- dbplus_lockrel — Request write lock on relation
- dbplus_next — Get next tuple from relation
- dbplus_open — Open relation file
- dbplus_prev — Get previous tuple from relation
- dbplus_rchperm — Change relation permissions
- dbplus_rcreate — Creates a new DB++ relation
- dbplus_rcrtexact — Creates an exact but empty copy of a relation including indices
- dbplus_rcrtlike — Creates an empty copy of a relation with default indices
- dbplus_resolve — Resolve host information for relation
- dbplus_restorepos — Restore position
- dbplus_rkeys — Specify new primary key for a relation
- dbplus_ropen — Open relation file local
- dbplus_rquery — Perform local (raw) AQL query
- dbplus_rrename — Rename a relation
- dbplus_rsecindex — Create a new secondary index for a relation
- dbplus_runlink — Remove relation from filesystem
- dbplus_rzap — Remove all tuples from relation
- dbplus_savepos — Save position
- dbplus_setindex — Set index
- dbplus_setindexbynumber — Set index by number
- dbplus_sql — Perform SQL query
- dbplus_tcl — Execute TCL code on server side
- dbplus_tremove — Remove tuple and return new current tuple
- dbplus_undo — Undo
- dbplus_undoprepare — Prepare undo
- dbplus_unlockrel — Give up write lock on relation
- dbplus_unselect — Remove a constraint from relation
- dbplus_update — Update specified tuple in relation
- dbplus_xlockrel — Request exclusive lock on relation
- dbplus_xunlockrel — Free exclusive lock on relation
dBase
Wstęp
These functions allow you to access records stored in dBase-format (dbf) databases.
dBase files are simple sequential files of fixed length records. Records are appended to the end of the file and delete records are kept until you call dbase_pack().
The types of dBase fields available are:
| Field | dBase Type | Format | Additional information |
|---|---|---|---|
| M | Memo | n/a | This type is not supported by PHP, such field will be ignored |
| D | Date | YYYYMMDD | The field length is limited to 8 |
| N | Number | A number | You must declare a length and a precision (the number of digits after the decimal point) |
| C | String | A string | You must declare a length. When retrieving data, the string will be right-padded with spaces to fit the declared length. |
| L | Boolean | T or Y for TRUE,
F or N for FALSE |
Stored and returned as an integer (1 or 0) |
| F | Float | A float number | Support for this type of field was added in PHP 5.2.0 |
Informacja:
To rozszerzenie zostało przeniesione do repozytorium » PECL i nie jest rozprowadzane z PHP od wersji 5.3.0.
There is no support for indexes or memo fields. There is no support for locking, too. Two concurrent web server processes modifying the same dBase file will very likely ruin your database.
We recommend that you do not use dBase files as your production database. Choose any real SQL server instead; » MySQL or » Postgres are common choices with PHP. dBase support is here to allow you to import and export data to and from your web database, because the file format is commonly understood by Windows spreadsheets and organizers.
Instalacja/Konfiguracja
Spis treści
Wymagania
Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.
Instalacja
In order to enable the bundled dbase library and to use these functions, you must compile PHP with the --enable-dbase option.
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
To rozszerzenie nie posiada żadnych stałych.
dBase Funkcje
Przykłady
Many examples in this reference require a dBase database. We will use /tmp/test.dbf that will be created in the example of dbase_create().
dbase_add_record
(PHP 4, PHP 5)
dbase_add_record — Adds a record to a database
Opis
$dbase_identifier
, array $record
)Adds the given data to the database.
Parametry
-
dbase_identifier -
The database link identifier, returned by dbase_open() or dbase_create().
-
record -
An indexed array of data. The number of items must be equal to the number of fields in the database, otherwise dbase_add_record() will fail.
Informacja:
If you're using dbase_get_record() return value for this parameter, remember to reset the key named deleted.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Inserting a record in a dBase database
<?php
// open in read-write mode
$db = dbase_open('/tmp/test.dbf', 2);
if ($db) {
dbase_add_record($db, array(
date('Ymd'),
'Maxim Topolov',
'23',
'max@example.com',
'T'));
dbase_close($db);
}
?>
Zobacz też:
- dbase_delete_record() - Deletes a record from a database
- dbase_replace_record() - Replaces a record in a database
dbase_close
(PHP 4, PHP 5)
dbase_close — Closes a database
Opis
$dbase_identifier
)Closes the given database link identifier.
Parametry
-
dbase_identifier -
The database link identifier, returned by dbase_open() or dbase_create().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Closing a dBase database file
<?php
// open in read-only mode
$db = dbase_open('/tmp/test.dbf', 0);
if ($db) {
// read some data ..
dbase_close($db);
}
?>
dbase_create
(PHP 4, PHP 5)
dbase_create — Creates a database
Opis
$filename
, array $fields
)dbase_create() creates a dBase database with the given definition.
Informacja: Gdy włączony jest tryb bezpieczny, PHP sprawdza, czy pliki lub katalogi, na których zostaną wykonane operacje mają takie same UID (owner) jak skrypt, który jest aktualnie wykonywany.
Informacja:
Ta funkcja podlega restrykcjom open_basedir.
Parametry
-
filename -
The name of the database. It can be a relative or absolute path to the file where dBase will store your data.
-
fields -
An array of arrays, each array describing the format of one field of the database. Each field consists of a name, a character indicating the field type, and optionally, a length, and a precision.
Informacja:
The fieldnames are limited in length and must not exceed 10 chars.
Zwracane wartości
Returns a database link identifier if the database is successfully created,
or FALSE if an error occurred.
Przykłady
Przykład #1 Creating a dBase database file
<?php
// database "definition"
$def = array(
array("date", "D"),
array("name", "C", 50),
array("age", "N", 3, 0),
array("email", "C", 128),
array("ismember", "L")
);
// creation
if (!dbase_create('/tmp/test.dbf', $def)) {
echo "Error, can't create the database\n";
}
?>
dbase_delete_record
(PHP 4, PHP 5)
dbase_delete_record — Deletes a record from a database
Opis
$dbase_identifier
, int $record_number
)Marks the given record to be deleted from the database.
Informacja:
To actually remove the record from the database, you must also call dbase_pack().
Parametry
-
dbase_identifier -
The database link identifier, returned by dbase_open() or dbase_create().
-
record_number -
An integer which spans from 1 to the number of records in the database (as returned by dbase_numrecords()).
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- dbase_add_record() - Adds a record to a database
- dbase_replace_record() - Replaces a record in a database
dbase_get_header_info
(PHP 5)
dbase_get_header_info — Gets the header info of a database
Opis
$dbase_identifier
)Returns information on the column structure of the given database link identifier.
Parametry
-
dbase_identifier -
The database link identifier, returned by dbase_open() or dbase_create().
Zwracane wartości
An indexed array with an entry for each column in the database. The array index starts at 0.
Each array element contains an associative array of column information, as described here:
- name
- The name of the column
- type
- The human-readable name for the dbase type of the column (i.e. date, boolean, etc.)
- length
- The number of bytes this column can hold
- precision
- The number of digits of decimal precision for the column
- format
- A suggested printf() format specifier for the column
- offset
- The byte offset of the column from the start of the row
If the database header information cannot be read, FALSE is returned.
Przykłady
Przykład #1 Showing header information for a dBase database file
<?php
// Path to dbase file
$db_path = "/tmp/test.dbf";
// Open dbase file
$dbh = dbase_open($db_path, 0)
or die("Error! Could not open dbase database file '$db_path'.");
// Get column information
$column_info = dbase_get_header_info($dbh);
// Display information
print_r($column_info);
?>
dbase_get_record_with_names
(PHP 4, PHP 5)
dbase_get_record_with_names — Gets a record from a database as an associative array
Opis
$dbase_identifier
, int $record_number
)Gets a record from a dBase database as an associative array.
Parametry
-
dbase_identifier -
The database link identifier, returned by dbase_open() or dbase_create().
-
record_number -
The index of the record.
Zwracane wartości
An associative array with the record. This will also include a key named deleted which is set to 1 if the record has been marked for deletion (see dbase_delete_record()).
Each field is converted to the appropriate PHP type, except:
- Dates are left as strings.
- Integers that would have caused an overflow (> 32 bits) are returned as strings.
On error, dbase_get_record_with_names() will return FALSE.
Przykłady
Przykład #1 Listing all the registered members in the database
<?php
// open in read-only mode
$db = dbase_open('/tmp/test.dbf', 0);
if ($db) {
$record_numbers = dbase_numrecords($db);
for ($i = 1; $i <= $record_numbers; $i++) {
$row = dbase_get_record_with_names($db, $i);
if ($row['ismember'] == 1) {
echo "Member #$i: " . trim($row['name']) . "\n";
}
}
}
?>
dbase_get_record
(PHP 4, PHP 5)
dbase_get_record — Gets a record from a database as an indexed array
Opis
$dbase_identifier
, int $record_number
)Gets a record from a database as an indexed array.
Parametry
-
dbase_identifier -
The database link identifier, returned by dbase_open() or dbase_create().
-
record_number -
The index of the record.
Zwracane wartości
An indexed array with the record. This array will also include an associative key named deleted which is set to 1 if the record has been marked for deletion (see dbase_delete_record()).
Each field is converted to the appropriate PHP type, except:
- Dates are left as strings.
- Integers that would have caused an overflow (> 32 bits) are returned as strings.
On error, dbase_get_record() will return FALSE.
dbase_numfields
(PHP 4, PHP 5)
dbase_numfields — Gets the number of fields of a database
Opis
$dbase_identifier
)Gets the number of fields (columns) in the specified database.
Informacja:
Field numbers are between 0 and dbase_numfields($db)-1, while record numbers are between 1 and dbase_numrecords($db).
Parametry
-
dbase_identifier -
The database link identifier, returned by dbase_open() or dbase_create().
Zwracane wartości
The number of fields in the database, or FALSE if an error occurs.
Przykłady
Przykład #1 dbase_numfields() Example
<?php
$rec = dbase_get_record($db, $recno);
$nf = dbase_numfields($db);
for ($i = 0; $i < $nf; $i++) {
echo $rec[$i], "\n";
}
?>
dbase_numrecords
(PHP 4, PHP 5)
dbase_numrecords — Gets the number of records in a database
Opis
$dbase_identifier
)Gets the number of records (rows) in the specified database.
Informacja:
Record numbers are between 1 and dbase_numrecords($db), while field numbers are between 0 and dbase_numfields($db)-1.
Parametry
-
dbase_identifier -
The database link identifier, returned by dbase_open() or dbase_create().
Zwracane wartości
The number of records in the database, or FALSE if an error occurs.
Przykłady
Przykład #1 Looping over all the records of the database
<?php
// open in read-only mode
$db = dbase_open('/tmp/test.dbf', 0);
if ($db) {
$record_numbers = dbase_numrecords($db);
for ($i = 1; $i <= $record_numbers; $i++) {
// do something here, for each record
}
}
?>
dbase_open
(PHP 4, PHP 5)
dbase_open — Opens a database
Opis
$filename
, int $mode
)dbase_open() opens a dBase database with the given access mode.
Informacja: Gdy włączony jest tryb bezpieczny, PHP sprawdza, czy pliki lub katalogi, na których zostaną wykonane operacje mają takie same UID (owner) jak skrypt, który jest aktualnie wykonywany.
Informacja:
Ta funkcja podlega restrykcjom open_basedir.
Parametry
-
filename -
The name of the database. It can be a relative or absolute path to the file where dBase will store your data.
-
mode -
An integer which correspond to those for the open() system call (Typically 0 means read-only, 1 means write-only, and 2 means read and write).
Informacja:
You can't open a dBase file in write-only mode as the function will fail to read the headers information and thus you can't use 1 as
mode.
Przykłady
Przykład #1 Opening a dBase database file
<?php
// open in read-only mode
$db = dbase_open('/tmp/test.dbf', 0);
if ($db) {
// read some data ..
dbase_close($db);
}
?>
Zwracane wartości
Returns a database link identifier if the database is successfully opened,
or FALSE if an error occurred.
dbase_pack
(PHP 4, PHP 5)
dbase_pack — Packs a database
Opis
$dbase_identifier
)Packs the specified database by permanently deleting all records marked for deletion using dbase_delete_record().
Parametry
-
dbase_identifier -
The database link identifier, returned by dbase_open() or dbase_create().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Emptying a dBase database
<?php
// open in read-write mode
$db = dbase_open('/tmp/test.dbf', 2);
if ($db) {
$record_numbers = dbase_numrecords($db);
for ($i = 1; $i <= $record_numbers; $i++) {
dbase_delete_record($db, $i);
}
// expunge the database
dbase_pack($db);
}
?>
dbase_replace_record
(PHP 4, PHP 5)
dbase_replace_record — Replaces a record in a database
Opis
$dbase_identifier
, array $record
, int $record_number
)Replaces the given record in the database with the given data.
Parametry
-
dbase_identifier -
The database link identifier, returned by dbase_open() or dbase_create().
-
record -
An indexed array of data. The number of items must be equal to the number of fields in the database, otherwise dbase_replace_record() will fail.
Informacja:
If you're using dbase_get_record() return value for this parameter, remember to reset the key named deleted.
-
record_number -
An integer which spans from 1 to the number of records in the database (as returned by dbase_numrecords()).
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Updating a record in the database
<?php
// open in read-write mode
$db = dbase_open('/tmp/test.dbf', 2);
if ($db) {
// gets the old row
$row = dbase_get_record_with_names($db, 1);
// remove the 'deleted' entry
unset($row['deleted']);
// Update the date field with the current timestamp
$row['date'] = date('Ymd');
// Replace the record
dbase_replace_record($db, $row, 1);
dbase_close($db);
}
?>
Zobacz też:
- dbase_add_record() - Adds a record to a database
- dbase_delete_record() - Deletes a record from a database
Spis treści
- dbase_add_record — Adds a record to a database
- dbase_close — Closes a database
- dbase_create — Creates a database
- dbase_delete_record — Deletes a record from a database
- dbase_get_header_info — Gets the header info of a database
- dbase_get_record_with_names — Gets a record from a database as an associative array
- dbase_get_record — Gets a record from a database as an indexed array
- dbase_numfields — Gets the number of fields of a database
- dbase_numrecords — Gets the number of records in a database
- dbase_open — Opens a database
- dbase_pack — Packs a database
- dbase_replace_record — Replaces a record in a database
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- dBase Funkcje
- dbase_add_record — Adds a record to a database
- dbase_close — Closes a database
- dbase_create — Creates a database
- dbase_delete_record — Deletes a record from a database
- dbase_get_header_info — Gets the header info of a database
- dbase_get_record_with_names — Gets a record from a database as an associative array
- dbase_get_record — Gets a record from a database as an indexed array
- dbase_numfields — Gets the number of fields of a database
- dbase_numrecords — Gets the number of records in a database
- dbase_open — Opens a database
- dbase_pack — Packs a database
- dbase_replace_record — Replaces a record in a database
filePro
Wstęp
These functions allow read-only access to data stored in filePro databases.
filePro is a registered trademark of fP Technologies, Inc. You can find more information about filePro at » http://www.fptech.com/.
Informacja:
To rozszerzenie zostało przeniesione do repozytorium » PECL i nie jest rozprowadzane z PHP od wersji 5.2.0.
Instalacja/Konfiguracja
Spis treści
Wymagania
Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.
Instalacja
filePro support in PHP is not enabled by default. To enable the bundled read-only filePro support you need to use the--enable-filepro configuration option when compiling PHP.
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
To rozszerzenie nie posiada żadnych stałych.
filePro Funkcje
filepro_fieldcount
(PHP 4, PHP 5 <= 5.1.6)
filepro_fieldcount — Find out how many fields are in a filePro database
Opis
Returns the number of fields (columns) in the opened filePro database.
Zwracane wartości
Returns the number of fields in the opened filePro database, or FALSE on
errors.
filepro_fieldname
(PHP 4, PHP 5 <= 5.1.6)
filepro_fieldname — Gets the name of a field
Opis
$field_number
)
Returns the name of the field corresponding to
field_number.
Parametry
-
field_number -
The field number.
Zwracane wartości
Returns the name of the field as a string, or FALSE on errors.
filepro_fieldtype
(PHP 4, PHP 5 <= 5.1.6)
filepro_fieldtype — Gets the type of a field
Opis
$field_number
)
Returns the edit type of the field corresponding to field_number.
Parametry
-
field_number -
The field number.
Zwracane wartości
Returns the edit type of the field as a string, or FALSE on errors.
filepro_fieldwidth
(PHP 4, PHP 5 <= 5.1.6)
filepro_fieldwidth — Gets the width of a field
Opis
$field_number
)
Returns the width of the field corresponding to field_number.
Parametry
-
field_number -
The field number.
Zwracane wartości
Returns the width of the field as a integer, or FALSE on errors.
filepro_retrieve
(PHP 4, PHP 5 <= 5.1.6)
filepro_retrieve — Retrieves data from a filePro database
Opis
$row_number
, int $field_number
)Returns the data from the specified location in the database.
Informacja: Gdy włączony jest tryb bezpieczny, PHP sprawdza, czy pliki lub katalogi, na których zostaną wykonane operacje mają takie same UID (owner) jak skrypt, który jest aktualnie wykonywany.
Parametry
-
row_number -
The row number. Must be between zero and the total number of rows minus one (0..filepro_rowcount() - 1)
-
field_number -
The field number. Accepts values between zero and the total number of fields minus one (0..filepro_fieldcount() - 1)
Zwracane wartości
Returns the specified data, or FALSE on errors.
filepro_rowcount
(PHP 4, PHP 5 <= 5.1.6)
filepro_rowcount — Find out how many rows are in a filePro database
Opis
Returns the number of rows in the opened filePro database.
Informacja: Gdy włączony jest tryb bezpieczny, PHP sprawdza, czy pliki lub katalogi, na których zostaną wykonane operacje mają takie same UID (owner) jak skrypt, który jest aktualnie wykonywany.
Zwracane wartości
Returns the number of rows in the opened filePro database, or FALSE on
errors.
filepro
(PHP 4, PHP 5 <= 5.1.6)
filepro — Read and verify the map file
Opis
$directory
)This reads and verifies the map file, storing the field count and info.
No locking is done, so you should avoid modifying your filePro database while it may be opened in PHP.
Informacja: Gdy włączony jest tryb bezpieczny, PHP sprawdza, czy pliki lub katalogi, na których zostaną wykonane operacje mają takie same UID (owner) jak skrypt, który jest aktualnie wykonywany.
Parametry
-
directory -
The map directory.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Spis treści
- filepro_fieldcount — Find out how many fields are in a filePro database
- filepro_fieldname — Gets the name of a field
- filepro_fieldtype — Gets the type of a field
- filepro_fieldwidth — Gets the width of a field
- filepro_retrieve — Retrieves data from a filePro database
- filepro_rowcount — Find out how many rows are in a filePro database
- filepro — Read and verify the map file
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- filePro Funkcje
- filepro_fieldcount — Find out how many fields are in a filePro database
- filepro_fieldname — Gets the name of a field
- filepro_fieldtype — Gets the type of a field
- filepro_fieldwidth — Gets the width of a field
- filepro_retrieve — Retrieves data from a filePro database
- filepro_rowcount — Find out how many rows are in a filePro database
- filepro — Read and verify the map file
Firebird/InterBase
Wstęp
Firebird/InterBase jest relacyjną bazą danych oferującą wiele cech ANSI SQL-92, działającą na systemach Linux, Windows i różnorodnych platformach Unixowych. Firebird/InterBase oferuje doskonałą współbieżność, dużą wydajność oraz rozbudowaną obsługę procedur składowanych i wyzwalaczy. Baza jest używana w systemach produkcyjnych, pod różnymi nazwami od 1981 r.
InterBase to nazwa jednego z wariantów tej bazy z zamkniętym kodem źródłowym, rozwijana przez Borland/Inprise. Więcej informacji na temat InterBase jest dostępnych na stronie » http://www.borland.com/interbase/.
Firebird jest komercyjnie niezależnym projektem programistów C i C++, doradców technicznych i zwolenników rozwiajania i ulepszania wieloplatformowego systemu zarządzania bazami danych bazującego na kodzie źródłowym wydanym przez Inprise Corp (znanej jako Borland Software Corp) na licencji InterBase Public License v.1.0 z dnia 25 lipca 2000 r. Więcej informacji na temat Firebird jest dostępnych na witrynie » http://www.firebirdsql.org/.
Informacja:
To rozszerzenie działa z InterBase 5 i późniejszymi wersjami oraz ze wszystkimi wersjami Firebird. Wsparcie techniczne dla InterBase 5.x zostanie zakończone w PHP 5.
Jako znaku unikowego ta baza danych używa pojedyńczego cudzysłowu ('), ( to zachowanie jest podobne do bazy danych Sybase ) i może zostać ustawione w php.ini przez następującą dyrektywę konfiguracyjną:
magic_quotes_sybase = On
Instalacja/Konfiguracja
Spis treści
Wymagania
Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.
Instalacja
W celu uruchomienia wsparcia dla Firebird/InterBase, należy użyć opcji --with-interbase[=DIR] w czasie kompilacji PHP, gdzie DIR jest katalogiem instalacji InterBase - domyślnie /usr/interbase.
Informacja: Informacja dla użytkowników Windows
Aby poprawnie działało rozszerzenie, pliki DLL muszą znajdować się w miejscu wskazanym przez PATH systemu Windows. Aby uzyskać więcej informacji zobacz FAQ zatytułowane "Jak mam dodać mój katalog PHP do PATH w Windows". Chociaż skopiowanie plików DLL z folderu PHP do systemowego katalogu Windows także zadziała (ponieważ katalog systemowy jest domyślnie w PATH systemu), ale nie jest to wymagane. To rozszerzenie wymaga następujących plików znajdujących się w PATH: gds32.dll
Jeśli serwer Firebird/InterBase jest zainstalowany na tej samej naszynie, na której jest uruchomiony PHP, to biblioteka DLL gds32.dll jest dostępna za pomocą zmiennej środowiskowej PATH.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślna wartość | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| ibase.allow_persistent | "1" | PHP_INI_SYSTEM | |
| ibase.max_persistent | "-1" | PHP_INI_SYSTEM | |
| ibase.max_links | "-1" | PHP_INI_SYSTEM | |
| ibase.default_db | NULL | PHP_INI_SYSTEM | Dostępne od PHP 5.0.0. |
| ibase.default_user | NULL | PHP_INI_ALL | |
| ibase.default_password | NULL | PHP_INI_ALL | |
| ibase.default_charset | NULL | PHP_INI_ALL | Dostępne od PHP 5.0.0. |
| ibase.timestampformat | "%Y-%m-%d %H:%M:%S" | PHP_INI_ALL | |
| ibase.dateformat | "%Y-%m-%d" | PHP_INI_ALL | |
| ibase.timeformat | "%H:%M:%S" | PHP_INI_ALL |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
ibase.allow_persistentboolean -
Określa czy pozwolić bazie Firebird/InterBase na połączenia stałe.
-
ibase.max_persistentinteger -
Definiuje maksymalną liczbę połączeń stałych Firebird/InterBase na proces serwera. Jeżeli ta liczba zostanie przekroczona to nowe połączenia utworzone za pomocą ibase_pconnect() będą istniały tylko podczas działania skryptu.
-
ibase.max_linksinteger -
Definiuje maksymalną liczbę połączeń Firebird/InterBase na proces serwera, włączając w to połączenia stałe.
-
ibase.default_dbstring -
Definiuje domyślną bazę danych dla ibase_[p]connect() i jest używana w przypadku, gdy funkcja zostanie wywołana bez parametru. Jeżeli dodatkowo jest włączony tryb SQL safe mode, nie będą możliwe połączenia do innych baz danych, poza tą domyślną.
-
ibase.default_userstring -
Definiuje domyślną nazwę użytkownika, używaną podaczas połączenia do bazy danych, jeżeli nie jest podana jako parametr funkcji.
-
ibase.default_passwordstring -
Definiuje domyślne hasło, używane podaczas połączenia do bazy danych, jeżeli nie jest podane jako parametr funkcji.
-
ibase.default_charsetstring -
Definiuje domyślne kodowanie znaków, używane podaczas połączenia do bazy danych jeżeli nie jest podane jako parametr funkcji.
-
ibase.timestampformatstring -
-
ibase.dateformatstring -
-
ibase.timeformatstring -
Te dyrektywy ustawiają formatowanie daty i czasu, które jest używane podczas zwracania wartości dat i czasów ze zbioru wynikowego lub podczas dowiązywania argumentów.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
Następujące stałe mogą być przekazane do ibase_trans() w celu określenia zachowania transakcji.
| Stała | Opis |
|---|---|
| IBASE_DEFAULT | Standardowe ustawienia transakcji. Domyślnie są one określone przez bibliotekę klienta, w większości przypadków następująco: IBASE_WRITE|IBASE_CONCURRENCY|IBASE_WAIT . |
| IBASE_READ | Rozpoczyna transakcję w trybie tylko do odczytu. |
| IBASE_WRITE | Rozpoczyna transakcję w trybie odczytu i zapisu. |
| IBASE_CONSISTENCY | Rozpoczyna transakcję na poziomie izolacji ustawionym jako 'spójny', który oznacza że transakcja nie może czytać z tabel będących w trakcie modyfikacji przez równoległe transakcje. |
| IBASE_CONCURRENCY | Rozpoczyna transakcję na poziomie izolacji ustawionym jako 'współbieżny' (lub 'migawka'), który oznacza że transakcja ma dostęp do wszystkich tabel, ale nie widzi żadnych zmian zatwierdzonych w międzyczasie przez równoległe transakcje. |
| IBASE_COMMITTED | Rozpoczyna transakcję na poziomie izolacji ustawionym jako
'odczyt zatwierdzony'. Ta flaga powinna być połączona jedną z dwóch:
IBASE_REC_VERSION lub
IBASE_REC_NO_VERSION. Ten poziom izolacji
pozwala uzyskać dostęp do zmian zatwierdzonych w międzyczasie przez
inne transakcje. W połączeniu z IBASE_REC_NO_VERSION
może być odczytana tylko ostatnia wartość wiersza. W połączeniu
z IBASE_REC_VERSION może być zawsze
odczytana aktualna wartość wiersza po zmodyfikowaniu jej przez
równoległe transakcję.
|
| IBASE_WAIT | Oznacza, że transakcja powinna czekać i ponawiać próbę w momencie wystąpienia konfliktu. |
| IBASE_NOWAIT | Oznacza, że transakcja powinna natychmiast zwrócić błąd w momencie wystąpienia konfliktu. |
Następujące stałe mogą być przekazane do ibase_fetch_row(), ibase_fetch_assoc() lub ibase_fetch_object() w celu określenia zachowania tych funkcji podczas pobierania wierszy.
| Stała | Opis |
|---|---|
| IBASE_FETCH_BLOBS | Równoważna z IBASE_TEXT w celu zachowania zgodności
z poprzednimi wersjami. Powoduje pobranie zawartości BLOBa, zamiast
zwrócenia identyfikatora BLOBa. |
| IBASE_FETCH_ARRAYS | Powoduje pobieranie tablic. W przeciwnym wypadku są zwracane identyfikatory tablic. Identyfikatory tablic mogą być używane tylko jako argumenty dla operacji INSERT, gdyż obecnie nie ma odpowiednich funkcji do ich obsługiwania. |
| IBASE_UNIXTIME | Powoduje że pola data i czas nie są zwracane w postaci sformatowanych łańcuchów, lecz jako unixowy znacznik czasu (liczba sekund, która upłynęła od początku epoki Uniksa, datowanej na 1 stycznia 1970 0:00 GTM). W niektórych systemach może to stanowić problem, w momencie gdy zostaną użyte daty sprzed 1970 r. |
Następujące stałe przekazują żądania i opcje do funkcji usługi API (ibase_server_info(), ibase_db_info(), ibase_backup(), ibase_restore() i ibase_maintain_db()). Prosimy odnieść się do dokumentacji Firebird/InterBase żeby zapoznać się ze znaczeniem tych opcji.
-
IBASE_BKP_IGNORE_CHECKSUMS -
IBASE_BKP_IGNORE_LIMBO -
IBASE_BKP_METADATA_ONLY -
IBASE_BKP_NO_GARBAGE_COLLECT -
IBASE_BKP_OLD_DESCRIPTIONS -
IBASE_BKP_NON_TRANSPORTABLE -
IBASE_BKP_CONVERT - Opcje dla ibase_backup()
-
IBASE_RES_DEACTIVATE_IDX -
IBASE_RES_NO_SHADOW -
IBASE_RES_NO_VALIDITY -
IBASE_RES_ONE_AT_A_TIME -
IBASE_RES_REPLACE -
IBASE_RES_CREATE -
IBASE_RES_USE_ALL_SPACE - Opcje dla ibase_restore()
-
IBASE_PRP_PAGE_BUFFERS -
IBASE_PRP_SWEEP_INTERVAL -
IBASE_PRP_SHUTDOWN_DB -
IBASE_PRP_DENY_NEW_TRANSACTIONS -
IBASE_PRP_DENY_NEW_ATTACHMENTS -
IBASE_PRP_RESERVE_SPACE -
IBASE_PRP_RES_USE_FULL -
IBASE_PRP_RES -
IBASE_PRP_WRITE_MODE -
IBASE_PRP_WM_ASYNC -
IBASE_PRP_WM_SYNC -
IBASE_PRP_ACCESS_MODE -
IBASE_PRP_AM_READONLY -
IBASE_PRP_AM_READWRITE -
IBASE_PRP_SET_SQL_DIALECT -
IBASE_PRP_ACTIVATE -
IBASE_PRP_DB_ONLINE -
IBASE_RPR_CHECK_DB -
IBASE_RPR_IGNORE_CHECKSUM -
IBASE_RPR_KILL_SHADOWS -
IBASE_RPR_MEND_DB -
IBASE_RPR_VALIDATE_DB -
IBASE_RPR_FULL -
IBASE_RPR_SWEEP_DB - Opcje dla ibase_maintain_db()
-
IBASE_STS_DATA_PAGES -
IBASE_STS_DB_LOG -
IBASE_STS_HDR_PAGES -
IBASE_STS_IDX_PAGES -
IBASE_STS_SYS_RELATIONS - Opcje dla ibase_db_info()
-
IBASE_SVC_SERVER_VERSION -
IBASE_SVC_IMPLEMENTATION -
IBASE_SVC_GET_ENV -
IBASE_SVC_GET_ENV_LOCK -
IBASE_SVC_GET_ENV_MSG -
IBASE_SVC_USER_DBPATH -
IBASE_SVC_SVR_DB_INFO -
IBASE_SVC_GET_USERS - Opcje dla ibase_server_info()
Funkcje Firebird/InterBase
ibase_add_user
(PHP 4 >= 4.2.0, PHP 5)
ibase_add_user — Dodaje użytkownika do bazy danych bezpieczeństwa (tylko dla IB6 i późniejszych)
Opis
$połączenie_do_usługi
, string $nazwa_użytkownika
, string $hasło
[, string $imię
[, string $drugie_imię
[, string $nazwisko
]]] )
PHP 4 używa parametrów serwer,
login_administratora_serwera
i hasło_administratora_serwera zamiast
połączenie_do_usługi.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- ibase_modify_user() - Modyfikuje użytkownika w bazie danych bezpieczeństwa (tylko dla IB6 i późniejszych)
- ibase_delete_user() - Usuwa użytkownika z bazy danych bezpieczeństwa (tylko dla IB6 i późniejszych)
ibase_affected_rows
(PHP 5)
ibase_affected_rows — Zwraca ilość wierszy przetworzonych przez ostatnie zapytanie
Opis
$identyfikator_połączenia
] )Ta funkcja zwraca liczbę wierszy przetworzonych przez ostatnie zapytanie (INSERT, UPDATE lub DELETE), które zostało wykonane w kontekście określonej transakcji.
Parametry
-
identyfikator_połączenia -
Kontekst transakcji. Jeśli
identyfikator_połączeniajest zasobem połączenia, używana jest jego domyślna transakcja.
Zwracane wartości
Zwraca liczbę wierszy jako integer.
Zobacz też:
- ibase_query() - Wykonuje zapytanie w bazie danych Firebird/Interbase
- ibase_execute() - Wykonuje wcześniej przygotowane zapytanie
ibase_backup
(PHP 5)
ibase_backup — Uruchamia zadanie wykonania kopii zapasowej w Menedżerze Usługi i natychmiast powraca
Opis
$połączenie_do_usługi
, string $baza_źródłowa
, string $plik_docelowy
[, int $opcje = 0
[, bool $szczegółowe_komunikaty = false
]] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
ibase_blob_add
(PHP 4, PHP 5)
ibase_blob_add — Dodaje dane do nowo utworzonego BLOBa
Opis
$uchwyt_do_bloba
, string $dane
)ibase_blob_add() dodaje dane do BLOBa utworzonego za pomocą ibase_blob_create().
Parametry
-
uchwyt_do_bloba -
Uchwyt do BLOBa otwartego przez ibase_blob_create().
-
dane -
Dane do dodania.
Zwracane wartości
Nie jest zwracana żadna wartość.
Zobacz też:
- ibase_blob_cancel() - Odwołuje tworzenie BLOBa
- ibase_blob_close() - Zamyka BLOBa
- ibase_blob_create() - Tworzy nowego BLOBa w celu umieszczenia w nim danych
- ibase_blob_import() - Tworzy BLOBa, kopiuje do niego zawartość pliku i zamyka go.
ibase_blob_cancel
(PHP 4, PHP 5)
ibase_blob_cancel — Odwołuje tworzenie BLOBa
Opis
$uchwyt_do_bloba
)Ta funkcja odwołuje BLOBa, jeśli jeszcze nie został zamknięty za pomocą ibase_blob_close().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- ibase_blob_close() - Zamyka BLOBa
- ibase_blob_create() - Tworzy nowego BLOBa w celu umieszczenia w nim danych
- ibase_blob_import() - Tworzy BLOBa, kopiuje do niego zawartość pliku i zamyka go.
ibase_blob_close
(PHP 4, PHP 5)
ibase_blob_close — Zamyka BLOBa
Opis
Ta funkcja zamyka BLOBa, który wcześniej był otwarty do odczytu za pomocą ibase_blob_open() lub otwarty do zapisu za pomocą ibase_blob_create().
Parametry
-
uchwyt_do_bloba -
Uchwyt do BLOBa otwartego za pomocą ibase_blob_create() lub ibase_blob_open().
Zwracane wartości
Jeśli BLOB był odczytywany, funkcja zwraca TRUE , natomiast jeśli
BLOB był zapisywany, funkcja zwraca łańcuch zawierający identyfikator
BLOBa przydzielony dla niego przez bazę danych. W przypadku niepowodzenia
funkcja zwraca FALSE.
Zobacz też:
- ibase_blob_cancel() - Odwołuje tworzenie BLOBa
- ibase_blob_open() - Otwiera BLOBa w celu pobrania części danych
ibase_blob_create
(PHP 4, PHP 5)
ibase_blob_create — Tworzy nowego BLOBa w celu umieszczenia w nim danych
Opis
$identyfikator_połączenia = NULL
] )ibase_blob_create() tworzy nowego BLOBa w celu wypełnienia go danymi.
Parametry
-
identyfikator_połączenia -
Identyfikator połączenia do Firebird/Interbase. Jeśli został pominięty używane jest ostatnio otwarte połączenie.
Zwracane wartości
Zwraca uchwyt do BLOBa, do późniejszego użycia z
ibase_blob_add() lub FALSE w przypadku niepowodzenia.
Zobacz też:
- ibase_blob_add() - Dodaje dane do nowo utworzonego BLOBa
- ibase_blob_cancel() - Odwołuje tworzenie BLOBa
- ibase_blob_close() - Zamyka BLOBa
- ibase_blob_import() - Tworzy BLOBa, kopiuje do niego zawartość pliku i zamyka go.
ibase_blob_echo
(PHP 4, PHP 5)
ibase_blob_echo — Wysyła zawartość BLOBa do przeglądarki
Opis
$identyfikator_bloba
)$identyfikator_połączenia
, string $identyfikator_bloba
)Ta funkcja otwiera BLOBa do odczytu i wysyła jego zawartość bezpośrednio na standardowe wyjście (najczęściej do przeglądarki internetowej).
Parametry
-
identyfikator_połączenia -
Identyfikator połączenia do Firebird/Interbase. Jeśli został pominięty używane jest ostatnio otwarte połączenie.
-
identyfikator_bloba -
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- ibase_blob_open() - Otwiera BLOBa w celu pobrania części danych
- ibase_blob_close() - Zamyka BLOBa
- ibase_blob_get() - Pobiera X bajtów danych z otwartego BLOBa
ibase_blob_get
(PHP 4, PHP 5)
ibase_blob_get — Pobiera X bajtów danych z otwartego BLOBa
Opis
$uchwyt_do_bloba
, int $X
)
Ta funkcja zwraca X bajtów danych z BLOBa,
który został otwarty do odczytu za pomocą ibase_blob_open().
Informacja:
Nie jest możliwe odczytywanie informacji o BLOBie, który jest otwarty do zapisu za pomocą ibase_blob_create().
Parametry
-
uchwyt_do_bloba -
Uchwyt do BLOBa otwartego za pomocą ibase_blob_open().
-
X -
Rozmiar zwracanych danych.
Zwracane wartości
Zwraca maksymalnie X bajtów z BLOBa, lub FALSE
w przypadku niepowodzenia.
Przykłady
Przykład #1 Przykład ibase_blob_get()
<?php
$wynik = ibase_query("SELECT wartosc_bloba FROM tabela");
$dane = ibase_fetch_object($wynik);
$dane_bloba = ibase_blob_info($dane->WARTOSC_BLOBA);
$uchwyt_do_bloba = ibase_blob_open($dane->WARTOSC_BLOBA);
echo ibase_blob_get($uchwyt_do_bloba, $dane_bloba[0]);
?>
Zobacz też:
- ibase_blob_open() - Otwiera BLOBa w celu pobrania części danych
- ibase_blob_close() - Zamyka BLOBa
- ibase_blob_echo() - Wysyła zawartość BLOBa do przeglądarki
ibase_blob_import
(PHP 4, PHP 5)
ibase_blob_import — Tworzy BLOBa, kopiuje do niego zawartość pliku i zamyka go.
Opis
$identyfikator_połączenia
, resource $uchwyt_do_pliku
)$uchwyt_do_pliku
)Ta funkcja tworzy BLOBa, wczytuje do niego zawartość wskazanego pliku, zamyka go i zwraca przydzielony identyfikator BLOBa.
Parametry
-
identyfikator_połączenia -
Identyfikator połączenia do Firebird/Interbase. Jeśli został pominięty używane jest ostatnio otwarte połączenie.
-
uchwyt_do_pliku -
Uchwyt do pliku to uchwyt zwrócony przez fopen().
Zwracane wartości
W przypadku powodzenia zwraca identyfikator BLABa, a gdy wystąpi błąd zwraca FALSE.
Przykłady
Przykład #1 Przykład ibase_blob_import()
<?php
$dbh = ibase_connect($host, $username, $password);
$nazwa_pliku = '/tmp/bar';
$fd = fopen($nazwa_pliku, 'r');
if ($fd) {
$blob = ibase_blob_import($dbh, $fd);
fclose($fd);
if (!is_string($blob)) {
// nie udało się wczytać zawartości pliku do BLOBa
} else {
$query = "INSERT INTO foo (name, data) VALUES ('$nazwa_pliku', ?)";
$prepared = ibase_prepare($dbh, $query);
if (!ibase_execute($prepared, $blob)) {
// nie powiodło się wykonanie zapytania
}
}
} else {
// nie udało się otworzyć pliku
}
?>
Zobacz też:
- ibase_blob_add() - Dodaje dane do nowo utworzonego BLOBa
- ibase_blob_cancel() - Odwołuje tworzenie BLOBa
- ibase_blob_close() - Zamyka BLOBa
- ibase_blob_create() - Tworzy nowego BLOBa w celu umieszczenia w nim danych
ibase_blob_info
(PHP 4, PHP 5)
ibase_blob_info — Zwraca długość i inne informacje dotyczące BLOBa
Opis
$identyfikator_połączenia
, string $identyfikator_bloba
)$identyfikator_bloba
)Zwraca długość i inne informacje na temat BLOBa.
Parametry
-
identyfikator_połączenia -
Identyfikator połączenia do Firebird/Interbase. Jeśli został pominięty używane jest ostatnio otwarte połączenie.
-
identyfikator_bloba -
Identyfikator BLOBa.
Zwracane wartości
Zwraca tablicę zawierającą informacje o BLOBie. Zwrócona informacja składa się z długości BLOBa, liczby segmentów, wielkości największego segmentu i czy jest to BLOB strumieniowy czy segmentowy.
ibase_blob_open
(PHP 4, PHP 5)
ibase_blob_open — Otwiera BLOBa w celu pobrania części danych
Opis
$identyfikator_połączenia
, string $identyfikator_bloba
)$identyfikator_bloba
)Otwiera istniejącego BLOBa do odczytu.
Parametry
-
identyfikator_połączenia -
Identyfikator połączenia do Firebird/Interbase. Jeśli został pominięty używane jest ostatnio otwarte połączenie.
-
identyfikator_bloba -
Identyfikator BLOBa.
Zwracane wartości
Zwraca uchwyt BLOBa do późniejszego użycia z
ibase_blob_get() lub FALSE w przypadku niepowodzenia.
Zobacz też:
- ibase_blob_close() - Zamyka BLOBa
- ibase_blob_echo() - Wysyła zawartość BLOBa do przeglądarki
- ibase_blob_get() - Pobiera X bajtów danych z otwartego BLOBa
ibase_close
(PHP 4, PHP 5)
ibase_close — Zamyka połączenie z serwerem Firebird/InterBase
Opis
$identyfikator_połączenia = NULL
] )Zamyka połączenie z serwerem Firebird/InterBase wiązane za pomocą podanego identyfikator połączenia, zwróconego przez ibase_connect(). Domyślna transakcja jest potwierdzana, pozostałe są wycofywane.
Parametry
-
identyfikator_połączenia -
Identyfikator połączenia z serwerem Firebird/InterBase, zwrócony przez ibase_connect(). Jeśli nie został podany, to używane jest ostatnio otwarte połączenie.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- ibase_connect() - Otwiera połączenie do serwera Firebird/InterBase
- ibase_pconnect() - Otwiera stałe połączenie do serwera Firebird/InterBase
ibase_commit_ret
(PHP 5)
ibase_commit_ret — Potwierdza transakcję bez zamykania jej
Opis
$identyfikator_połączenia lub identyfikator_transakcji = NULL
] )Potwierdza transakcję bez zamykania jej.
Parametry
-
identyfikator_połączenia lub identyfikator_transakcji -
Jeśli jest wywołana bez argumentu, potwierdza domyślną transakcję w domyślnym połączeniu. Jeśli argumentem jest identyfikator_połączenia potwierdza domyślną transakcję we wskazanym połączeniu. Jeśli argumentem jest identyfikator_transakcji potwierdza wskazaną transakcję. Kontekst transakcji powinien zostać zachowany, natomiast wykonane segmenty zapytań w tej transakcji nie mogą zostać wycofane.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
ibase_commit
(PHP 4, PHP 5)
ibase_commit — Zatwierdza transakcję
Opis
$identyfikator_połączenia_lub_transakcji = NULL
] )Zatwierdza transakcję.
Parametry
-
identyfikator_połączenia_lub_transakcji -
Jeśli jest wywołana bez argumentu, zatwierdza domyślną transakcję w domyślnym połączeniu. Jeśli argumentem jest identyfikator połączenia zatwierdza domyślną transakcję we wskazanym połączeniu. Jeśli argumentem jest identyfikator transakcji zatwierdza wskazaną transakcję.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
ibase_connect
(PHP 4, PHP 5)
ibase_connect — Otwiera połączenie do serwera Firebird/InterBase
Opis
$baza_danych
[, string $użytkownik
[, string $hasło
[, string $kodowanie_znaków
[, int $bufory
[, int $dialekt
[, string $rola
[, int $synchronizacja
]]]]]]]] )Nawiązuje połączenie z serwerem Firebird/InterBase.
W przypadku ponownego wywołania funkcji ibase_connect() z takimi samymi argumentami, nie jest otwierane nowe połączenie, jednak w to miejsce powinien zostać zwrócony identyfikator już otwartego połączenia. Połączenie do serwera powinno zostać zamknięte wkrótce po tym, gdy wykonywanie skryptu PHP się zakończy, o ile nie zostanie zamknięte wcześniej przez jawne wywołanie funkcji ibase_close().
Parametry
-
baza_danych -
Parametr
baza_danychjest ścieżką do pliku bazy danych (lub aliasem zapisanym w pliku aliases.conf) na serwerze, na którym się ona znajduje. Jeżeli serwer nie jest uruchomiony lokalnie, to ścieżka musi być poprzedzona łańcuchem 'nazwa_hosta:' (TCP/IP), '//nazwa_hosta/' (NetBEUI) lub 'nazwa_hosta@' (IPX/SPX), w zależności od używanego protokołu. -
użytkownik -
Nazwa użytkownika. Może być ona ustawiona za pomocą dyrektywy konfiguracyjnej PHP ibase.default_user w pliku php.ini.
-
hasło -
Hasło
użytkownika. Może być ono ustawione za pomocą dyrektywy konfiguracyjnej PHP ibase.default_password w pliku php.ini. -
kodowanie_znaków -
Parametr
kodowanie_znakówjest domyślnym kodowaniem znaków narodowych w bazie danych. -
bufory -
Parametr
buforyjest liczbą buforów bazy danych jaką ma zaalokować serwer w swojej pamięci podręcznej. Jeżeli jest ustawiony na 0, lub jest pominięty, to serwer użyje wartości domyślnej. -
dialekt -
Parametr
dialektustawia domyślny dialekt SQL dla wszystkich instrukcji wykonywanych podczas połączenia. Domyślnie jest on ustawiony na najwyższy obsługiwany przez biblioteki klienta. Jest obsługiwany przez InterBase 6 i nowsze wersje. -
rola -
Są obsługiwane przez InterBase 5 i nowsze wersje.
-
synchronizacja -
Zwracane wartości
Zwraca identyfikator połączenia do serwera Firebird/InterBase
w przypadku powodzenia, lub FALSE w przypadku błędu.
Błędy/Wyjątki
Jeżeli są zwracane błędy takie jak "arithmetic exception, numeric overflow, or string truncation. Cannot transliterate character between character sets" (to może się zdarzyć w przypadku użycia niektórych znaków narodowych) po użyciu funkcji ibase_query(), to należy ustawić kodowanie znaków (np. ISO8859_2, WIN1250, UTF8).
Przykłady
Przykład #1 Przykład ibase_connect()
<?php
$host = 'localhost:/sciezka/do/mojej_bazy.fdb';
$dbh = ibase_connect($host, $username, $password, 'ISO8859_2');
$stmt = 'SELECT * FROM NAZWA_TABELI';
$sth = ibase_query($dbh, $stmt);
while ($row = ibase_fetch_object($sth)) {
echo $row->NAZWA_KOLUMNY, "\n";
}
ibase_free_result($sth);
ibase_close($dbh);
?>
Zobacz też:
- ibase_pconnect() - Otwiera stałe połączenie do serwera Firebird/InterBase
- ibase_close() - Zamyka połączenie z serwerem Firebird/InterBase
ibase_db_info
(PHP 5)
ibase_db_info — Pobiera szczegółowe informacje o bazie danych
Opis
$połączenie_do_usługi
, string $baza_danych
, int $akcja
[, int $argument = 0
] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
ibase_delete_user
(PHP 4 >= 4.2.0, PHP 5)
ibase_delete_user — Usuwa użytkownika z bazy danych bezpieczeństwa (tylko dla IB6 i późniejszych)
Opis
$połączenie_do_usługi
, string $nazwa_użytkownika
)
PHP 4 używa parametrów server,
login_administratora_serwera
i hasło_administratora_serwera zamiast
service_handle.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- ibase_add_user() - Dodaje użytkownika do bazy danych bezpieczeństwa (tylko dla IB6 i późniejszych)
- ibase_modify_user() - Modyfikuje użytkownika w bazie danych bezpieczeństwa (tylko dla IB6 i późniejszych)
ibase_drop_db
(PHP 5)
ibase_drop_db — Usuwa bazę danych Firebird/InterBase
Opis
$połączenie = NULL
] )Ta funkcja usuwa bazę danych otwartą za pomocą ibase_connect() lub ibase_pconnect(). Baza danych jest zamykana i usuwana z serwera.
Parametry
-
połączenie -
Identyfikator połączenia Firebird/Interbase. Jeśli został pominięty używane jest ostatnio otwarte połączenie.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- ibase_connect() - Otwiera połączenie do serwera Firebird/InterBase
- ibase_pconnect() - Otwiera stałe połączenie do serwera Firebird/InterBase
ibase_errcode
(PHP 5)
ibase_errcode — Zwraca kod błędu
Opis
Zwraca kod ostatniego błędu, który powstał w wyniku wywołania funkcji FireBird/Interbase.
Zwracane wartości
Zwraca kod błędu jako integer, lub FALSE w przypadku
gdy nie wystąpił żaden błąd.
ibase_errmsg
(PHP 4, PHP 5)
ibase_errmsg — Zwraca tekst komunikatu błędu
Opis
Zwraca tekst komunikatu błędu, który powstał w wyniku wywołania funkcji FireBird/Interbase.
Zwracane wartości
Zwraca tekst komunikatu błędu jako łańcuch, lub FALSE w przypadku
gdy nie wystąpił żaden błąd.
ibase_execute
(PHP 4, PHP 5)
ibase_execute — Wykonuje wcześniej przygotowane zapytanie
Opis
Wykonuje zapytanie przygotowane za pomocą ibase_prepare().
Funkcja jest o wiele bardziej efektywna niż ibase_query(), jeżeli wiele razy jest powtarzany taki sam rodzaj zapytania i zmieniane są tylko wartości niektórych parametrów.
Parametry
-
zapytanie -
Zapytanie SQL przygotowane za pomocą ibase_prepare().
-
dowiązywany_argument_1 -
-
... -
Zwracane wartości
Jeśli zapytanie powoduje błąd, zwraca FALSE. Jeśli zapytanie zostanie
pomyślnie wykonane a jego rezultatem będzie (być może pusty) zbiór wynikowy
(uzyskany za pomocą SELECT), zwraca identyfikator_wyniku. Jeśli zapytanie
zostanie pomyślnie wykonane a nie powstanie zbiór wynikowy, zwraca TRUE.
Informacja:
W PHP 5.0.0 i nowszych wersjach ta funkcja zwraca liczbę wierszy przetworzonych przez ostatnie zapytanie (jeżeli jest > 0 i użyto odpowiedniej instrukcji SQL). W przypadku zapytania wykonanego prawidłowo, ale nie przetwarzającego żadnego wiersza (np. UPDATE z warunkiem nie pasującym do żadnego rekordu) funkcja zwraca
TRUE.
Przykłady
Przykład #1 Przykład ibase_execute()
<?php
$dbh = ibase_connect($host, $username, $password, 'ISO8859_2');
$aktualizacje = array(
1 => 'Gościsława',
5 => 'Drogomysł',
7 => 'Sjęgniewa'
);
$sql = ibase_prepare($dbh, "UPDATE NAZWA_TABELI SET IMIE = ? WHERE ID = ?");
foreach ($aktualizacje as $id => $imie) {
ibase_execute($sql, $imie, $id);
}
?>
ibase_fetch_assoc
(PHP 4 >= 4.3.0, PHP 5)
ibase_fetch_assoc — Pobiera wiersz wyniku zapytania w postaci tablicy asocjacyjnej
Opis
$identyfikator_wyniku
[, int $znacznik_pobrania = 0
] )Pobiera wiersz wyniku zapytania w postaci tablicy asocjacyjnej.
ibase_fetch_assoc() pobiera jeden wiersz zawierający dane
z identyfikatora_wyniku. Jeśli takie same nazwy pól
mają dwie lub więcej kolumn, wówczas zostaną zapisane wartości z ostatnich
kolumn. Aby uzyskać dostęp do wartości różnych kolumn o tych samych nazwach,
powinniśmy pobrać wynik do tablicy z indeksami numerycznymi używając
ibase_fetch_row() , albo stosowac aliasy nazw w naszych zapytaniach.
Parametry
-
identyfikator_wyniku -
Identyfikator wyniku Firebird/Interbase.
-
znacznik_pobrania -
znacznik_pobraniajest kombinacją stałychIBASE_TEXTiIBASE_UNIXTIMEłączonych ze sobą przy pomocy operatora sumy bitowej. Przekazanie stałejIBASE_TEXTpowoduje, że ta funkcja zwraca zawartość BLOBa zamiast identyfikatora BLOBa. Przekazanie stałejIBASE_UNIXTIMEpowoduje, że ta funkcja zwraca wartości daty/czasu w postaci unixowego znacznika czasu, zamiast sformatowanego łańcucha.
Zwracane wartości
Zwraca tablicę asocjacyjną, która jest odpowiednikiem pobranego wiersza.
Kolejne wywołanie zwróci następny wiersz ze zbioru wynikowego, lub FALSE
jeśli nie ma już więcej wierszy.
Zobacz też:
- ibase_fetch_row() - Pobiera wiersz wyniku zapytania w postaci tablicy numerycznej
- ibase_fetch_object() - Pobiera wiersz wyniku zapytania w postaci obiektu
ibase_fetch_object
(PHP 4, PHP 5)
ibase_fetch_object — Pobiera wiersz wyniku zapytania w postaci obiektu
Opis
$identyfikator_wyniku
[, int $znacznik_pobrania = 0
] )Pobiera wiesz jako pseudo-obiekt z podanego zbioru wynikowego.
Kolejne wywołanie ibase_fetch_object() zwróci następny wiersz ze zbioru wynikowego.
Parametry
-
identyfikator_wyniku -
Identyfikator wyniku Firebird/InterBase uzyskanego wcześniej przez wywołanie ibase_query() lub ibase_execute().
-
znacznik_pobrania -
znacznik_pobraniajest kombinacją stałychIBASE_TEXTiIBASE_UNIXTIMEłączonych ze sobą przy pomocy operatora sumy bitowej. Przekazanie stałejIBASE_TEXTpowoduje, że ta funkcja zwraca zawartość BLOBa zamiast identyfikatora BLOBa. Przekazanie stałejIBASE_UNIXTIMEpowoduje, że ta funkcja zwraca wartości daty/czasu w postaci unixowego znacznika czasu, zamiast sformatowanego łańcucha.
Zwracane wartości
Zwraca obiekt zawierający dane kolejnego wiersza, lub FALSE jeśli nie ma
już więcej wierszy.
Przykłady
Przykład #1 Przykład ibase_fetch_object()
<?php
$dbh = ibase_connect($host, $uzytkownik, $haslo);
$stmt = 'SELECT * FROM tabela';
$sth = ibase_query($dbh, $stmt);
while ($row = ibase_fetch_object($sth)) {
echo $row->EMAIL . "\n";
}
ibase_close($dbh);
?>
Zobacz też:
- ibase_fetch_row() - Pobiera wiersz wyniku zapytania w postaci tablicy numerycznej
- ibase_fetch_assoc() - Pobiera wiersz wyniku zapytania w postaci tablicy asocjacyjnej
ibase_fetch_row
(PHP 4, PHP 5)
ibase_fetch_row — Pobiera wiersz wyniku zapytania w postaci tablicy numerycznej
Opis
$identyfikator_wyniku
[, int $znacznik_pobrania = 0
] )ibase_fetch_row() pobiera jeden wiersz zawierający dane z podanego zbioru wynikowego.
Kolejne wywołanie ibase_fetch_row()
zwróci następny wiersz ze zbioru wynikowego, lub FALSE jeśli nie
ma już więcej wierszy.
Parametry
-
identyfikator_wyniku -
Identyfikator wyniku Firebird/Interbase.
-
znacznik_pobrania -
znacznik_pobraniajest kombinacją stałychIBASE_TEXTiIBASE_UNIXTIMEłączonych ze sobą przy pomocy operatora sumy bitowej. Przekazanie stałejIBASE_TEXTpowoduje, że ta funkcja zwraca zawartość BLOBa zamiast identyfikatora BLOBa. Przekazanie stałejIBASE_UNIXTIMEpowoduje, że ta funkcja zwraca wartości daty/czasu w postaci unixowego znacznika czasu, zamiast sformatowanego łańcucha.
Zwracane wartości
Zwraca tablicę numeryczną odpowiadającą pobranemu wierszowi, lub FALSE
jeśli nie ma już więcej wierszy. Wartości kolumn są umieszczane na kolejnych
pozycjach tablicy, zaczynając od 0.
Zobacz też:
- ibase_fetch_assoc() - Pobiera wiersz wyniku zapytania w postaci tablicy asocjacyjnej
- ibase_fetch_object() - Pobiera wiersz wyniku zapytania w postaci obiektu
ibase_field_info
(PHP 4, PHP 5)
ibase_field_info — Zwraca informację o polu
Opis
$wynik
, int $numer_pola
)Zwraca tablicę zawierającą informacje o polu, po wykonaniu zapytania SELECT.
Parametry
-
wynik -
Identyfikator wyniku.
-
numer_pola -
Numer pola.
Zwracane wartości
Zwraca tablicę z następującymi kluczami: name, alias, relation, length, type - odpowiednio: nazwa, alias, relacja, długość i typ.
Przykłady
Przykład #1 Przykład ibase_field_info()
<?php
$rs = ibase_query("SELECT * FROM tabela");
$coln = ibase_num_fields($rs);
for ($i = 0; $i < $coln; $i++) {
$col_info = ibase_field_info($rs, $i);
echo "nazwa: ". $col_info['name']. "\n";
echo "alias: ". $col_info['alias']. "\n";
echo "relacja: ". $col_info['relation']. "\n";
echo "długość: ". $col_info['length']. "\n";
echo "typ: ". $col_info['type']. "\n";
}
?>
ibase_free_event_handler
(PHP 5)
ibase_free_event_handler — Odwołuje funkcję zarejestrowaną do obsługiwania zdarzeń
Opis
$uchwyt_zdarzeń
)
Ta funkcja powoduje, że zarejestrowana obsługa zdarzeń określona przez
uchwyt_zdarzeń zostanie odwołana. Funkcja zwrotna
nie będzie już wywoływana w przypadku przesyłania zdarzeń przez serwer.
Parametry
-
uchwyt_zdarzeń -
Identyfikator zasobu do obsługiwania zdarzeń, utworzony przez ibase_set_event_handler().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- ibase_set_event_handler() - Rejestruje funkcję zwrotną, wywoływaną podczas występowania zadarzeń
ibase_free_query
(PHP 4, PHP 5)
ibase_free_query — Zwalnia pamięć zajmowaną przez przygotowane zapytanie
Opis
$zapytanie
)Zwalnia pamięć zajmowaną przez przygotowane zapytanie.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
ibase_free_result
(PHP 4, PHP 5)
ibase_free_result — Zwalnia pamięć zajmowaną przez wynik
Opis
$identyfikator_wyniku
)Zwalnia pamięć zajmowaną przez wynik.
Parametry
-
identyfikator_wyniku -
Zwalnia pamięć zajmowaną przez wynik, przydzieloną w wyniku użycia ibase_query() lub ibase_execute().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
ibase_gen_id
(PHP 5)
ibase_gen_id — Zwiększa generator i zwraca jego nową wartość
Opis
$generator
[, int $przyrost = 1
[, resource $identyfikator_połączenia = NULL
]] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Zwraca nową wartość generatora jako integer, lub jako string, w przypadku gdy przekroczy ona jego zakres.
ibase_maintain_db
(PHP 5)
ibase_maintain_db — Uruchamia polecenie konserwacyjne na serwerze baz danych
Opis
$połączenie_do_usługi
, string $baza_danych
, int $akcja
[, int $argument = 0
] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
ibase_modify_user
(PHP 4 >= 4.2.0, PHP 5)
ibase_modify_user — Modyfikuje użytkownika w bazie danych bezpieczeństwa (tylko dla IB6 i późniejszych)
Opis
$połączenie_do_usługi
, string $nazwa_użytkownika
, string $hasło
[, string $imię
[, string $drugie_imię
[, string $nazwisko
]]] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
PHP 4 używa parametrów serwer,
login_administratora_serwera
i hasło_administratora_serwera zamiast
połączenie_do_usługi.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- ibase_add_user() - Dodaje użytkownika do bazy danych bezpieczeństwa (tylko dla IB6 i późniejszych)
- ibase_delete_user() - Usuwa użytkownika z bazy danych bezpieczeństwa (tylko dla IB6 i późniejszych)
ibase_name_result
(PHP 5)
ibase_name_result — Przypisuje nazwę do zbioru wynikowego
Opis
$wynik
, string $nazwa
)
Ta funkcja przypisuje nazwę do wyniku. Nazwa może być później używana
w segmentach: UPDATE|DELETE ... WHERE CURRENT OF nazwa.
Parametry
-
wynik -
Wynik zapytania Firebird/InterBase.
-
nazwa -
Nazwa do przypisania.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Przykład ibase_name_result()
<?php
$result = ibase_query("SELECT pole1,pole2 FROM tabela FOR UPDATE");
ibase_name_result($result, "moj_kursor");
$updateqry = ibase_prepare("UPDATE tabela SET pole2 = ? WHERE CURRENT OF moj_kursor");
for ($i = 0; ibase_fetch_row($result); ++$i) {
ibase_execute($updateqry, $i);
}
?>
Zobacz też:
- ibase_prepare() - Przygotowuje zapytanie do późniejszego dowiązania parametrów w postaci zmiennych, i do wykonania
- ibase_execute() - Wykonuje wcześniej przygotowane zapytanie
ibase_num_fields
(PHP 4, PHP 5)
ibase_num_fields — Zwraca liczbę pól w zbiorze wynikowym
Opis
$id_wyniku
)Zwraca liczbę pól w zbiorze wynikowym.
Parametry
-
id_wyniku -
Identyfikator zbioru wynikowego Firebird/Interbase.
Zwracane wartości
Zwraca liczbę pól jako integer.
Przykłady
Przykład #1 Przykład ibase_num_fields()
<?php
$rs = ibase_query("SELECT * FROM tabela");
$coln = ibase_num_fields($rs);
for ($i = 0; $i < $coln; $i++) {
$col_info = ibase_field_info($rs, $i);
echo "nazwa: " . $col_info['name'] . "\n";
echo "alias: " . $col_info['alias'] . "\n";
echo "relacja: " . $col_info['relation'] . "\n";
echo "długość: " . $col_info['length'] . "\n";
echo "typ: " . $col_info['type'] . "\n";
}
?>
ibase_num_params
(PHP 5)
ibase_num_params — Zwraca liczbę parametrów w przygotowanym zapytaniu
Opis
$przygotowane_zapytanie
)
Ta funkcja zwraca liczbę parametrów w przygotowanym zapytaniu, określonym
przez przygotowane_zapytanie. Wynikiem jest liczba argumentów,
które muszą zostać dowiązane podczas wywoływania ibase_execute().
Parametry
-
przygotowane_zapytanie -
Uchwyt do przygotowanego zapytania.
Zwracane wartości
Zwraca liczbę parametrów jako integer.
Zobacz też:
- ibase_prepare() - Przygotowuje zapytanie do późniejszego dowiązania parametrów w postaci zmiennych, i do wykonania
- ibase_param_info() - Zwraca informację o parametrze w przygotowanym zapytaniu
ibase_param_info
(PHP 5)
ibase_param_info — Zwraca informację o parametrze w przygotowanym zapytaniu
Opis
$przygotowane_zapytanie
, int $numer_parametru
)Zwraca tablicę z informacją o parametrze we wcześniej przygotowanym zapytaniu.
Parametry
-
przygotowane_zapytanie -
Uchwyt do przygotowanego zapytania Firebird/Interbase.
-
numer_parametru -
Pozycja parametru.
Zwracane wartości
Zwraca tablicę zawierającą następujące klucze: name, alias, relation, length i type, odpowiednio - nazwę, alias, relację, długość i typ.
Zobacz też:
- ibase_field_info() - Zwraca informację o polu
- ibase_num_params() - Zwraca liczbę parametrów w przygotowanym zapytaniu
ibase_pconnect
(PHP 4, PHP 5)
ibase_pconnect — Otwiera stałe połączenie do serwera Firebird/InterBase
Opis
$baza_danych
[, string $użytkownik
[, string $hasło
[, string $kodowanie_znaków
[, int $bufory
[, int $dialekt
[, string $rola
[, int $synchronizacja
]]]]]]]] )Nawiązuje stałe połączenie z serwerem Firebird/InterBase.
ibase_pconnect() zachowuje się prawie jak ibase_connect(), z dwoma zasadniczymi różnicami.
Pierwsza - podczas łączenia funkcja najpierw spróbuje znaleźć połączenie (stałe), już otwarte z takimi samymi argumentami (host, użytkownik, hasło, ...) Jeżeli je znajdzie, to zostanie zwrócony jego identyfikator, zamiast otwierania nowego połączenia.
Druga - połączenie z serwerem Firebird/Interbase nie zostanie zamknięte po zakończeniu wykonywania skryptu. Zamiast tego połączenie pozostanie otwarte do późniejszego użycia (ibase_close() nie zamyka połączeń nawiązanych za pomocą ibase_pconnect()). Dlatego też ten typ połączeń nazywany jest 'stałym'.
Parametry
-
baza_danych -
Parametr
baza_danychjest ścieżką do pliku bazy danych (lub aliasem zapisanym w pliku aliases.conf) na serwerze, na którym się ona znajduje. Jeżeli serwer nie jest uruchomiony lokalnie, to ścieżka musi być poprzedzona łańcuchem 'nazwa_hosta:' (TCP/IP), '//nazwa_hosta/' (NetBEUI) lub 'nazwa_hosta@' (IPX/SPX), w zależności od używanego protokołu. -
użytkownik -
Nazwa użytkownika. Może być ona ustawiona za pomocą dyrektywy konfiguracyjnej PHP ibase.default_user w pliku php.ini.
-
hasło -
Hasło
użytkownika. Może być ono ustawione za pomocą dyrektywy konfiguracyjnej PHP ibase.default_password w pliku php.ini. -
kodowanie_znaków -
Parametr
kodowanie_znakówjest domyślnym kodowaniem znaków narodowych w bazie danych. -
bufory -
Parametr
buforyjest liczbą buforów bazy danych jaką ma zaalokować serwer w swojej pamięci podręcznej. Jeżeli jest ustawiony na 0, lub jest pominięty, to serwer użyje wartości domyślnej. -
dialekt -
Parametr
dialektustawia domyślny dialekt SQL dla wszystkich instrukcji wykonywanych podczas połączenia. Domyślnie jest on ustawiony na najwyższy obsługiwany przez biblioteki klienta. Jest obsługiwany przez InterBase 6 i nowsze wersje. -
rola -
Są obsługiwane przez InterBase 5 i nowsze wersje.
-
synchronizacja -
Zwracane wartości
Zwraca identyfikator połączenia do serwera Firebird/InterBase
w przypadku powodzenia, lub FALSE w przypadku błędu.
Zobacz też:
- ibase_close() - Zamyka połączenie z serwerem Firebird/InterBase
- ibase_connect() - Otwiera połączenie do serwera Firebird/InterBase
ibase_prepare
(PHP 4, PHP 5)
ibase_prepare — Przygotowuje zapytanie do późniejszego dowiązania parametrów w postaci zmiennych, i do wykonania
Opis
$zapytanie
)$identyfikator_połączenia
, string $zapytanie
)$identyfikator_połączenia
, string $transakcja
, string $zapytanie
)Przygotowuje zapytanie do późniejszego dowiązania parametrów w postaci zmiennych, i do wykonania (za pomocą ibase_execute()).
Parametry
-
zapytanie -
Zapytanie SQL.
Zwracane wartości
Zwraca identyfikator przygotowanego zapytania, lub
FALSE w przypadku błędu.
ibase_query
(PHP 4, PHP 5)
ibase_query — Wykonuje zapytanie w bazie danych Firebird/Interbase
Opis
$identyfikator_połączenia
], string $zapytanie
[, int $dowiązywany_argument_1
] )Wykonuje zapytanie w bazie danych Firebird/Interbase.
Parametry
-
identyfikator_połączenia -
Identyfikator połączenia do Firebird/Interbase. Jeżeli zostanie pominięty, to użyte będzie istniejące połączenie.
-
zapytanie -
Zapytanie SQL.
-
dowiązywany_argument_1 -
Zwracane wartości
Jeśli zapytanie powoduje błąd, funkcja zwraca FALSE. Jeśli zapytanie zostanie
pomyślnie wykonane a jego rezultatem będzie (być może pusty) zbiór wynikowy
(uzyskany za pomocą SELECT), zwraca identyfikator_wyniku. Jeśli zapytanie
zostanie pomyślnie wykonane, a nie powstanie zbiór wynikowy, zwraca TRUE.
Informacja:
W PHP 5.0.0 i nowszych wersjach ta funkcja zwraca liczbę wierszy przetworzonych przez ostatnie zapytanie (instrukcje INSERT, UPDATE lub DELETE). W celu zachowania zgodności z poprzednimi wersjami funkcja zwraca
TRUEdla prawidłowo wykonanych zapytań, w których nie były przetwarzane wiersze.
Błędy/Wyjątki
Jeżeli są zwracane błędy takie jak "arithmetic exception, numeric overflow, or string truncation. Cannot transliterate character between character sets" (to może się zdarzyć w przypadku użycia niektórych znaków narodowych) po użyciu funkcji ibase_query(), to należy ustawić kodowanie znaków (np. ISO8859_2, WIN1250, UTF8).
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.1 |
W przypadku powodzenia funkcja zwraca obecnie TRUE jeśli
nie były przetworzone żadne wiersze. W poprzednich wersjach PHP
funkcja zwracała 0 (zero i spację).
|
Przykłady
Przykład #1 Przykład ibase_query()
<?php
$host = 'localhost:alias_bazy_danych';
$dbh = ibase_connect($host, $username, $password, 'ISO8859_2');
$stmt = 'SELECT * FROM NAZWA_TABELI';
$sth = ibase_query($dbh, $stmt) or die(ibase_errmsg());
?>
Zobacz też:
- ibase_errmsg() - Zwraca tekst komunikatu błędu
- ibase_fetch_row() - Pobiera wiersz wyniku zapytania w postaci tablicy numerycznej
- ibase_fetch_object() - Pobiera wiersz wyniku zapytania w postaci obiektu
- ibase_free_result() - Zwalnia pamięć zajmowaną przez wynik
ibase_restore
(PHP 5)
ibase_restore — Uruchamia zadanie przywrócenia bazy danych z kopii zapasowej w Menedżerze Usługi i natychmiast powraca
Opis
$połączenie_do_usługi
, string $plik_źródłowy
, string $baza_docelowa
[, int $opcje = 0
[, bool $szczegółowe_komunikaty = false
]] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
ibase_rollback_ret
(PHP 5)
ibase_rollback_ret — Wycofuje transakcję bez zamykania jej
Opis
$identyfikator_połączenia lub identyfikator_transakcji = NULL
] )Wycofuje transakcję bez zamykania jej.
Parametry
-
identyfikator_połączenia lub identyfikator_transakcji -
Jeśli jest wywołana bez argumentu, wycofuje domyślną transakcję w domyślnym połączeniu. Jeśli argumentem jest identyfikator_połączenia wycofuje domyślną transakcję we wskazanym połączeniu. Jeśli argumentem jest identyfikator_transakcji wycofuje wskazaną transakcję. Kontekst transakcji powinien zostać zachowany, natomiast wycofane segmenty zapytań w tej transakcji nie mogą zostać potwierdzone.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
ibase_rollback
(PHP 4, PHP 5)
ibase_rollback — Wycofuje transakcję
Opis
$identyfikator_połączenia_lub_transakcji = NULL
] )Wycofuje transakcję.
Parametry
-
identyfikator_połączenia_lub_transakcji -
Jeśli jest wywołana bez argumentu, wycofuje domyślną transakcję w domyślnym połączeniu. Jeśli argumentem jest identyfikator połączenia wycofuje domyślną transakcję we wskazanym połączeniu. Jeśli argumentem jest identyfikator transakcji wycofuje wskazaną transakcję.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
ibase_server_info
(PHP 5)
ibase_server_info — Pobiera informacje o serwerze baz danych
Opis
$połączenie_do_usługi
, int $akcja
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
ibase_service_attach
(PHP 5)
ibase_service_attach — Łączy się do Menedżera Usługi
Opis
$host
, string $login_administratora_serwera
, string $hasło_administratora_serwera
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
ibase_service_detach
(PHP 5)
ibase_service_detach — Odłącza się od Menedżera Usługi
Opis
$połączenie_do_usługi
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
ibase_set_event_handler
(PHP 5)
ibase_set_event_handler — Rejestruje funkcję zwrotną, wywoływaną podczas występowania zadarzeń
Opis
$nazwa_funkcji_zwrotnej
, string $nazwa_zdarzenia1
[, string $nazwa_zdarzenia2
[, string $...
]] )$identyfikator_połączenia
, callback $nazwa_funkcji_zwrotnej
, string $nazwa_zdarzenia1
[, string $nazwa_zdarzenia2
[, string $...
]] )Ta funkcja rejestruje funkcję użytkownika PHP do obsługiwania zdarzeń przesyłanych przez bazę danych.
Parametry
-
nazwa_funkcji_zwrotnej -
Funkcja zwrotna jest wywoływana z argumentami nazwa_zdarzenia i identyfikator_połączenia, gdy tylko baza danych prześle informację o wystąpieniu jednego z określonych zdarzeń.
Aby obsługa zdarzenia została wyrejestrowana, funkcja zwrotna musi zwrócić
FALSE. Każda inna zwracana wartość jest ignorowana. Funkcja akceptuje maksymalnie 15 argumentów nazwa_zdarzenia. -
nazwa_zdarzenia1 -
Nazwa zdarzenia.
-
nazwa_zdarzenia2 -
Można przekazać maksymalnie 15 zdarzeń.
Zwracane wartości
Zwracana wartość jest identyfikatorem zasobu do obsługiwania zdarzeń. Identyfikator może być użyty do odwołania funkcji obsługiwania zdarzeń za pomocą ibase_free_event_handler().
Przykłady
Przykład #1 Przykład ibase_set_event_handler()
<?php
function funkcja_zwrotna($nazwa_zdarzenia, $link)
{
if ($nazwa_zdarzenia=="NOWE_ZAMOWIENIE") {
// przetwarzanie NOWE_ZAMOWIENIE
ibase_query($link, "UPDATE zamowienia SET status='zakonczone'");
} else if ($nazwa_zdarzenia=="ZATRZYMANIE_SERWERA") {
// wyrejestrowanie funkcji zwrotnej
return false;
}
}
ibase_set_event_handler($link, "funkcja_zwrotna", "NOWE_ZAMOWIENIE", "ZATRZYMANIE_SERWERA");
?>
Zobacz też:
- ibase_free_event_handler() - Odwołuje funkcję zarejestrowaną do obsługiwania zdarzeń
- ibase_wait_event() - Czeka na zdarzenie, które zostanie przesłane przez serwer
ibase_timefmt
(PHP 4)
ibase_timefmt — Ustawia format znacznika czasu, daty i czasu w typach kolum zwracanych przez zapytania
Opis
$format
[, int $typ_kolumny = IBASE_TIMESTAMP
] )Ustawia format znacznika czasu, daty i czasu w typach kolum zwracanych przez zapytania.
Można ustawić domyślne wartości dla tych formatów za pomocą dyrektyw konfiguracyjnych PHP ibase.timestampformat, ibase.dateformat i ibase.timeformat.
Informacja:
Ta funkcja została usunięta w PHP 5. Zamiast niej należy używać ini_set().
Parametry
-
format -
Wewnętrznie (w PHP) kolumny są formatowane za pomocą funkcji języka C strftime(), więc odsyłamy do jej dokumentacji, w celu zapoznania się z możliwościami formatowania tego łańcucha.
-
typ_kolumny -
typ_kolumnyjest jedną ze stałychIBASE_TIMESTAMP,IBASE_DATEiIBASE_TIME. Jeśli zostanie pominięty, to domyślnie przyjmowana jest wartośćIBASE_TIMESTAMP.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Przykład ibase_timefmt()
<?php
/* InterBase 6 zwróci typ czasu
* w formacie '05 godzin 37 minut'. */
ibase_timefmt("%H godzin %M minut", IBASE_TIME);
?>
ibase_trans
(PHP 4, PHP 5)
ibase_trans — Rozpoczyna transakcję
Opis
$opcje_transakcji
[, resource $identyfikator_połączenia
]] )$identyfikator_połączenia
[, int $opcje_transakcji
]] )Rozpoczyna transakcję.
Informacja:
Zachowanie tej funkcji zostało zmienione w PHP 5.0.0. Pierwsze wywołanie ibase_trans() nie zwraca domyślnej transakcji w domyślnym połączeniu. Wszystkie transakcje rozpoczęte w wyniku wywołania ibase_trans() będą wycofane w momencie zakończenia działania skryptu, jeżeli nie zostaną jawnie potwierdzone lub wycofane, odpowiednio za pomocą ibase_commit() lub ibase_rollback().
Informacja:
W PHP 5.0.0. i nowszych wersjach ta funkcja akceptuje złożone argumenty
opcje_transakcjiiidentyfikator_połączenia. To pozwala transakcjom na wielokrotne połączenia do baz danych i stosowanie algorytmu dwufazowego potwierdzania. Tym samym można mieć pewność, że we wszystkich bazach danych operacje zakończą się prawidłowo lub błędnie. To NIE oznacza, że można używać tabel z różnych baz danych w jednym zapytaniu!Podczas korzystania w tym samym czasie z wielu baz danych, należy podawać obydwa parametry
identyfikator_połączeniaiidentyfikator_transakcjiprzy wywoływaniu ibase_query() i ibase_prepare().
Parametry
-
opcje_transakcji -
opcje_transakcjimogą być kombinacją stałychIBASE_READ,IBASE_WRITE,IBASE_COMMITTED,IBASE_CONSISTENCY,IBASE_CONCURRENCY,IBASE_REC_VERSION,IBASE_REC_NO_VERSION,IBASE_WAITiIBASE_NOWAIT. -
identyfikator_połączenia -
Identyfikator połączenia do Firebird/InterBase. Jeżeli zostanie pominięty, to użyte będzie istniejące połączenie.
Zwracane wartości
Zwraca identyfikator transakcji, lub FALSE w przypadku błędu.
ibase_wait_event
(PHP 5)
ibase_wait_event — Czeka na zdarzenie, które zostanie przesłane przez serwer
Opis
$nazwa_zdarzenia1
[, string $nazwa_zdarzenia2
[, string $...
]] )$identyfikator_połączenia
, string $nazwa_zdarzenia1
[, string $nazwa_zdarzenia2
[, string $...
]] )Ta funkcja wstrzymuje wykonywanie skryptu, dopóki nie zostanie przesłana informacja przez bazę danych o wystąpieniu jednego określonych zdarzeń. Funkcja akceptuje maksymalnie 15 argumentów nazwa_zdarzenia.
Parametry
-
nazwa_zdarzenia1 -
Nazwa zdarzenia.
-
nazwa_zdarzenia2 -
-
... -
Zwracane wartości
Zwraca nazwę zdarzenia, które zostało przesłane.
Zobacz też:
- ibase_set_event_handler() - Rejestruje funkcję zwrotną, wywoływaną podczas występowania zadarzeń
- ibase_free_event_handler() - Odwołuje funkcję zarejestrowaną do obsługiwania zdarzeń
Spis treści
- ibase_add_user — Dodaje użytkownika do bazy danych bezpieczeństwa (tylko dla IB6 i późniejszych)
- ibase_affected_rows — Zwraca ilość wierszy przetworzonych przez ostatnie zapytanie
- ibase_backup — Uruchamia zadanie wykonania kopii zapasowej w Menedżerze Usługi i natychmiast powraca
- ibase_blob_add — Dodaje dane do nowo utworzonego BLOBa
- ibase_blob_cancel — Odwołuje tworzenie BLOBa
- ibase_blob_close — Zamyka BLOBa
- ibase_blob_create — Tworzy nowego BLOBa w celu umieszczenia w nim danych
- ibase_blob_echo — Wysyła zawartość BLOBa do przeglądarki
- ibase_blob_get — Pobiera X bajtów danych z otwartego BLOBa
- ibase_blob_import — Tworzy BLOBa, kopiuje do niego zawartość pliku i zamyka go.
- ibase_blob_info — Zwraca długość i inne informacje dotyczące BLOBa
- ibase_blob_open — Otwiera BLOBa w celu pobrania części danych
- ibase_close — Zamyka połączenie z serwerem Firebird/InterBase
- ibase_commit_ret — Potwierdza transakcję bez zamykania jej
- ibase_commit — Zatwierdza transakcję
- ibase_connect — Otwiera połączenie do serwera Firebird/InterBase
- ibase_db_info — Pobiera szczegółowe informacje o bazie danych
- ibase_delete_user — Usuwa użytkownika z bazy danych bezpieczeństwa (tylko dla IB6 i późniejszych)
- ibase_drop_db — Usuwa bazę danych Firebird/InterBase
- ibase_errcode — Zwraca kod błędu
- ibase_errmsg — Zwraca tekst komunikatu błędu
- ibase_execute — Wykonuje wcześniej przygotowane zapytanie
- ibase_fetch_assoc — Pobiera wiersz wyniku zapytania w postaci tablicy asocjacyjnej
- ibase_fetch_object — Pobiera wiersz wyniku zapytania w postaci obiektu
- ibase_fetch_row — Pobiera wiersz wyniku zapytania w postaci tablicy numerycznej
- ibase_field_info — Zwraca informację o polu
- ibase_free_event_handler — Odwołuje funkcję zarejestrowaną do obsługiwania zdarzeń
- ibase_free_query — Zwalnia pamięć zajmowaną przez przygotowane zapytanie
- ibase_free_result — Zwalnia pamięć zajmowaną przez wynik
- ibase_gen_id — Zwiększa generator i zwraca jego nową wartość
- ibase_maintain_db — Uruchamia polecenie konserwacyjne na serwerze baz danych
- ibase_modify_user — Modyfikuje użytkownika w bazie danych bezpieczeństwa (tylko dla IB6 i późniejszych)
- ibase_name_result — Przypisuje nazwę do zbioru wynikowego
- ibase_num_fields — Zwraca liczbę pól w zbiorze wynikowym
- ibase_num_params — Zwraca liczbę parametrów w przygotowanym zapytaniu
- ibase_param_info — Zwraca informację o parametrze w przygotowanym zapytaniu
- ibase_pconnect — Otwiera stałe połączenie do serwera Firebird/InterBase
- ibase_prepare — Przygotowuje zapytanie do późniejszego dowiązania parametrów w postaci zmiennych, i do wykonania
- ibase_query — Wykonuje zapytanie w bazie danych Firebird/Interbase
- ibase_restore — Uruchamia zadanie przywrócenia bazy danych z kopii zapasowej w Menedżerze Usługi i natychmiast powraca
- ibase_rollback_ret — Wycofuje transakcję bez zamykania jej
- ibase_rollback — Wycofuje transakcję
- ibase_server_info — Pobiera informacje o serwerze baz danych
- ibase_service_attach — Łączy się do Menedżera Usługi
- ibase_service_detach — Odłącza się od Menedżera Usługi
- ibase_set_event_handler — Rejestruje funkcję zwrotną, wywoływaną podczas występowania zadarzeń
- ibase_timefmt — Ustawia format znacznika czasu, daty i czasu w typach kolum zwracanych przez zapytania
- ibase_trans — Rozpoczyna transakcję
- ibase_wait_event — Czeka na zdarzenie, które zostanie przesłane przez serwer
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Funkcje Firebird/InterBase
- ibase_add_user — Dodaje użytkownika do bazy danych bezpieczeństwa (tylko dla IB6 i późniejszych)
- ibase_affected_rows — Zwraca ilość wierszy przetworzonych przez ostatnie zapytanie
- ibase_backup — Uruchamia zadanie wykonania kopii zapasowej w Menedżerze Usługi i natychmiast powraca
- ibase_blob_add — Dodaje dane do nowo utworzonego BLOBa
- ibase_blob_cancel — Odwołuje tworzenie BLOBa
- ibase_blob_close — Zamyka BLOBa
- ibase_blob_create — Tworzy nowego BLOBa w celu umieszczenia w nim danych
- ibase_blob_echo — Wysyła zawartość BLOBa do przeglądarki
- ibase_blob_get — Pobiera X bajtów danych z otwartego BLOBa
- ibase_blob_import — Tworzy BLOBa, kopiuje do niego zawartość pliku i zamyka go.
- ibase_blob_info — Zwraca długość i inne informacje dotyczące BLOBa
- ibase_blob_open — Otwiera BLOBa w celu pobrania części danych
- ibase_close — Zamyka połączenie z serwerem Firebird/InterBase
- ibase_commit_ret — Potwierdza transakcję bez zamykania jej
- ibase_commit — Zatwierdza transakcję
- ibase_connect — Otwiera połączenie do serwera Firebird/InterBase
- ibase_db_info — Pobiera szczegółowe informacje o bazie danych
- ibase_delete_user — Usuwa użytkownika z bazy danych bezpieczeństwa (tylko dla IB6 i późniejszych)
- ibase_drop_db — Usuwa bazę danych Firebird/InterBase
- ibase_errcode — Zwraca kod błędu
- ibase_errmsg — Zwraca tekst komunikatu błędu
- ibase_execute — Wykonuje wcześniej przygotowane zapytanie
- ibase_fetch_assoc — Pobiera wiersz wyniku zapytania w postaci tablicy asocjacyjnej
- ibase_fetch_object — Pobiera wiersz wyniku zapytania w postaci obiektu
- ibase_fetch_row — Pobiera wiersz wyniku zapytania w postaci tablicy numerycznej
- ibase_field_info — Zwraca informację o polu
- ibase_free_event_handler — Odwołuje funkcję zarejestrowaną do obsługiwania zdarzeń
- ibase_free_query — Zwalnia pamięć zajmowaną przez przygotowane zapytanie
- ibase_free_result — Zwalnia pamięć zajmowaną przez wynik
- ibase_gen_id — Zwiększa generator i zwraca jego nową wartość
- ibase_maintain_db — Uruchamia polecenie konserwacyjne na serwerze baz danych
- ibase_modify_user — Modyfikuje użytkownika w bazie danych bezpieczeństwa (tylko dla IB6 i późniejszych)
- ibase_name_result — Przypisuje nazwę do zbioru wynikowego
- ibase_num_fields — Zwraca liczbę pól w zbiorze wynikowym
- ibase_num_params — Zwraca liczbę parametrów w przygotowanym zapytaniu
- ibase_param_info — Zwraca informację o parametrze w przygotowanym zapytaniu
- ibase_pconnect — Otwiera stałe połączenie do serwera Firebird/InterBase
- ibase_prepare — Przygotowuje zapytanie do późniejszego dowiązania parametrów w postaci zmiennych, i do wykonania
- ibase_query — Wykonuje zapytanie w bazie danych Firebird/Interbase
- ibase_restore — Uruchamia zadanie przywrócenia bazy danych z kopii zapasowej w Menedżerze Usługi i natychmiast powraca
- ibase_rollback_ret — Wycofuje transakcję bez zamykania jej
- ibase_rollback — Wycofuje transakcję
- ibase_server_info — Pobiera informacje o serwerze baz danych
- ibase_service_attach — Łączy się do Menedżera Usługi
- ibase_service_detach — Odłącza się od Menedżera Usługi
- ibase_set_event_handler — Rejestruje funkcję zwrotną, wywoływaną podczas występowania zadarzeń
- ibase_timefmt — Ustawia format znacznika czasu, daty i czasu w typach kolum zwracanych przez zapytania
- ibase_trans — Rozpoczyna transakcję
- ibase_wait_event — Czeka na zdarzenie, które zostanie przesłane przez serwer
FrontBase
Wstęp
Te funkcje pozwalają uzyskać dostęp do serwerów baz danych FrontBase. Więcej informacji na temat FrontBase można znaleźć na witrynie » http://www.frontbase.com/.
Dokumentacja FrontBase jest dostępna na witrynie » http://www.frontbase.com/cgi-bin/WebObjects/FBWebSite.woa.
Obsługa FrontBase została dodana w PHP 4.0.6.
Informacja:
To rozszerzenie zostało przeniesione do repozytorium » PECL i nie jest rozprowadzane z PHP od wersji 5.3.0.
Instalacja/Konfiguracja
Spis treści
Wymagania
Aby używać tych funkcji, należy zainstalować serwer zarządzania bazami danych FrontBase, lub przynajmniej biblioteki klienta fbsql. FrontBase można pobrać z witryny » http://www.frontbase.com/.
Instalacja
Aby te funkcje były dostępne, musimy skompilować PHP z obsługą fbsql używając opcji --with-fbsql[=DIR] . Jeśli użyjemy tej opcji bez określenia ścieżki do FrontBase, wówczas PHP będzie szukał bibliotek klienta fbsql w domyślnym katalogu instalacji dla danej platformy systemowej. Użytkownicy, którzy zainstalowali FrontBase w niestandardowym katalogu, zawsze powinni określić ścieżkę do fbsql: --with-fbsql=/ścieżka/do/fbsql . Podanie ścieżki wskaże PHP aby używał bibliotek klienta zainstalowanych z FrontBase, co pozwoli uniknąć problemów.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Wartość domyślna | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| fbsql.allow_persistent | "1" | PHP_INI_SYSTEM | Dostępna od PHP 4.2.0. |
| fbsql.generate_warnings | "0" | PHP_INI_SYSTEM | Dostępna od PHP 4.0.6. |
| fbsql.autocommit | "1" | PHP_INI_SYSTEM | Dostępna od PHP 4.0.6. |
| fbsql.max_persistent | "-1" | PHP_INI_SYSTEM | Dostępna od PHP 4.0.6. |
| fbsql.max_links | "128" | PHP_INI_SYSTEM | Dostępna od PHP 4.0.6. |
| fbsql.max_connections | "128" | PHP_INI_SYSTEM | Dostępna od PHP 4.0.6. |
| fbsql.max_results | "128" | PHP_INI_SYSTEM | Dostępna od PHP 4.0.6. |
| fbsql.batchSize | "1000" | PHP_INI_SYSTEM | Dostępna od PHP 4.2.0. Usunięta w PHP 5.1.0. |
| fbsql.default_host | NULL | PHP_INI_SYSTEM | Dostępna od PHP 4.0.6. |
| fbsql.default_user | "_SYSTEM" | PHP_INI_SYSTEM | Dostępna od PHP 4.0.6. |
| fbsql.default_password | "" | PHP_INI_SYSTEM | Dostępna od PHP 4.0.6. |
| fbsql.default_database | "" | PHP_INI_SYSTEM | Dostępna od PHP 4.0.6. |
| fbsql.default_database_password | "" | PHP_INI_SYSTEM | Dostępna od PHP 4.0.6. |
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
-
FBSQL_ASSOC(integer) -
FBSQL_NUM(integer) -
FBSQL_BOTH(integer) -
FBSQL_LOCK_DEFERRED(integer) -
FBSQL_LOCK_OPTIMISTIC(integer) -
FBSQL_LOCK_PESSIMISTIC(integer) -
FBSQL_ISO_READ_UNCOMMITTED(integer) -
FBSQL_ISO_READ_COMMITTED(integer) -
FBSQL_ISO_REPEATABLE_READ(integer) -
FBSQL_ISO_SERIALIZABLE(integer) -
FBSQL_ISO_VERSIONED(integer) -
FBSQL_UNKNOWN(integer) -
FBSQL_STOPPED(integer) -
FBSQL_STARTING(integer) -
FBSQL_RUNNING(integer) -
FBSQL_STOPPING(integer) -
FBSQL_NOEXEC(integer) -
FBSQL_LOB_DIRECT(integer) -
FBSQL_LOB_HANDLE(integer)
Funkcje FrontBase
fbsql_affected_rows
(PHP 4 >= 4.0.6, PHP 5)
fbsql_affected_rows — Get number of affected rows in previous FrontBase operation
Opis
$link_identifier
] )
fbsql_affected_rows() returns the number
of rows affected by the last INSERT, UPDATE or DELETE query
associated with link_identifier.
Informacja:
If you are using transactions, you need to call fbsql_affected_rows() after your INSERT, UPDATE, or DELETE query, not after the commit.
If the last query was a DELETE query with no WHERE clause, all of the records will have been deleted from the table but this function will return zero.
Informacja:
When using UPDATE, FrontBase will not update columns where the new value is the same as the old value. This creates the possibility that fbsql_affected_rows() may not actually equal the number of rows matched, only the number of rows that were literally affected by the query.
Parametry
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
Zwracane wartości
If the last query failed, this function will return -1.
fbsql_autocommit
(PHP 4 >= 4.0.6, PHP 5)
fbsql_autocommit — Enable or disable autocommit
Opis
$link_identifier
[, bool $OnOff
] )Returns the current autocommit status.
Parametry
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
-
OnOff -
If this optional parameter is given the auto commit status will be changed.
With
OnOffset toTRUEeach statement will be committed automatically, if no errors was found.With OnOff set to
FALSEthe user must commit or rollback the transaction using either fbsql_commit() or fbsql_rollback().
Zwracane wartości
Returns the current autocommit status, as a boolean.
Zobacz też:
- fbsql_commit() - Commits a transaction to the database
- fbsql_rollback() - Rollback a transaction to the database
fbsql_blob_size
(PHP 4 >= 4.2.0, PHP 5)
fbsql_blob_size — Get the size of a BLOB
Opis
$blob_handle
[, resource $link_identifier
] )Returns the size of the given BLOB.
Parametry
-
blob_handle -
A BLOB handle, returned by fbsql_create_blob().
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
Zwracane wartości
Returns the BLOB size as an integer, or FALSE on error.
fbsql_change_user
(PHP 4 >= 4.0.6, PHP 5)
fbsql_change_user — Change logged in user of the active connection
Opis
$user
, string $password
[, string $database
[, resource $link_identifier
]] )fbsql_change_user() changes the logged in user of the specified connection. If the new user and password authorization fails, the current connected user stays active.
Parametry
-
user -
The new user name.
-
password -
The new user password.
-
database -
If specified, this will be the default or current database after the user has been changed.
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
fbsql_clob_size
(PHP 4 >= 4.2.0, PHP 5)
fbsql_clob_size — Get the size of a CLOB
Opis
$clob_handle
[, resource $link_identifier
] )Returns the size of the given CLOB.
Parametry
-
clob_handle -
A CLOB handle, returned by fbsql_create_clob().
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
Zwracane wartości
Returns the CLOB size as an integer, or FALSE on error.
fbsql_close
(PHP 4 >= 4.0.6, PHP 5)
fbsql_close — Zamyka połączenie z serwerem FrontBase
Opis
$identyfikator_połączenia
] )Zamyka połączenie z serwerem FrontBase skojarzone z podanym identyfikatorem połączenia.
Używanie fbsql_close() zazwyczaj nie jest konieczne, jako że niestałe połączenia są automatycznie zamykane po zakończeniu wykonywania skryptu.
Parametry
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Przykład fbsql_close()
<?php
$link = fbsql_connect("localhost", "_SYSTEM", "")
or die("Nie można nawiązać połączenia");
echo "Połączenie zostało nawiązane";
fbsql_close($link);
?>
Zobacz też:
- fbsql_connect() - Otwiera połączenie z serwerem FrontBase
- fbsql_pconnect() - Otwiera stałe połączenie z serwerem FrontBase
fbsql_commit
(PHP 4 >= 4.0.6, PHP 5)
fbsql_commit — Commits a transaction to the database
Opis
$link_identifier
] )Ends the current transaction by writing all inserts, updates and deletes to the disk and unlocking all row and table locks held by the transaction. This command is only needed if autocommit is set to false.
Parametry
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- fbsql_autocommit() - Enable or disable autocommit
- fbsql_rollback() - Rollback a transaction to the database
fbsql_connect
(PHP 4 >= 4.0.6, PHP 5)
fbsql_connect — Otwiera połączenie z serwerem FrontBase
Opis
$nazwa_hosta = ini_get("fbsql.default_host")
[, string $użytkownik = ini_get("fbsql.default_user")
[, string $hasło = ini_get("fbsql.default_password")
]]] )fbsql_connect() nawiązuje połączenie z serwerem FrontBase.
W przypadku ponownego wywołania funkcji fbsql_connect() z takimi samymi argumentami, nie jest otwierane nowe połączenie, jednak w to miejsce powinien zostać zwrócony identyfikator już otwartego połączenia.
Połączenie do serwera powinno zostać zamknięte wkrótce po tym, kiedy wykonywanie skryptu PHP się zakończy, o ile nie zostanie zamknięte wcześniej przez jawne wywołanie funkcji fbsql_close().
Parametry
-
nazwa_hosta -
Nazwa hosta, na którym jest uruchomiony serwer.
-
użytkownik -
Nazwa użytkownika do nawiązania połączenia.
-
hasło -
Hasło do nawiązania połączenia.
Zwracane wartości
Zwraca identyfikator połączenia do FrontBase w przypadku sukcesu
lub FALSE w przypadku błędów.
Przykłady
Przykład #1 Przykład fbsql_connect()
<?php
$link = fbsql_connect("localhost", "_SYSTEM", "")
or die("Nie można nawiązać połączenia");
echo "Połączenie zostało nawiązane";
fbsql_close($link);
?>
Zobacz też:
- fbsql_pconnect() - Otwiera stałe połączenie z serwerem FrontBase
- fbsql_close() - Zamyka połączenie z serwerem FrontBase
fbsql_create_blob
(PHP 4 >= 4.2.0, PHP 5)
fbsql_create_blob — Create a BLOB
Opis
$blob_data
[, resource $link_identifier
] )Creates a BLOB from the given data.
Parametry
-
blob_data -
The BLOB data.
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
Zwracane wartości
Returns a resource handle to the newly created BLOB, which can be used with insert and update commands to store the BLOB in the database.
Przykłady
Przykład #1 fbsql_create_blob() example
<?php
$link = fbsql_pconnect("localhost", "_SYSTEM", "secret")
or die("Could not connect");
$filename = "blobfile.bin";
$fp = fopen($filename, "rb");
$blobdata = fread($fp, filesize($filename));
fclose($fp);
$blobHandle = fbsql_create_blob($blobdata, $link);
$sql = "INSERT INTO BLOB_TABLE (BLOB_COLUMN) VALUES ($blobHandle);";
$rs = fbsql_query($sql, $link);
?>
Zobacz też:
- fbsql_create_clob() - Create a CLOB
- fbsql_read_blob() - Read a BLOB from the database
- fbsql_read_clob() - Read a CLOB from the database
- fbsql_set_lob_mode() - Set the LOB retrieve mode for a FrontBase result set
fbsql_create_clob
(PHP 4 >= 4.2.0, PHP 5)
fbsql_create_clob — Create a CLOB
Opis
$clob_data
[, resource $link_identifier
] )Creates a CLOB from the given data.
Parametry
-
clob_data -
The CLOB data.
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
Zwracane wartości
Returns a resource handle to the newly created CLOB, which can be used with insert and update commands to store the CLOB in the database.
Przykłady
Przykład #1 fbsql_create_clob() example
<?php
$link = fbsql_pconnect("localhost", "_SYSTEM", "secret")
or die("Could not connect");
$filename = "clob_file.txt";
$fp = fopen($filename, "rb");
$clobdata = fread($fp, filesize($filename));
fclose($fp);
$clobHandle = fbsql_create_clob($clobdata, $link);
$sql = "INSERT INTO CLOB_TABLE (CLOB_COLUMN) VALUES ($clobHandle);";
$rs = fbsql_query($sql, $link);
?>
Zobacz też:
- fbsql_create_blob() - Create a BLOB
- fbsql_read_blob() - Read a BLOB from the database
- fbsql_read_clob() - Read a CLOB from the database
- fbsql_set_lob_mode() - Set the LOB retrieve mode for a FrontBase result set
fbsql_create_db
(PHP 4 >= 4.0.6, PHP 5)
fbsql_create_db — Create a FrontBase database
Opis
$database_name
[, resource $link_identifier
[, string $database_options
]] )Attempts to create a new database on the specified server.
Parametry
-
database_name -
The database name, as a string.
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
-
database_options -
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 fbsql_create_db() example
<?php
$link = fbsql_pconnect("localhost", "_SYSTEM", "secret")
or die("Could not connect");
if (fbsql_create_db("my_db")) {
echo "Database created successfully\n";
} else {
printf("Error creating database: %s\n", fbsql_error());
}
?>
fbsql_data_seek
(PHP 4 >= 4.0.6, PHP 5)
fbsql_data_seek — Move internal result pointer
Opis
$result
, int $row_number
)Moves the internal row pointer of the FrontBase result associated with the specified result identifier to point to the specified row number.
The next call to fbsql_fetch_row() would return that row.
Parametry
-
result -
Identyfikator wyniku zwrócony przez fbsql_query() lub fbsql_db_query().
-
row_number -
The row number. Starts at 0.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 fbsql_data_seek() example
<?php
$link = fbsql_pconnect("localhost", "_SYSTEM", "secret")
or die("Could not connect");
fbsql_select_db("samp_db")
or die("Could not select database");
$query = "SELECT last_name, first_name FROM friends;";
$result = fbsql_query($query)
or die("Query failed");
// fetch rows in reverse order
for ($i = fbsql_num_rows($result) - 1; $i >=0; $i--) {
if (!fbsql_data_seek($result, $i)) {
printf("Cannot seek to row %d\n", $i);
continue;
}
if (!($row = fbsql_fetch_object($result)))
continue;
echo $row->last_name . $row->first_name . "<br />\n";
}
fbsql_free_result($result);
?>
fbsql_database_password
(PHP 4 >= 4.0.6, PHP 5)
fbsql_database_password — Sets or retrieves the password for a FrontBase database
Opis
$link_identifier
[, string $database_password
] )Sets and retrieves the database password used by the connection. If a database is protected by a database password, the user must call this function before calling fbsql_select_db().
If no link is open, the function will try to establish a link as if fbsql_connect() was called, and use it.
This function does not change the database password in the database nor can it be used to retrieve the database password for a database.
Parametry
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
-
database_password -
The database password, as a string. If given, the function sets the database password for the specified link identifier.
Zwracane wartości
Returns the database password associated with the link identifier.
Przykłady
Przykład #1 fbsql_create_clob() example
<?php
$link = fbsql_pconnect("localhost", "_SYSTEM", "secret")
or die("Could not connect");
fbsql_database_password($link, "secret db password");
fbsql_select_db($database, $link);
?>
Zobacz też:
- fbsql_connect() - Otwiera połączenie z serwerem FrontBase
- fbsql_pconnect() - Otwiera stałe połączenie z serwerem FrontBase
- fbsql_select_db() - Select a FrontBase database
fbsql_database
(PHP 4 >= 4.0.6, PHP 5)
fbsql_database — Get or set the database name used with a connection
Opis
$link_identifier
[, string $database
] )Get or set the database name used with the connection.
Parametry
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
-
database -
The database name. If given, the default database of the connexion will be changed to
database.
Zwracane wartości
Returns the name of the database used with this connection.
fbsql_db_query
(PHP 4 >= 4.0.6, PHP 5)
fbsql_db_query — Send a FrontBase query
Opis
$database
, string $query
[, resource $link_identifier
] )Selects a database and executes a query on it.
Parametry
-
database -
The database to be selected.
-
query -
The SQL query to be executed.
Informacja:
The query string shall always end with a semicolon.
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
Zwracane wartości
Returns a positive FrontBase result identifier to the query result, or
FALSE on error.
Zobacz też:
- fbsql_query() - Wysyła zapytanie do serwera FrontBase
- fbsql_connect() - Otwiera połączenie z serwerem FrontBase
fbsql_db_status
(PHP 4 >= 4.0.7, PHP 5)
fbsql_db_status — Zwraca status dla podanej bazy danych
Opis
$nazwa_bazy_danych
[, resource $identyfikator_połączenia
] )Zwraca bieżący status dla określonej bazy danych.
Parametry
-
nazwa_bazy_danych -
Nazwa bazy danych.
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
Zwracane wartości
Zwraca wartość typu integer oznaczającą obecny status bazy danych. Może ona przyjmować następujące wartości:
-
FALSE- Identyfikator połączenia do hosta był nieprawidłowy. Ten błąd występuje wówczas, gdyidentyfikator_połączeniajest zasobem utrzymującym bezpośrednie połączenie z bazą danych na ustalonym porcie. FBExec może być dostępny na serwerze, jednak nie zostało zdefiniowane dla niego połączenie. -
FBSQL_UNKNOWN- Nieznany status. -
FBSQL_STOPPED- Baza danych nie jest uruchomiona. Użyj fbsql_start_db() aby uruchomić bazę danych. -
FBSQL_STARTING- Baza danych uruchamia się. -
FBSQL_RUNNING- Baza danych jest uruchomiona i można wykonywać instrukcje SQL. -
FBSQL_STOPPING- Baza danych zatrzymuje się. -
FBSQL_NOEXEC- FBExec nie jest uruchomiony na serwerze i nie jest możliwe pobranie informacji o statusie bazy danych.
Zobacz też:
- fbsql_start_db() - Uruchamia bazę danych na serwerze lokalnym lub zdalnym
- fbsql_stop_db() - Zatrzymuje bazę danych na serwerze lokalnym lub zdalnym
fbsql_drop_db
(PHP 4 >= 4.0.6, PHP 5)
fbsql_drop_db — Drop (delete) a FrontBase database
Opis
$database_name
[, resource $link_identifier
] )fbsql_drop_db() attempts to drop (remove) an entire database from the server associated with the specified link identifier.
Parametry
-
database_name -
The database name, as a string.
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
fbsql_errno
(PHP 4 >= 4.0.6, PHP 5)
fbsql_errno — Returns the error number from previous operation
Opis
$link_identifier
] )Returns the numerical value of the error message from previous FrontBase operation.
Errors coming back from the fbsql database backend don't issue warnings. Instead, use fbsql_errno() to retrieve the error code. Note that this function only returns the error code from the most recently executed fbsql function (not including fbsql_error() and fbsql_errno()), so if you want to use it, make sure you check the value before calling another fbsql function.
Parametry
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
Zwracane wartości
Returns the error number from the last fbsql function, or 0 (zero) if no error occurred.
Przykłady
Przykład #1 fbsql_errno() Example
<?php
fbsql_connect("marliesle");
echo fbsql_errno() . ": " . fbsql_error() . "<br />";
fbsql_select_db("nonexistentdb");
echo fbsql_errno() . ": " . fbsql_error() . "<br />";
$conn = fbsql_query("SELECT * FROM nonexistenttable;");
echo fbsql_errno() . ": " . fbsql_error() . "<br />";
?>
Zobacz też:
- fbsql_error() - Returns the error message from previous operation
- fbsql_warnings() - Enable or disable FrontBase warnings
fbsql_error
(PHP 4 >= 4.0.6, PHP 5)
fbsql_error — Returns the error message from previous operation
Opis
$link_identifier
] )Returns the error message from previous FrontBase operation.
Errors coming back from the fbsql database backend don't issue warnings. Instead, use fbsql_error() to retrieve the error text. Note that this function only returns the error code from the most recently executed fbsql function (not including fbsql_error() and fbsql_errno()), so if you want to use it, make sure you check the value before calling another fbsql function.
Parametry
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
Zwracane wartości
Returns the error text from the last fbsql function, or '' (the empty string) if no error occurred.
Przykłady
Przykład #1 fbsql_error() Example
<?php
fbsql_connect("marliesle");
echo fbsql_errno() . ": " . fbsql_error() . "<br />";
fbsql_select_db("nonexistentdb");
echo fbsql_errno() . ": " . fbsql_error() . "<br />";
$conn = fbsql_query("SELECT * FROM nonexistenttable;");
echo fbsql_errno() . ": " . fbsql_error() . "<br />";
?>
Zobacz też:
- fbsql_errno() - Returns the error number from previous operation
- fbsql_warnings() - Enable or disable FrontBase warnings
fbsql_fetch_array
(PHP 4 >= 4.0.6, PHP 5)
fbsql_fetch_array — Fetch a result row as an associative array, a numeric array, or both
Opis
$result
[, int $result_type
] )fbsql_fetch_array() is a combination of fbsql_fetch_row() and fbsql_fetch_assoc().
An important thing to note is that using fbsql_fetch_array() is NOT significantly slower than using fbsql_fetch_row(), while it provides a significant added value.
Parametry
-
result -
Identyfikator wyniku zwrócony przez fbsql_query() lub fbsql_db_query().
-
result_type -
A constant and can take the following values:
FBSQL_ASSOC,FBSQL_NUM, orFBSQL_BOTH.When using
FBSQL_BOTH, in addition to storing the data in the numeric indices of the result array, it also stores the data in associative indices, using the field names as keys.
Zwracane wartości
Returns an array that corresponds to the fetched row, or FALSE
if there are no more rows.
If two or more columns of the result have the same field names, the last column will take precedence. To access the other column(s) of the same name, you must the numeric index of the column or make an alias for the column.
select t1.f1 as foo t2.f1 as bar from t1, t2
Przykłady
Przykład #1 fbsql_fetch_array() example
<?php
fbsql_connect($host, $user, $password);
$result = fbsql_db_query("database", "select user_id, fullname from table");
while ($row = fbsql_fetch_array($result)) {
echo "user_id: " . $row["user_id"] . "<br />\n";
echo "user_id: " . $row[0] . "<br />\n";
echo "fullname: " . $row["fullname"] . "<br />\n";
echo "fullname: " . $row[1] . "<br />\n";
}
fbsql_free_result($result);
?>
Zobacz też:
- fbsql_fetch_row() - Get a result row as an enumerated array
- fbsql_fetch_assoc() - Fetch a result row as an associative array
- fbsql_fetch_object() - Fetch a result row as an object
fbsql_fetch_assoc
(PHP 4 >= 4.0.6, PHP 5)
fbsql_fetch_assoc — Fetch a result row as an associative array
Opis
$result
)
Calling fbsql_fetch_assoc() is equivalent to calling
fbsql_fetch_array() with
FBSQL_ASSOC as second parameter. It only returns an
associative array.
This is the way fbsql_fetch_array() originally worked. If you need the numeric indices as well as the associative, use fbsql_fetch_array().
An important thing to note is that using fbsql_fetch_assoc() is NOT significantly slower than using fbsql_fetch_row(), while it provides a significant added value.
Zwracane wartości
Returns an associative array that corresponds to the fetched row, or
FALSE if there are no more rows.
If two or more columns of the result have the same field names, the last column will take precedence. To access the other column(s) of the same name, you must use fbsql_fetch_array() and have it return the numeric indices as well.
Przykłady
Przykład #1 fbsql_fetch_assoc() example
<?php
fbsql_connect($host, $user, $password);
$result = fbsql_db_query("database", "select * from table");
while ($row = fbsql_fetch_assoc($result)) {
echo $row["user_id"];
echo $row["fullname"];
}
fbsql_free_result($result);
?>
Zobacz też:
- fbsql_fetch_row() - Get a result row as an enumerated array
- fbsql_fetch_array() - Fetch a result row as an associative array, a numeric array, or both
- fbsql_fetch_object() - Fetch a result row as an object
fbsql_fetch_field
(PHP 4 >= 4.0.6, PHP 5)
fbsql_fetch_field — Get column information from a result and return as an object
Opis
$result
[, int $field_offset
] )Used in order to obtain information about fields in a certain query result.
Parametry
-
result -
Identyfikator wyniku zwrócony przez fbsql_query() lub fbsql_db_query().
-
field_offset -
The numerical offset of the field. The field index starts at 0. If not specified, the next field that wasn't yet retrieved by fbsql_fetch_field() is retrieved.
Zwracane wartości
Returns an object containing field information, or FALSE on errors.
The properties of the object are:
- name - column name
- table - name of the table the column belongs to
- max_length - maximum length of the column
-
not_null - 1 if the column cannot be
NULL - type - the type of the column
Przykłady
Przykład #1 fbsql_fetch_field() example
<?php
fbsql_connect($host, $user, $password)
or die("Could not connect");
$result = fbsql_db_query("database", "select * from table")
or die("Query failed");
# get column metadata
$i = 0;
while ($i < fbsql_num_fields($result)) {
echo "Information for column $i:<br />\n";
$meta = fbsql_fetch_field($result);
if (!$meta) {
echo "No information available<br />\n";
}
echo "<pre>
max_length: $meta->max_length
name: $meta->name
not_null: $meta->not_null
table: $meta->table
type: $meta->type
</pre>";
$i++;
}
fbsql_free_result($result);
?>
fbsql_fetch_lengths
(PHP 4 >= 4.0.6, PHP 5)
fbsql_fetch_lengths — Get the length of each output in a result
Opis
$result
)Stores the lengths of each result column in the last row returned by fbsql_fetch_row(), fbsql_fetch_array() and fbsql_fetch_object() in an array.
Zwracane wartości
Returns an array, starting at offset 0, that corresponds to the lengths of
each field in the last row fetched by fbsql_fetch_row(),
or FALSE on error.
fbsql_fetch_object
(PHP 4 >= 4.0.6, PHP 5)
fbsql_fetch_object — Fetch a result row as an object
Opis
$result
)fbsql_fetch_object() is similar to fbsql_fetch_array(), with one difference - an object is returned, instead of an array. Indirectly, that means that you can only access the data by the field names, and not by their offsets (numbers are illegal property names).
Speed-wise, the function is identical to fbsql_fetch_array(), and almost as quick as fbsql_fetch_row() (the difference is insignificant).
Zwracane wartości
Returns an object with properties that correspond to the fetched row, or
FALSE if there are no more rows.
Przykłady
Przykład #1 fbsql_fetch_object() example
<?php
fbsql_connect($host, $user, $password);
$result = fbsql_db_query("database", "select * from table");
while ($row = fbsql_fetch_object($result)) {
echo $row->user_id;
echo $row->fullname;
}
fbsql_free_result($result);
?>
Zobacz też:
- fbsql_fetch_array() - Fetch a result row as an associative array, a numeric array, or both
- fbsql_fetch_row() - Get a result row as an enumerated array
- fbsql_fetch_assoc() - Fetch a result row as an associative array
fbsql_fetch_row
(PHP 4 >= 4.0.6, PHP 5)
fbsql_fetch_row — Get a result row as an enumerated array
Opis
$result
)fbsql_fetch_row() fetches one row of data from the result associated with the specified result identifier.
Subsequent call to fbsql_fetch_row() would
return the next row in the result set, or FALSE if there are no
more rows.
Zwracane wartości
Returns an array that corresponds to the fetched row where each result
column is stored in an offset, starting at offset 0, or FALSE if there
are no more rows.
Zobacz też:
- fbsql_fetch_array() - Fetch a result row as an associative array, a numeric array, or both
- fbsql_fetch_assoc() - Fetch a result row as an associative array
- fbsql_fetch_object() - Fetch a result row as an object
- fbsql_data_seek() - Move internal result pointer
- fbsql_fetch_lengths() - Get the length of each output in a result
- fbsql_result() - Get result data
fbsql_field_flags
(PHP 4 >= 4.0.6, PHP 5)
fbsql_field_flags — Get the flags associated with the specified field in a result
Opis
$result
[, int $field_offset
] )Gets the flags associated with the specified field in a result.
Parametry
-
result -
A result pointer returned by fbsql_list_fields().
-
field_offset -
The numerical offset of the field. The field index starts at 0.
Zwracane wartości
Returns the field flags of the specified field as a single word per flag separated by a single space, so that you can split the returned value using explode().
fbsql_field_len
(PHP 4 >= 4.0.6, PHP 5)
fbsql_field_len — Returns the length of the specified field
Opis
$result
[, int $field_offset
] )Returns the length of the specified field.
Parametry
-
result -
A result pointer returned by fbsql_list_fields().
-
field_offset -
The numerical offset of the field. The field index starts at 0.
Zwracane wartości
Returns the length of the specified field.
fbsql_field_name
(PHP 4 >= 4.0.6, PHP 5)
fbsql_field_name — Get the name of the specified field in a result
Opis
$result
[, int $field_index
] )Returns the name of the specified field index.
Parametry
-
result -
A result pointer returned by fbsql_list_fields().
-
field_index -
The numerical offset of the field. The field index starts at 0.
Zwracane wartości
Returns the name as a string, or FALSE if the field doesn't exist.
Przykłady
Przykład #1 fbsql_field_name() example
<?php
// The users table consists of three fields:
// user_id
// username
// password.
$res = fbsql_db_query("users", "select * from users", $link);
echo fbsql_field_name($res, 0) . "\n";
echo fbsql_field_name($res, 2);
?>
Powyższy przykład wyświetli:
user_id password
fbsql_field_seek
(PHP 4 >= 4.0.6, PHP 5)
fbsql_field_seek — Set result pointer to a specified field offset
Opis
$result
[, int $field_offset
] )Seeks to the specified field offset. If the next call to fbsql_fetch_field() doesn't include a field offset, the field offset specified in fbsql_field_seek() will be returned.
Parametry
-
result -
Identyfikator wyniku zwrócony przez fbsql_query() lub fbsql_db_query().
-
field_offset -
The numerical offset of the field. The field index starts at 0.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
fbsql_field_table
(PHP 4 >= 4.0.6, PHP 5)
fbsql_field_table — Zwraca nazwę tabeli dla określonego pola
Opis
$wynik
[, int $przesunięcie_pola
] )Zwraca nazwę tabeli dla określonego pola w zbiorze wynikowym.
Parametry
-
result -
Identyfikator wyniku zwrócony przez fbsql_query() lub fbsql_db_query().
-
przesunięcie_pola -
Liczbowe przesunięcie pola. Przesunięcie pola zaczyna się od 0.
Zwracane wartości
Zwraca nazwę tabeli jako string.
fbsql_field_type
(PHP 4 >= 4.0.6, PHP 5)
fbsql_field_type — Get the type of the specified field in a result
Opis
$result
[, int $field_offset
] )fbsql_field_type() is similar to the fbsql_field_name() function, but the field type is returned instead.
Parametry
-
result -
Identyfikator wyniku zwrócony przez fbsql_query() lub fbsql_db_query().
-
field_offset -
The numerical offset of the field. The field index starts at 0.
Zwracane wartości
Returns the field type, as a string.
This can be one of int, real, string, blob, and others as detailed in the » FrontBase documentation.
Przykłady
Przykład #1 fbsql_field_type() example
<?php
fbsql_connect("localhost", "_SYSTEM", "");
fbsql_select_db("wisconsin");
$result = fbsql_query("SELECT * FROM onek;");
$fields = fbsql_num_fields($result);
$rows = fbsql_num_rows($result);
$i = 0;
$table = fbsql_field_table($result, $i);
echo "Your '" . $table . "' table has " . $fields . " fields and " . $rows . " records <br />";
echo "The table has the following fields <br />";
while ($i < $fields) {
$type = fbsql_field_type($result, $i);
$name = fbsql_field_name($result, $i);
$len = fbsql_field_len($result, $i);
$flags = fbsql_field_flags($result, $i);
echo $type . " " . $name . " " . $len . " " . $flags . "<br />";
$i++;
}
fbsql_close();
?>
fbsql_free_result
(PHP 4 >= 4.0.6, PHP 5)
fbsql_free_result — Zwalnia pamięć zajmowaną przez wynik
Opis
$wynik
)
Zwalnia pamięć zajmowaną przez wynik.
Wywołanie fbsql_free_result() jest potrzebne tylko wtedy, jeśli obawiamy się o ilość pamięci jaka zostanie użyta dla zapytań zwracających duży zbiór wyników. Cała pamięć przydzielona dla wyników jest automatycznie zwalniana, kiedy zakończy się wykonywanie skryptu.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
fbsql_get_autostart_info
(PHP 4 >= 4.0.7, PHP 5)
fbsql_get_autostart_info — Pobiera informacje o bazach automatycznie uruchamianych podczas startu serwera
Opis
$identyfikator_połączenia
] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
fbsql_hostname
(PHP 4 >= 4.0.6, PHP 5)
fbsql_hostname — Zraca lub ustawia nazwę hosta używaną w połączeniu
Opis
$identyfikator_połączenia
[, string $nazwa_hosta
] )Zraca lub ustawia nazwę hosta używaną w połączeniu.
Parametry
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
-
nazwa_hosta -
Jeśli zostanie podana, wówczas będzie nową nazwą hosta w połączeniu.
Zwracane wartości
Zwraca nazwę aktualnego hosta używanego w połączeniu.
Zobacz też:
- fbsql_username() - Zraca lub ustawia nazwę użytkownika używaną w połączeniu
- fbsql_password() - Zwraca lub ustawia hasło użytkownika używane w połączeniu
fbsql_insert_id
(PHP 4 >= 4.0.6, PHP 5)
fbsql_insert_id — Get the id generated from the previous INSERT operation
Opis
$link_identifier
] )Gets the id generated from the previous INSERT operation which created a DEFAULT UNIQUE value.
Informacja:
The value of the FrontBase SQL function fbsql_insert_id() always contains the most recently generated DEFAULT UNIQUE value, and is not reset between queries.
Parametry
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
Zwracane wartości
Returns the ID generated from the previous INSERT query, or 0 if the previous query does not generate an DEFAULT UNIQUE value.
If you need to save the value for later, be sure to call this function immediately after the query that generates the value.
fbsql_list_dbs
(PHP 4 >= 4.0.6, PHP 5)
fbsql_list_dbs — List databases available on a FrontBase server
Opis
$link_identifier
] )Return a result pointer containing the databases available from the current fbsql daemon. Use the fbsql_tablename() to traverse this result pointer.
Parametry
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
Zwracane wartości
Returns a result pointer or FALSE on error.
Przykłady
Przykład #1 fbsql_list_dbs() example
<?php
$link = fbsql_connect('localhost', 'myname', 'secret');
$db_list = fbsql_list_dbs($link);
while ($row = fbsql_fetch_object($db_list)) {
echo $row->Database . "\n";
}
?>
Powyższy przykład wyświetli coś podobnego do:
database1 database2 database3 ...
Informacja:
The above code would just as easily work with fbsql_fetch_row() or other similar functions.
Zobacz też:
- fbsql_list_fields() - List FrontBase result fields
- fbsql_list_tables() - List tables in a FrontBase database
fbsql_list_fields
(PHP 4 >= 4.0.6, PHP 5)
fbsql_list_fields — List FrontBase result fields
Opis
$database_name
, string $table_name
[, resource $link_identifier
] )Retrieves information about the given table.
Parametry
-
database_name -
The database name.
-
table_name -
The table name.
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
Zwracane wartości
Returns a result pointer which can be used with the
fbsql_field_xxx functions, or FALSE on error.
Błędy/Wyjątki
A string describing the error will be placed in $phperrmsg, and unless the function was called as @fbsql() then this error string will also be printed out.
Przykłady
Przykład #1 fbsql_list_fields() example
<?php
$link = fbsql_connect('localhost', 'myname', 'secret');
$fields = fbsql_list_fields("database1", "table1", $link);
$columns = fbsql_num_fields($fields);
for ($i = 0; $i < $columns; $i++) {
echo fbsql_field_name($fields, $i) . "\n";;
}
?>
Powyższy przykład wyświetli coś podobnego do:
field1 field2 field3 ...
Zobacz też:
- fbsql_field_len() - Returns the length of the specified field
- fbsql_field_name() - Get the name of the specified field in a result
- fbsql_field_type() - Get the type of the specified field in a result
- fbsql_field_flags() - Get the flags associated with the specified field in a result
fbsql_list_tables
(PHP 4 >= 4.0.6, PHP 5)
fbsql_list_tables — List tables in a FrontBase database
Opis
$database
[, resource $link_identifier
] )
Returns a result pointer describing the database.
Parametry
-
database -
The database name.
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
Zwracane wartości
Returns a result pointer which can be used with the
fbsql_tablename() function to read the actual table
names, or FALSE on error.
Zobacz też:
- fbsql_list_fields() - List FrontBase result fields
- fbsql_list_dbs() - List databases available on a FrontBase server
fbsql_next_result
(PHP 4 >= 4.0.6, PHP 5)
fbsql_next_result — Move the internal result pointer to the next result
Opis
$result
)When sending more than one SQL statement to the server or executing a stored procedure with multiple results will cause the server to return multiple result sets. This function will test for additional results available form the server. If an additional result set exists it will free the existing result set and prepare to fetch the words from the new result set.
Zwracane wartości
Returns TRUE if an additional result set was available or FALSE
otherwise.
Przykłady
Przykład #1 fbsql_next_result() example
<?php
$link = fbsql_connect("localhost", "_SYSTEM", "secret");
fbsql_select_db("MyDB", $link);
$SQL = "Select * from table1; select * from table2;";
$rs = fbsql_query($SQL, $link);
do {
while ($row = fbsql_fetch_row($rs)) {
}
} while (fbsql_next_result($rs));
fbsql_free_result($rs);
fbsql_close($link);
?>
fbsql_num_fields
(PHP 4 >= 4.0.6, PHP 5)
fbsql_num_fields — Get number of fields in result
Opis
$result
)
Returns the number of fields in the given result
set.
Zwracane wartości
Returns the number of fields, as an integer.
Zobacz też:
- fbsql_db_query() - Send a FrontBase query
- fbsql_query() - Wysyła zapytanie do serwera FrontBase
- fbsql_fetch_field() - Get column information from a result and return as an object
- fbsql_num_rows() - Get number of rows in result
fbsql_num_rows
(PHP 4 >= 4.0.6, PHP 5)
fbsql_num_rows — Get number of rows in result
Opis
$result
)
Gets the number of rows in the given result set.
This function is only valid for SELECT statements. To retrieve the number of rows returned from a INSERT, UPDATE or DELETE query, use fbsql_affected_rows().
Zwracane wartości
Returns the number of rows returned by the last SELECT statement.
Przykłady
Przykład #1 fbsql_num_rows() example
<?php
$link = fbsql_connect("localhost", "username", "password");
fbsql_select_db("database", $link);
$result = fbsql_query("SELECT * FROM table1;", $link);
$num_rows = fbsql_num_rows($result);
echo "$num_rows Rows\n";
?>
Zobacz też:
- fbsql_affected_rows() - Get number of affected rows in previous FrontBase operation
- fbsql_connect() - Otwiera połączenie z serwerem FrontBase
- fbsql_select_db() - Select a FrontBase database
- fbsql_query() - Wysyła zapytanie do serwera FrontBase
fbsql_password
(PHP 4 >= 4.0.6, PHP 5)
fbsql_password — Zwraca lub ustawia hasło użytkownika używane w połączeniu
Opis
$identyfikator_połączenia
[, string $hasło
] )Zwraca lub ustawia hasło użytkownika używane w połączeniu.
Parametry
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
-
hasło -
Jeśli zostanie podane, to będzie nowym hasłem w połączeniu.
Zwracane wartości
Zwraca bieżące hasło używane w połączeniu.
Zobacz też:
- fbsql_username() - Zraca lub ustawia nazwę użytkownika używaną w połączeniu
- fbsql_hostname() - Zraca lub ustawia nazwę hosta używaną w połączeniu
fbsql_pconnect
(PHP 4 >= 4.0.6, PHP 5)
fbsql_pconnect — Otwiera stałe połączenie z serwerem FrontBase
Opis
$nazwa_hosta = ini_get("fbsql.default_host")
[, string $użytkownik = ini_get("fbsql.default_user")
[, string $hasło = ini_get("fbsql.default_password")
]]] )Nawiązuje stałe połączenie z serwerem FrontBase.
Aby ustawić numer portu należy użyć fbsql_select_db().
fbsql_pconnect() zachowuje się prawie jak fbsql_connect() z dwoma zasadniczymi różnicami:
Pierwsza, podczas łączenia funkcja najpierw spróbuje znaleźć połączenie (stałe), już otwarte dla tych samych parametrów (host, użytkownik, hasło). Jeżeli je znajdzie, to jego identyfikator zostanie zwrócony zamiast otwierania nowego połączenia.
Druga, połączenie z serwerem FrontBase nie zostanie zamknięte po zakończeniu wykonywania skryptu. Zamiast tego połączenie pozostanie otwarte do późniejszego użycia.
Dlatego też ten typ połączeń nazywany jest 'stałym'.
Parametry
-
nazwa_hosta -
Nazwa hosta, na którym jest uruchomiony serwer.
-
użytkownik -
Nazwa użytkownika do nawiązania połączenia.
-
hasło -
Hasło do nawiązania połączenia.
Zwracane wartości
Zwraca identyfikator stałego połączenia do FrontBase w przypadku sukcesu
lub FALSE w przypadku błędu.
fbsql_query
(PHP 4 >= 4.0.6, PHP 5)
fbsql_query — Wysyła zapytanie do serwera FrontBase
Opis
$zapytanie
[, resource $identyfikator_połączenia
[, int $rozmiar_partii_danych
]] )
Wysyła zapytanie do bieżącej bazy danych na
serwerze.
Jeśli wykonanie zapytania się powiedzie, możemy wywołać fbsql_num_rows() aby się dowiedzieć jak dużo wierszy zostało zwróconych przez instrukcję SELECT, lub fbsql_affected_rows() żeby wykryć ile wierszy zostało przetworzonych przez instrukcję DELETE, INSERT, REPLACE, lub UPDATE.
Parametry
-
zapytanie -
Zapytanie SQL do wykonania.
Informacja:
Zapytanie powinno zawsze kończyć się średnikiem.
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
-
rozmiar_partii_danych -
Zwracane wartości
fbsql_query() zwraca TRUE (nie zero) lub FALSE
aby wskazać, czy zapytanie zostało wykonane prawidłowo. Zwrócenie
TRUE oznacza, że zapytanie było prawidłowe i mogło zostać wykonane
przez serwer. Funkcja nie informuje o liczbie przetworzonych
lub zwróconych wieszy. Jest całkiem możliwe, że zapytanie było
prawidłowe, jednak nie przetworzyło ani nie zwróciło żadnych wierszy.
Dla instrukcji SELECT fbsql_query() zwraca nowy identyfikator wyniku, który możemy przekazać do fbsql_result().
fbsql_query() może się nie powieść i zwrócić FALSE jeśli
nie mamy uprawnień dostępu do tabel określonych w zapytaniu.
Przykłady
Poniższe zapytanie ma nieprawidłową składnię, a zatem wywołanie
fbsql_query() się nie powiedzie i zwróci FALSE:
Przykład #1 Przykład fbsql_query()
<?php
$result = fbsql_query("SELECT * WHERE 1=1")
or die ("Nieprawidłowe zapytanie");
?>
Poniższe zapytanie ma nieprawidłową składnię, jeżeli
kolumna nie jest kolumną w tabeli
tabela, tak więc wywołanie fbsql_query()
się nie powiedzie i zwróci FALSE:
Przykład #2 Przykład fbsql_query()
<?php
$result = fbsql_query ("SELECT kolumna FROM tabela;")
or die ("Nieprawidłowe zapytanie");
?>
Zobacz też:
- fbsql_affected_rows() - Get number of affected rows in previous FrontBase operation
- fbsql_db_query() - Send a FrontBase query
- fbsql_free_result() - Zwalnia pamięć zajmowaną przez wynik
- fbsql_result() - Get result data
- fbsql_select_db() - Select a FrontBase database
- fbsql_connect() - Otwiera połączenie z serwerem FrontBase
fbsql_read_blob
(PHP 4 >= 4.2.0, PHP 5)
fbsql_read_blob — Read a BLOB from the database
Opis
$blob_handle
[, resource $link_identifier
] )Reads BLOB data from the database.
If a select statement contains BLOB and/or CLOB columns FrontBase will return the data directly when data is fetched. This default behavior can be changed with fbsql_set_lob_mode() so the fetch functions will return handles to BLOB and CLOB data. If a handle is fetched a user must call fbsql_read_blob() to get the actual BLOB data from the database.
Parametry
-
blob_handle -
A BLOB handle, returned by fbsql_create_blob().
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
Zwracane wartości
Returns a string containing the specified BLOB data.
Przykłady
Przykład #1 fbsql_read_blob() example
<?php
$link = fbsql_pconnect("localhost", "_SYSTEM", "secret")
or die("Could not connect");
$sql = "SELECT BLOB_COLUMN FROM BLOB_TABLE;";
$rs = fbsql_query($sql, $link);
$row_data = fbsql_fetch_row($rs);
// $row_data[0] will now contain the blob data for the first row
fbsql_free_result($rs);
$rs = fbsql_query($sql, $link);
fbsql_set_lob_mode($rs, FBSQL_LOB_HANDLE);
$row_data = fbsql_fetch_row($rs);
// $row_data[0] will now contain a handle to the BLOB data in the first row
$blob_data = fbsql_read_blob($row_data[0]);
fbsql_free_result($rs);
?>
Zobacz też:
- fbsql_create_blob() - Create a BLOB
- fbsql_read_clob() - Read a CLOB from the database
- fbsql_set_lob_mode() - Set the LOB retrieve mode for a FrontBase result set
fbsql_read_clob
(PHP 4 >= 4.2.0, PHP 5)
fbsql_read_clob — Read a CLOB from the database
Opis
$clob_handle
[, resource $link_identifier
] )Reads CLOB data from the database.
If a select statement contains BLOB and/or CLOB columns FrontBase will return the data directly when data is fetched. This default behavior can be changed with fbsql_set_lob_mode() so the fetch functions will return handles to BLOB and CLOB data. If a handle is fetched a user must call fbsql_read_clob() to get the actual CLOB data from the database.
Parametry
-
clob_handle -
A CLOB handle, returned by fbsql_create_clob().
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
Zwracane wartości
Returns a string containing the specified CLOB data.
Przykłady
Przykład #1 fbsql_read_clob() example
<?php
$link = fbsql_pconnect("localhost", "_SYSTEM", "secret")
or die("Could not connect");
$sql = "SELECT CLOB_COLUMN FROM CLOB_TABLE;";
$rs = fbsql_query($sql, $link);
$row_data = fbsql_fetch_row($rs);
// $row_data[0] will now contain the clob data for the first row
fbsql_free_result($rs);
$rs = fbsql_query($sql, $link);
fbsql_set_lob_mode($rs, FBSQL_LOB_HANDLE);
$row_data = fbsql_fetch_row($rs);
// $row_data[0] will now contain a handle to the CLOB data in the first row
$clob_data = fbsql_read_clob($row_data[0]);
fbsql_free_result($rs);
?>
Zobacz też:
- fbsql_create_clob() - Create a CLOB
- fbsql_read_blob() - Read a BLOB from the database
- fbsql_set_lob_mode() - Set the LOB retrieve mode for a FrontBase result set
fbsql_result
(PHP 4 >= 4.0.6, PHP 5)
fbsql_result — Get result data
Opis
Returns the contents of one cell from a FrontBase
result set.
When working on large result sets, you should consider using one of the functions that fetch an entire row (specified below). As these functions return the contents of multiple cells in one function call, they're MUCH quicker than fbsql_result().
Calls to fbsql_result() should not be mixed with calls to other functions that deal with the result set.
Parametry
-
result -
Identyfikator wyniku zwrócony przez fbsql_query() lub fbsql_db_query().
-
row -
-
field -
Can be the field's offset, or the field's name, or the field's table dot field's name (tablename.fieldname).
If the column name has been aliased ('select foo as bar from...'), use the alias instead of the column name.
Informacja:
Specifying a numeric offset for the field argument is much quicker than specifying a fieldname or tablename.fieldname argument.
Zwracane wartości
Zobacz też:
Recommended high-performance alternatives:
- fbsql_fetch_row() - Get a result row as an enumerated array
- fbsql_fetch_array() - Fetch a result row as an associative array, a numeric array, or both
- fbsql_fetch_assoc() - Fetch a result row as an associative array
- fbsql_fetch_object() - Fetch a result row as an object
fbsql_rollback
(PHP 4 >= 4.0.6, PHP 5)
fbsql_rollback — Rollback a transaction to the database
Opis
$link_identifier
] )Ends the current transaction by rolling back all statements issued since last commit.
This command is only needed if autocommit is set to false.
Parametry
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- fbsql_autocommit() - Enable or disable autocommit
- fbsql_commit() - Commits a transaction to the database
fbsql_rows_fetched
(PHP 5 >= 5.1.0)
fbsql_rows_fetched — Get the number of rows affected by the last statement
Opis
$result
)Gets the number of rows affected by the last statement.
Zwracane wartości
Returns the number of rows, as an integer.
fbsql_select_db
(PHP 4 >= 4.0.6, PHP 5)
fbsql_select_db — Select a FrontBase database
Opis
$database_name
[, resource $link_identifier
]] )Sets the current active database on the given link identifier.
The client contacts FBExec to obtain the port number to use for the connection to the database. If the database name is a number the system will use that as a port number and it will not ask FBExec for the port number. The FrontBase server can be stared as FRontBase -FBExec=No -port=<port number> <database name>.
Every subsequent call to fbsql_query() will be made on the active database.
Parametry
-
database_name -
The name of the database to be selected.
If the database is protected with a database password, the you must call fbsql_database_password() before selecting the database.
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- fbsql_connect() - Otwiera połączenie z serwerem FrontBase
- fbsql_pconnect() - Otwiera stałe połączenie z serwerem FrontBase
- fbsql_database_password() - Sets or retrieves the password for a FrontBase database
- fbsql_query() - Wysyła zapytanie do serwera FrontBase
fbsql_set_characterset
(PHP 5 >= 5.1.0)
fbsql_set_characterset — Zmienia kodowanie znaków na wejściu/wyjściu
Opis
$identyfikator_połączenia
, int $kodowanie_znaków
[, int $w_obie_strony
] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Zwracane wartości
Nie jest zwracana żadna wartość.
fbsql_set_lob_mode
(PHP 4 >= 4.2.0, PHP 5)
fbsql_set_lob_mode — Set the LOB retrieve mode for a FrontBase result set
Opis
$result
, int $lob_mode
)Sets the mode for retrieving LOB data from the database.
When BLOB and CLOB data is retrieved in FrontBase it can be retrieved direct or indirect. Direct retrieved LOB data will always be fetched no matter the setting of the lob mode. If the LOB data is less than 512 bytes it will always be retrieved directly.
Parametry
-
result -
Identyfikator wyniku zwrócony przez fbsql_query() lub fbsql_db_query().
-
lob_mode -
Can be one of:
-
FBSQL_LOB_DIRECT- LOB data is retrieved directly. When data is fetched from the database with fbsql_fetch_row(), and other fetch functions, all CLOB and BLOB columns will be returned as ordinary columns. This is the default value on a new FrontBase result. -
FBSQL_LOB_HANDLE- LOB data is retrieved as handles to the data. When data is fetched from the database with fbsql_fetch_row(), and other fetch functions, LOB data will be returned as a handle to the data if the data is stored indirect or the data if it is stored direct. If a handle is returned it will be a 27 byte string formatted as @'000000000000000000000000'.
-
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- fbsql_create_blob() - Create a BLOB
- fbsql_create_clob() - Create a CLOB
- fbsql_read_blob() - Read a BLOB from the database
- fbsql_read_clob() - Read a CLOB from the database
fbsql_set_password
(PHP 5)
fbsql_set_password — Change the password for a given user
Opis
$link_identifier
, string $user
, string $password
, string $old_password
)
Changes the password for the given user.
Parametry
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
-
user -
The user name.
-
password -
The new password to be set.
-
old_password -
The old password to be replaced.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
fbsql_set_transaction
(PHP 4 >= 4.2.0, PHP 5)
fbsql_set_transaction — Set the transaction locking and isolation
Opis
$link_identifier
, int $locking
, int $isolation
)
Sets the transaction locking and
isolation.
Parametry
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
-
locking -
The type of locking to be set. It can be one of the following constants:
FBSQL_LOCK_DEFERRED,FBSQL_LOCK_OPTIMISTIC, orFBSQL_LOCK_PESSIMISTIC. -
isolation -
The type of isolation to be set. It can be one of the following constants:
FBSQL_ISO_READ_UNCOMMITTED,FBSQL_ISO_READ_COMMITTED,FBSQL_ISO_REPEATABLE_READ,FBSQL_ISO_SERIALIZABLE, orFBSQL_ISO_VERSIONED.
Zwracane wartości
Nie jest zwracana żadna wartość.
fbsql_start_db
(PHP 4 >= 4.0.6, PHP 5)
fbsql_start_db — Uruchamia bazę danych na serwerze lokalnym lub zdalnym
Opis
$nazwa_bazy_danych
[, resource $identyfikator_połączenia
[, string $opcje
]] )Uruchamia bazę danych na serwerze lokalnym lub zdalnym.
Parametry
-
nazwa_bazy_danych -
Nazwa bazy danych.
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
-
opcje -
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- fbsql_db_status() - Zwraca status dla podanej bazy danych
- fbsql_stop_db() - Zatrzymuje bazę danych na serwerze lokalnym lub zdalnym
fbsql_stop_db
(PHP 4 >= 4.0.6, PHP 5)
fbsql_stop_db — Zatrzymuje bazę danych na serwerze lokalnym lub zdalnym
Opis
$nazwa_bazy_danych
[, resource $identyfikator_połączenia
] )Zatrzymuje bazę danych na serwerze lokalnym lub zdalnym.
Parametry
-
nazwa_bazy_danych -
Nazwa bazy danych.
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- fbsql_db_status() - Zwraca status dla podanej bazy danych
- fbsql_start_db() - Uruchamia bazę danych na serwerze lokalnym lub zdalnym
fbsql_table_name
(PHP 4 >= 4.2.0, PHP 5)
fbsql_table_name — Get table name of field
Opis
$result
, int $index
)
fbsql_table_name() gets the name of the current table in
the given result set.
The fbsql_num_rows() function may be used to determine the number of tables in the result pointer.
Parametry
-
result -
A result pointer returned by fbsql_list_tables().
-
index -
Integer index for the current table.
Zwracane wartości
Returns the name of the table, as a string.
Przykłady
Przykład #1 fbsql_table_name() example
<?php
fbsql_connect("localhost", "_SYSTEM", "");
$result = fbsql_list_tables("wisconsin");
$i = 0;
while ($i < fbsql_num_rows($result)) {
$tb_names[$i] = fbsql_table_name($result, $i);
echo $tb_names[$i] . "<br />";
$i++;
}
?>
Opis
Ta funkcja jest aliasem dla: fbsql_table_name().
fbsql_username
(PHP 4 >= 4.0.6, PHP 5)
fbsql_username — Zraca lub ustawia nazwę użytkownika używaną w połączeniu
Opis
$identyfikator_połączenia
[, string $nazwa_użytkownika
] )Zraca lub ustawia nazwę użytkownika używaną w połączeniu.
Parametry
-
link_identifier -
Identyfikator połączenia FrontBase zwrócony przez fbsql_connect() lub fbsql_pconnect().
Link jest opcjonalny i jeśli nie zostanie podany, to funkcja spróbuje znaleźć otwarte połączenie do serwera FrontBase. Jeśli funkcja nie znajdzie otwartego połączenia, to spróbuje utworzyć je tak jakby fbsql_connect() była wywołana bez argumentów.
-
nazwa_użytkownika -
Jeśli zostanie podana, wówczas będzie nowym użytkownikiem w połączeniu.
Zwracane wartości
Zwraca jako string nazwę aktualnego użytkownka używanego w połączeniu.
Zobacz też:
- fbsql_password() - Zwraca lub ustawia hasło użytkownika używane w połączeniu
- fbsql_hostname() - Zraca lub ustawia nazwę hosta używaną w połączeniu
fbsql_warnings
(PHP 4 >= 4.0.6, PHP 5)
fbsql_warnings — Enable or disable FrontBase warnings
Opis
$OnOff
] )Enables or disables FrontBase warnings.
Parametry
-
OnOff -
Whether to enable warnings or no.
Zwracane wartości
Returns TRUE if warnings is turned on, FALSE otherwise.
Zobacz też:
- fbsql_errno() - Returns the error number from previous operation
- fbsql_error() - Returns the error message from previous operation
Spis treści
- fbsql_affected_rows — Get number of affected rows in previous FrontBase operation
- fbsql_autocommit — Enable or disable autocommit
- fbsql_blob_size — Get the size of a BLOB
- fbsql_change_user — Change logged in user of the active connection
- fbsql_clob_size — Get the size of a CLOB
- fbsql_close — Zamyka połączenie z serwerem FrontBase
- fbsql_commit — Commits a transaction to the database
- fbsql_connect — Otwiera połączenie z serwerem FrontBase
- fbsql_create_blob — Create a BLOB
- fbsql_create_clob — Create a CLOB
- fbsql_create_db — Create a FrontBase database
- fbsql_data_seek — Move internal result pointer
- fbsql_database_password — Sets or retrieves the password for a FrontBase database
- fbsql_database — Get or set the database name used with a connection
- fbsql_db_query — Send a FrontBase query
- fbsql_db_status — Zwraca status dla podanej bazy danych
- fbsql_drop_db — Drop (delete) a FrontBase database
- fbsql_errno — Returns the error number from previous operation
- fbsql_error — Returns the error message from previous operation
- fbsql_fetch_array — Fetch a result row as an associative array, a numeric array, or both
- fbsql_fetch_assoc — Fetch a result row as an associative array
- fbsql_fetch_field — Get column information from a result and return as an object
- fbsql_fetch_lengths — Get the length of each output in a result
- fbsql_fetch_object — Fetch a result row as an object
- fbsql_fetch_row — Get a result row as an enumerated array
- fbsql_field_flags — Get the flags associated with the specified field in a result
- fbsql_field_len — Returns the length of the specified field
- fbsql_field_name — Get the name of the specified field in a result
- fbsql_field_seek — Set result pointer to a specified field offset
- fbsql_field_table — Zwraca nazwę tabeli dla określonego pola
- fbsql_field_type — Get the type of the specified field in a result
- fbsql_free_result — Zwalnia pamięć zajmowaną przez wynik
- fbsql_get_autostart_info — Pobiera informacje o bazach automatycznie uruchamianych podczas startu serwera
- fbsql_hostname — Zraca lub ustawia nazwę hosta używaną w połączeniu
- fbsql_insert_id — Get the id generated from the previous INSERT operation
- fbsql_list_dbs — List databases available on a FrontBase server
- fbsql_list_fields — List FrontBase result fields
- fbsql_list_tables — List tables in a FrontBase database
- fbsql_next_result — Move the internal result pointer to the next result
- fbsql_num_fields — Get number of fields in result
- fbsql_num_rows — Get number of rows in result
- fbsql_password — Zwraca lub ustawia hasło użytkownika używane w połączeniu
- fbsql_pconnect — Otwiera stałe połączenie z serwerem FrontBase
- fbsql_query — Wysyła zapytanie do serwera FrontBase
- fbsql_read_blob — Read a BLOB from the database
- fbsql_read_clob — Read a CLOB from the database
- fbsql_result — Get result data
- fbsql_rollback — Rollback a transaction to the database
- fbsql_rows_fetched — Get the number of rows affected by the last statement
- fbsql_select_db — Select a FrontBase database
- fbsql_set_characterset — Zmienia kodowanie znaków na wejściu/wyjściu
- fbsql_set_lob_mode — Set the LOB retrieve mode for a FrontBase result set
- fbsql_set_password — Change the password for a given user
- fbsql_set_transaction — Set the transaction locking and isolation
- fbsql_start_db — Uruchamia bazę danych na serwerze lokalnym lub zdalnym
- fbsql_stop_db — Zatrzymuje bazę danych na serwerze lokalnym lub zdalnym
- fbsql_table_name — Get table name of field
- fbsql_tablename — Alias dla fbsql_table_name
- fbsql_username — Zraca lub ustawia nazwę użytkownika używaną w połączeniu
- fbsql_warnings — Enable or disable FrontBase warnings
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Funkcje FrontBase
- fbsql_affected_rows — Get number of affected rows in previous FrontBase operation
- fbsql_autocommit — Enable or disable autocommit
- fbsql_blob_size — Get the size of a BLOB
- fbsql_change_user — Change logged in user of the active connection
- fbsql_clob_size — Get the size of a CLOB
- fbsql_close — Zamyka połączenie z serwerem FrontBase
- fbsql_commit — Commits a transaction to the database
- fbsql_connect — Otwiera połączenie z serwerem FrontBase
- fbsql_create_blob — Create a BLOB
- fbsql_create_clob — Create a CLOB
- fbsql_create_db — Create a FrontBase database
- fbsql_data_seek — Move internal result pointer
- fbsql_database_password — Sets or retrieves the password for a FrontBase database
- fbsql_database — Get or set the database name used with a connection
- fbsql_db_query — Send a FrontBase query
- fbsql_db_status — Zwraca status dla podanej bazy danych
- fbsql_drop_db — Drop (delete) a FrontBase database
- fbsql_errno — Returns the error number from previous operation
- fbsql_error — Returns the error message from previous operation
- fbsql_fetch_array — Fetch a result row as an associative array, a numeric array, or both
- fbsql_fetch_assoc — Fetch a result row as an associative array
- fbsql_fetch_field — Get column information from a result and return as an object
- fbsql_fetch_lengths — Get the length of each output in a result
- fbsql_fetch_object — Fetch a result row as an object
- fbsql_fetch_row — Get a result row as an enumerated array
- fbsql_field_flags — Get the flags associated with the specified field in a result
- fbsql_field_len — Returns the length of the specified field
- fbsql_field_name — Get the name of the specified field in a result
- fbsql_field_seek — Set result pointer to a specified field offset
- fbsql_field_table — Zwraca nazwę tabeli dla określonego pola
- fbsql_field_type — Get the type of the specified field in a result
- fbsql_free_result — Zwalnia pamięć zajmowaną przez wynik
- fbsql_get_autostart_info — Pobiera informacje o bazach automatycznie uruchamianych podczas startu serwera
- fbsql_hostname — Zraca lub ustawia nazwę hosta używaną w połączeniu
- fbsql_insert_id — Get the id generated from the previous INSERT operation
- fbsql_list_dbs — List databases available on a FrontBase server
- fbsql_list_fields — List FrontBase result fields
- fbsql_list_tables — List tables in a FrontBase database
- fbsql_next_result — Move the internal result pointer to the next result
- fbsql_num_fields — Get number of fields in result
- fbsql_num_rows — Get number of rows in result
- fbsql_password — Zwraca lub ustawia hasło użytkownika używane w połączeniu
- fbsql_pconnect — Otwiera stałe połączenie z serwerem FrontBase
- fbsql_query — Wysyła zapytanie do serwera FrontBase
- fbsql_read_blob — Read a BLOB from the database
- fbsql_read_clob — Read a CLOB from the database
- fbsql_result — Get result data
- fbsql_rollback — Rollback a transaction to the database
- fbsql_rows_fetched — Get the number of rows affected by the last statement
- fbsql_select_db — Select a FrontBase database
- fbsql_set_characterset — Zmienia kodowanie znaków na wejściu/wyjściu
- fbsql_set_lob_mode — Set the LOB retrieve mode for a FrontBase result set
- fbsql_set_password — Change the password for a given user
- fbsql_set_transaction — Set the transaction locking and isolation
- fbsql_start_db — Uruchamia bazę danych na serwerze lokalnym lub zdalnym
- fbsql_stop_db — Zatrzymuje bazę danych na serwerze lokalnym lub zdalnym
- fbsql_table_name — Get table name of field
- fbsql_tablename — Alias dla fbsql_table_name
- fbsql_username — Zraca lub ustawia nazwę użytkownika używaną w połączeniu
- fbsql_warnings — Enable or disable FrontBase warnings
IBM DB2, Cloudscape and Apache Derby
Wstęp
These functions enable you to access IBM DB2 Universal Database, IBM Cloudscape, and Apache Derby databases using the DB2 Call Level Interface (DB2 CLI).
Instalacja/Konfiguracja
Spis treści
Wymagania
To connect to IBM DB2 Universal Database for Linux, UNIX, and Windows, or IBM Cloudscape, or Apache Derby, you must install an IBM DB2 Universal Database client on the same computer on which you are running PHP. The extension has been developed and tested with DB2 Version 8.2.
To connect to IBM DB2 Universal Database for z/OS or iSeries, you also require IBM DB2 Connect or the equivalent DRDA gateway software.
Requirements on Linux or Unix
The user invoking the PHP executable or SAPI must specify the DB2 instance before accessing these functions. You can set the name of the DB2 instance in php.ini using the ibm_db2.instance_name configuration option, or you can source the DB2 instance profile before invoking the PHP executable.
If you created a DB2 instance named db2inst1 in /home/db2inst1/, for example, you can add the following line to php.ini:
ibm_db2.instance_name=db2inst1
bash$ source /home/db2inst1/sqllib/db2profile
Instalacja
To build the ibm_db2 extension, the DB2 application development header files and libraries must be installed on your system. DB2 does not install these by default, so you may have to return to your DB2 installer and add this option. The header files are included with the DB2 Application Development Client freely available for download from the IBM DB2 Universal Database » support site.
If you add the DB2 application development header files and libraries to a Linux or Unix operating system on which DB2 was already installed, you must issue the command db2iupdt -e to update the symbolic links to the header files and libraries in your DB2 instances.
ibm_db2 is a » PECL extension, so follow the instructions in Installation of PECL extensions to install the ibm_db2 extension for PHP. Issue the configure command to point to the location of your DB2 header files and libraries as follows:
bash$ ./configure --with-IBM_DB2=/path/to/DB2
Informacja: Note for IIS users
If you are using the ibm_db2 driver with Microsoft Internet Information Server (IIS) you may have to do the following:
- Install DB2 with extended operating system security.
- Add the PHP binary path to the PATH system environment variable (default C:\php\).
- Create another system environment variable equal to the path where the PHP.INI file is located (eg: PHPRC = C:\php\).
- Add the IUSR_COMPUTERNAME to the DB2USERS group.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Changelog |
|---|---|---|---|
| ibm_db2.binmode | "1" | PHP_INI_ALL | |
| ibm_db2.i5_all_pconnect | "0" | PHP_INI_SYSTEM | Available since ibm_db2 1.6.5. |
| ibm_db2.i5_allow_commit | "0" | PHP_INI_SYSTEM | Available since ibm_db2 1.4.9. |
| ibm_db2.i5_dbcs_alloc | "0" | PHP_INI_SYSTEM | Available since ibm_db2 1.5.0. |
| ibm_db2.instance_name | NULL | PHP_INI_SYSTEM | Available since ibm_db2 1.0.2. |
| ibm_db2.i5_ignore_userid | "0" | PHP_INI_SYSTEM | Available since ibm_db2 1.8.0. |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
ibm_db2.binmodeinteger -
This option controls the mode used for converting to and from binary data in the PHP application.
-
1 (DB2_BINARY)
-
2 (DB2_CONVERT)
-
3 (DB2_PASSTHRU)
-
-
ibm_db2.i5_all_pconnectinteger -
This option overrides i5 db2_connect() full open and close in the PHP application. When
ibm_db2.i5_all_pconnect= 1, all db2 connections become persistent (db2_pconnect()). On i5/OS, db2_pconnect() performs dramatically better with lower machine stress over db2_connect(). This is a convenience override of db2_connect() to evoke db2_pconnect() without PHP source code changes.-
0 db2_connect() default full open and close
-
1 db2_connect() override to db2_pconnect() for persistent connection only
-
-
ibm_db2.i5_allow_commitinteger -
This option controls the commit mode used for i5 schema collections in the PHP application.
-
0 no commit (see
i5_commitfor override) -
1 allow commit (see
i5_commitfor override)
-
-
ibm_db2.i5_dbcs_allocinteger -
This option controls the internal ibm_db2 allocation scheme for large DBCS column buffers.
-
0 no expanded allocations (see
i5_dbcs_allocfor override) -
1 use expanded allocations (see
i5_dbcs_allocfor override)
-
-
ibm_db2.instance_namestring -
On Linux and UNIX operating systems, this option defines the name of the instance to use for cataloged database connections. If this option is set, its value overrides the DB2INSTANCE environment variable setting.
This option is ignored on Windows operating systems.
-
ibm_db2.i5_ignore_useridinteger -
This option overrides i5 db2_(p)connect userid and password in the PHP application. When
ibm_db2.i5_ignore_userid= 1, all db2 (p)connections become null userid and null password. Therefore Apache jobs connect with the current profile (NOBODY). Use of this override is only for simple DB2 based websites that never require profile switching and therefore can avoid all overhead of server mode additional QSQSRVR jobs. This is a convenience override of db2_(p)connect to set the userid and password values to null without PHP source code changes. This override can be used in combination withibm_db2.i5_all_pconnect= 1.-
0 db2_(p)connect with specified userid and password
-
1 db2_(p)connect override connect with null userid and null password
-
Typy zasobów
The ibm_db2 extension returns connection resources, statement resources, and result set resources.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
-
DB2_BINARY(integer) - Specifies that binary data shall be returned as is. This is the default mode.
-
DB2_CONVERT(integer) - Specifies that binary data shall be converted to a hexadecimal encoding and returned as an ASCII string.
-
DB2_PASSTHRU(integer) -
Specifies that binary data shall be converted to a
NULLvalue. -
DB2_SCROLLABLE(integer) - Specifies a scrollable cursor for a statement resource. This mode enables random access to rows in a result set, but currently is supported only by IBM DB2 Universal Database.
-
DB2_FORWARD_ONLY(integer) - Specifies a forward-only cursor for a statement resource. This is the default cursor type and is supported on all database servers.
-
DB2_PARAM_IN(integer) - Specifies the PHP variable should be bound as an IN parameter for a stored procedure.
-
DB2_PARAM_OUT(integer) - Specifies the PHP variable should be bound as an OUT parameter for a stored procedure.
-
DB2_PARAM_INOUT(integer) - Specifies the PHP variable should be bound as an INOUT parameter for a stored procedure.
-
DB2_PARAM_FILE(integer) - Specifies that the column should be bound directly to a file for input.
-
DB2_AUTOCOMMIT_ON(integer) - Specifies that autocommit should be turned on.
-
DB2_AUTOCOMMIT_OFF(integer) - Specifies that autocommit should be turned off.
-
DB2_DOUBLE(integer) - Specifies that the variable should be bound as a DOUBLE, FLOAT, or REAL data type.
-
DB2_LONG(integer) - Specifies that the variable should be bound as a SMALLINT, INTEGER, or BIGINT data type.
-
DB2_CHAR(integer) - Specifies that the variable should be bound as a CHAR or VARCHAR data type.
-
DB2_CASE_NATURAL(integer) - Specifies that column names will be returned in their natural case.
-
DB2_CASE_LOWER(integer) - Specifies that column names will be returned in lower case.
-
DB2_CASE_UPPER(integer) - Specifies that column names will be returned in upper case.
-
DB2_DEFERRED_PREPARE_ON(integer) - Specifies that deferred prepare should be turned on for the specified statement resource.
-
DB2_DEFERRED_PREPARE_OFF(integer) - Specifies that deferred prepare should be turned off for the specified statement resource.
IBM DB2 Funkcje
db2_autocommit
(PECL ibm_db2 >= 1.0.0)
db2_autocommit — Returns or sets the AUTOCOMMIT state for a database connection
Opis
Sets or gets the AUTOCOMMIT behavior of the specified connection resource.
Parametry
-
connection -
A valid database connection resource variable as returned from db2_connect() or db2_pconnect().
-
value -
One of the following constants:
- DB2_AUTOCOMMIT_OFF
-
Turns AUTOCOMMIT off.
- DB2_AUTOCOMMIT_ON
-
Turns AUTOCOMMIT on.
Zwracane wartości
When db2_autocommit() receives only the
connection parameter, it returns the current state
of AUTOCOMMIT for the requested connection as an integer value. A value of
0 indicates that AUTOCOMMIT is off, while a value of 1 indicates that
AUTOCOMMIT is on.
When db2_autocommit() receives both the
connection parameter and
autocommit parameter, it attempts to set the
AUTOCOMMIT state of the requested connection to the corresponding state.
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Retrieving the AUTOCOMMIT value for a connection
In the following example, a connection which has been created with AUTOCOMMIT turned off is tested with the db2_autocommit() function.
<?php
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF);
$conn = db2_connect($database, $user, $password, $options);
$ac = db2_autocommit($conn);
if ($ac == 0) {
print "$ac -- AUTOCOMMIT is off.";
} else {
print "$ac -- AUTOCOMMIT is on.";
}
?>
Powyższy przykład wyświetli:
0 -- AUTOCOMMIT is off.
Przykład #2 Setting the AUTOCOMMIT value for a connection
In the following example, a connection which was initially created with AUTOCOMMIT turned off has its behavior changed to turn AUTOCOMMIT on.
<?php
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF);
$conn = db2_connect($database, $user, $password, $options);
// Turn AUTOCOMMIT on
$rc = db2_autocommit($conn, DB2_AUTOCOMMIT_ON);
if ($rc) {
print "Turning AUTOCOMMIT on succeeded.\n";
}
// Check AUTOCOMMIT state
$ac = db2_autocommit($conn);
if ($ac == 0) {
print "$ac -- AUTOCOMMIT is off.";
} else {
print "$ac -- AUTOCOMMIT is on.";
}
?>
Powyższy przykład wyświetli:
Turning AUTOCOMMIT on succeeded. 1 -- AUTOCOMMIT is on.
Zobacz też:
- db2_connect() - Returns a connection to a database
- db2_pconnect() - Returns a persistent connection to a database
db2_bind_param
(PECL ibm_db2 >= 1.0.0)
db2_bind_param — Binds a PHP variable to an SQL statement parameter
Opis
$stmt
, int $parameter-number
, string $variable-name
[, int $parameter-type
[, int $data-type = 0
[, int $precision = -1
[, int $scale = 0
]]]] )Binds a PHP variable to an SQL statement parameter in a statement resource returned by db2_prepare(). This function gives you more control over the parameter type, data type, precision, and scale for the parameter than simply passing the variable as part of the optional input array to db2_execute().
Parametry
-
stmt -
A prepared statement returned from db2_prepare().
-
parameter-number -
Specifies the 1-indexed position of the parameter in the prepared statement.
-
variable-name -
A string specifying the name of the PHP variable to bind to the parameter specified by
parameter-number. -
parameter-type -
A constant specifying whether the PHP variable should be bound to the SQL parameter as an input parameter (DB2_PARAM_IN), an output parameter (DB2_PARAM_OUT), or as a parameter that accepts input and returns output (DB2_PARAM_INOUT). To avoid memory overhead, you can also specify DB2_PARAM_FILE to bind the PHP variable to the name of a file that contains large object (BLOB, CLOB, or DBCLOB) data.
-
data-type -
A constant specifying the SQL data type that the PHP variable should be bound as: one of DB2_BINARY, DB2_CHAR, DB2_DOUBLE, or DB2_LONG .
-
precision -
Specifies the precision with which the variable should be bound to the database. This parameter can also be used for retrieving XML output values from stored procedures. A non-negative value specifies the maximum size of the XML data that will be retrieved from the database. If this parameter is not used, a default of 1MB will be assumed for retrieving the XML output value from the stored procedure.
-
scale -
Specifies the scale with which the variable should be bound to the database.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Binding PHP variables to a prepared statement
The SQL statement in the following example uses two input parameters in the WHERE clause. We call db2_bind_param() to bind two PHP variables to the corresponding SQL parameters. Notice that the PHP variables do not have to be declared or assigned before the call to db2_bind_param(); in the example, $lower_limit is assigned a value before the call to db2_bind_param(), but $upper_limit is assigned a value after the call to db2_bind_param(). The variables must be bound and, for parameters that accept input, must have any value assigned, before calling db2_execute().
<?php
$sql = 'SELECT name, breed, weight FROM animals
WHERE weight > ? AND weight < ?';
$conn = db2_connect($database, $user, $password);
$stmt = db2_prepare($conn, $sql);
// We can declare the variable before calling db2_bind_param()
$lower_limit = 1;
db2_bind_param($stmt, 1, "lower_limit", DB2_PARAM_IN);
db2_bind_param($stmt, 2, "upper_limit", DB2_PARAM_IN);
// We can also declare the variable after calling db2_bind_param()
$upper_limit = 15.0;
if (db2_execute($stmt)) {
while ($row = db2_fetch_array($stmt)) {
print "{$row[0]}, {$row[1]}, {$row[2]}\n";
}
}
?>
Powyższy przykład wyświetli:
Pook, cat, 3.2 Rickety Ride, goat, 9.7 Peaches, dog, 12.3
Przykład #2 Calling stored procedures with IN and OUT parameters
The stored procedure match_animal in the following example accepts three different parameters:
-
an input (IN) parameter that accepts the name of the first animal as input
-
an input-output (INOUT) parameter that accepts the name of the second animal as input and returns the string TRUE if an animal in the database matches that name
-
an output (OUT) parameter that returns the sum of the weight of the two identified animals
<?php
$sql = 'CALL match_animal(?, ?, ?)';
$conn = db2_connect($database, $user, $password);
$stmt = db2_prepare($conn, $sql);
$name = "Peaches";
$second_name = "Rickety Ride";
$weight = 0;
db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
db2_bind_param($stmt, 2, "second_name", DB2_PARAM_INOUT);
db2_bind_param($stmt, 3, "weight", DB2_PARAM_OUT);
print "Values of bound parameters _before_ CALL:\n";
print " 1: {$name} 2: {$second_name} 3: {$weight}\n\n";
if (db2_execute($stmt)) {
print "Values of bound parameters _after_ CALL:\n";
print " 1: {$name} 2: {$second_name} 3: {$weight}\n\n";
print "Results:\n";
while ($row = db2_fetch_array($stmt)) {
print " {$row[0]}, {$row[1]}, {$row[2]}\n";
}
}
?>
Powyższy przykład wyświetli:
Values of bound parameters _before_ CALL: 1: Peaches 2: Rickety Ride 3: 0 Values of bound parameters _after_ CALL: 1: Peaches 2: TRUE 3: 22 Results: Peaches, dog, 12.3 Pook, cat, 3.2 Rickety Ride, goat, 9.7
Przykład #3 Inserting a binary large object (BLOB) directly from a file
The data for large objects are typically stored in files, such as XML documents or audio files. Rather than reading an entire file into a PHP variable, and then binding that PHP variable into an SQL statement, you can avoid some memory overhead by binding the file directly to the input parameter of your SQL statement. The following example demonstrates how to bind a file directly into a BLOB column.
<?php
$stmt = db2_prepare($conn, "INSERT INTO animal_pictures(picture) VALUES (?)");
$picture = "/opt/albums/spook/grooming.jpg";
$rc = db2_bind_param($stmt, 1, "picture", DB2_PARAM_FILE);
$rc = db2_execute($stmt);
?>
Zobacz też:
- db2_execute() - Executes a prepared SQL statement
- db2_prepare() - Prepares an SQL statement to be executed
db2_client_info
(PECL ibm_db2 >= 1.1.1)
db2_client_info — Returns an object with properties that describe the DB2 database client
Opis
$connection
)This function returns an object with read-only properties that return information about the DB2 database client. The following table lists the DB2 client properties:
| Property name | Return type | Description |
|---|---|---|
| APPL_CODEPAGE | int | The application code page. |
| CONN_CODEPAGE | int | The code page for the current connection. |
| DATA_SOURCE_NAME | string | The data source name (DSN) used to create the current connection to the database. |
| DRIVER_NAME | string | The name of the library that implements the DB2 Call Level Interface (CLI) specification. |
| DRIVER_ODBC_VER | string | The version of ODBC that the DB2 client supports. This returns a string "MM.mm" where MM is the major version and mm is the minor version. The DB2 client always returns "03.51". |
| DRIVER_VER | string | The version of the client, in the form of a string "MM.mm.uuuu" where MM is the major version, mm is the minor version, and uuuu is the update. For example, "08.02.0001" represents major version 8, minor version 2, update 1. |
| ODBC_SQL_CONFORMANCE | string |
The level of ODBC SQL grammar supported by the client:
|
| ODBC_VER | string | The version of ODBC that the ODBC driver manager supports. This returns a string "MM.mm.rrrr" where MM is the major version, mm is the minor version, and rrrr is the release. The DB2 client always returns "03.01.0000". |
Parametry
-
connection -
Specifies an active DB2 client connection.
Zwracane wartości
Returns an object on a successful call. Returns FALSE on failure.
Przykłady
Przykład #1 A db2_client_info() example
To retrieve information about the client, you must pass a valid database connection resource to db2_client_info().
<?php
$conn = db2_connect( 'SAMPLE', 'db2inst1', 'ibmdb2' );
$client = db2_client_info( $conn );
if ($client) {
echo "DRIVER_NAME: "; var_dump( $client->DRIVER_NAME );
echo "DRIVER_VER: "; var_dump( $client->DRIVER_VER );
echo "DATA_SOURCE_NAME: "; var_dump( $client->DATA_SOURCE_NAME );
echo "DRIVER_ODBC_VER: "; var_dump( $client->DRIVER_ODBC_VER );
echo "ODBC_VER: "; var_dump( $client->ODBC_VER );
echo "ODBC_SQL_CONFORMANCE: "; var_dump( $client->ODBC_SQL_CONFORMANCE );
echo "APPL_CODEPAGE: "; var_dump( $client->APPL_CODEPAGE );
echo "CONN_CODEPAGE: "; var_dump( $client->CONN_CODEPAGE );
}
else {
echo "Error retrieving client information.
Perhaps your database connection was invalid.";
}
db2_close($conn);
?>
Powyższy przykład wyświetli:
DRIVER_NAME: string(8) "libdb2.a" DRIVER_VER: string(10) "08.02.0001" DATA_SOURCE_NAME: string(6) "SAMPLE" DRIVER_ODBC_VER: string(5) "03.51" ODBC_VER: string(10) "03.01.0000" ODBC_SQL_CONFORMANCE: string(8) "EXTENDED" APPL_CODEPAGE: int(819) CONN_CODEPAGE: int(819)
Zobacz też:
- db2_server_info() - Returns an object with properties that describe the DB2 database server
db2_close
(PECL ibm_db2 >= 1.0.0)
db2_close — Closes a database connection
Opis
$connection
)This function closes a DB2 client connection created with db2_connect() and returns the corresponding resources to the database server.
If you attempt to close a persistent DB2 client connection created with db2_pconnect(), the close request is ignored and the persistent DB2 client connection remains available for the next caller.
Parametry
-
connection -
Specifies an active DB2 client connection.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Closing a connection
The following example demonstrates a successful attempt to close a connection to an IBM DB2, Cloudscape, or Apache Derby database.
<?php
$conn = db2_connect('SAMPLE', 'db2inst1', 'ibmdb2');
$rc = db2_close($conn);
if ($rc) {
echo "Connection was successfully closed.";
}
?>
Powyższy przykład wyświetli:
Connection was successfully closed.
Zobacz też:
- db2_connect() - Returns a connection to a database
- db2_pclose() - Closes a persistent database connection
- db2_pconnect() - Returns a persistent connection to a database
db2_column_privileges
(PECL ibm_db2 >= 1.0.0)
db2_column_privileges — Returns a result set listing the columns and associated privileges for a table
Opis
$connection
[, string $qualifier
[, string $schema
[, string $table-name
[, string $column-name
]]]] )Returns a result set listing the columns and associated privileges for a table.
Parametry
-
connection -
A valid connection to an IBM DB2, Cloudscape, or Apache Derby database.
-
qualifier -
A qualifier for DB2 databases running on OS/390 or z/OS servers. For other databases, pass
NULLor an empty string. -
schema -
The schema which contains the tables. To match all schemas, pass
NULLor an empty string. -
table-name -
The name of the table or view. To match all tables in the database, pass
NULLor an empty string. -
column-name -
The name of the column. To match all columns in the table, pass
NULLor an empty string.
Zwracane wartości
Returns a statement resource with a result set containing rows describing the column privileges for columns matching the specified parameters. The rows are composed of the following columns:
| Column name | Description |
|---|---|
| TABLE_CAT | Name of the catalog. The value is NULL if this table does not have catalogs. |
| TABLE_SCHEM | Name of the schema. |
| TABLE_NAME | Name of the table or view. |
| COLUMN_NAME | Name of the column. |
| GRANTOR | Authorization ID of the user who granted the privilege. |
| GRANTEE | Authorization ID of the user to whom the privilege was granted. |
| PRIVILEGE | The privilege for the column. |
| IS_GRANTABLE | Whether the GRANTEE is permitted to grant this privilege to other users. |
Zobacz też:
- db2_columns() - Returns a result set listing the columns and associated metadata for a table
- db2_foreign_keys() - Returns a result set listing the foreign keys for a table
- db2_primary_keys() - Returns a result set listing primary keys for a table
- db2_procedure_columns() - Returns a result set listing stored procedure parameters
- db2_procedures() - Returns a result set listing the stored procedures registered in a database
- db2_special_columns() - Returns a result set listing the unique row identifier columns for a table
- db2_statistics() - Returns a result set listing the index and statistics for a table
- db2_table_privileges() - Returns a result set listing the tables and associated privileges in a database
- db2_tables() - Returns a result set listing the tables and associated metadata in a database
db2_columns
(PECL ibm_db2 >= 1.0.0)
db2_columns — Returns a result set listing the columns and associated metadata for a table
Opis
$connection
[, string $qualifier
[, string $schema
[, string $table-name
[, string $column-name
]]]] )Returns a result set listing the columns and associated metadata for a table.
Parametry
-
connection -
A valid connection to an IBM DB2, Cloudscape, or Apache Derby database.
-
qualifier -
A qualifier for DB2 databases running on OS/390 or z/OS servers. For other databases, pass
NULLor an empty string. -
schema -
The schema which contains the tables. To match all schemas, pass '%'.
-
table-name -
The name of the table or view. To match all tables in the database, pass
NULLor an empty string. -
column-name -
The name of the column. To match all columns in the table, pass
NULLor an empty string.
Zwracane wartości
Returns a statement resource with a result set containing rows describing the columns matching the specified parameters. The rows are composed of the following columns:
| Column name | Description |
|---|---|
| TABLE_CAT | Name of the catalog. The value is NULL if this table does not have catalogs. |
| TABLE_SCHEM | Name of the schema. |
| TABLE_NAME | Name of the table or view. |
| COLUMN_NAME | Name of the column. |
| DATA_TYPE | The SQL data type for the column represented as an integer value. |
| TYPE_NAME | A string representing the data type for the column. |
| COLUMN_SIZE | An integer value representing the size of the column. |
| BUFFER_LENGTH | Maximum number of bytes necessary to store data from this column. |
| DECIMAL_DIGITS |
The scale of the column, or NULL where scale is not applicable.
|
| NUM_PREC_RADIX |
An integer value of either 10 (representing
an exact numeric data type), 2 (representing an
approximate numeric data type), or NULL (representing a data type for
which radix is not applicable).
|
| NULLABLE | An integer value representing whether the column is nullable or not. |
| REMARKS | Description of the column. |
| COLUMN_DEF | Default value for the column. |
| SQL_DATA_TYPE | An integer value representing the size of the column. |
| SQL_DATETIME_SUB |
Returns an integer value representing a datetime subtype code,
or NULL for SQL data types to which this does not apply.
|
| CHAR_OCTET_LENGTH |
Maximum length in octets for a character data type column, which
matches COLUMN_SIZE for single-byte character set data, or NULL for
non-character data types.
|
| ORDINAL_POSITION | The 1-indexed position of the column in the table. |
| IS_NULLABLE | A string value where 'YES' means that the column is nullable and 'NO' means that the column is not nullable. |
Zobacz też:
- db2_column_privileges() - Returns a result set listing the columns and associated privileges for a table
- db2_foreign_keys() - Returns a result set listing the foreign keys for a table
- db2_primary_keys() - Returns a result set listing primary keys for a table
- db2_procedure_columns() - Returns a result set listing stored procedure parameters
- db2_procedures() - Returns a result set listing the stored procedures registered in a database
- db2_special_columns() - Returns a result set listing the unique row identifier columns for a table
- db2_statistics() - Returns a result set listing the index and statistics for a table
- db2_table_privileges() - Returns a result set listing the tables and associated privileges in a database
- db2_tables() - Returns a result set listing the tables and associated metadata in a database
db2_commit
(PECL ibm_db2 >= 1.0.0)
db2_commit — Commits a transaction
Opis
$connection
)Commits an in-progress transaction on the specified connection resource and begins a new transaction. PHP applications normally default to AUTOCOMMIT mode, so db2_commit() is not necessary unless AUTOCOMMIT has been turned off for the connection resource.
Parametry
-
connection -
A valid database connection resource variable as returned from db2_connect() or db2_pconnect().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- db2_autocommit() - Returns or sets the AUTOCOMMIT state for a database connection
- db2_rollback() - Rolls back a transaction
db2_conn_error
(PECL ibm_db2 >= 1.0.0)
db2_conn_error — Returns a string containing the SQLSTATE returned by the last connection attempt
Opis
$connection
] )
db2_conn_error() returns an SQLSTATE value representing
the reason the last attempt to connect to a database failed. As
db2_connect() returns FALSE in the event of a failed
connection attempt, you do not pass any parameters to
db2_conn_error() to retrieve the SQLSTATE value.
If, however, the connection was successful but becomes invalid over time,
you can pass the connection parameter to retrieve
the SQLSTATE value for a specific connection.
To learn what the SQLSTATE value means, you can issue the following command
at a DB2 Command Line Processor prompt:
db2 '? . You
can also call db2_conn_errormsg() to retrieve an
explicit error message and the associated SQLCODE value.
sqlstate-value'
Parametry
-
connection -
A connection resource associated with a connection that initially succeeded, but which over time became invalid.
Zwracane wartości
Returns the SQLSTATE value resulting from a failed connection attempt. Returns an empty string if there is no error associated with the last connection attempt.
Przykłady
Przykład #1 Retrieving an SQLSTATE value for a failed connection attempt
The following example demonstrates how to return an SQLSTATE value after deliberately passing invalid parameters to db2_connect().
<?php
$conn = db2_connect('badname', 'baduser', 'badpassword');
if (!$conn) {
print "SQLSTATE value: " . db2_conn_error();
}
?>
Powyższy przykład wyświetli:
SQLSTATE value: 08001
Zobacz też:
- db2_conn_errormsg() - Returns the last connection error message and SQLCODE value
- db2_connect() - Returns a connection to a database
- db2_stmt_error() - Returns a string containing the SQLSTATE returned by an SQL statement
- db2_stmt_errormsg() - Returns a string containing the last SQL statement error message
db2_conn_errormsg
(PECL ibm_db2 >= 1.0.0)
db2_conn_errormsg — Returns the last connection error message and SQLCODE value
Opis
$connection
] )
db2_conn_errormsg() returns an error message and SQLCODE
value representing the reason the last database connection attempt failed.
As db2_connect() returns FALSE in the event of a failed
connection attempt, do not pass any parameters to
db2_conn_errormsg() to retrieve the associated error
message and SQLCODE value.
If, however, the connection was successful but becomes invalid over time,
you can pass the connection parameter to retrieve
the associated error message and SQLCODE value for a specific connection.
Parametry
-
connection -
A connection resource associated with a connection that initially succeeded, but which over time became invalid.
Zwracane wartości
Returns a string containing the error message and SQLCODE value resulting from a failed connection attempt. If there is no error associated with the last connection attempt, db2_conn_errormsg() returns an empty string.
Przykłady
Przykład #1 Retrieving the error message returned by a failed connection attempt
The following example demonstrates how to return an error message and SQLCODE value after deliberately passing invalid parameters to db2_connect().
<?php
$conn = db2_connect('badname', 'baduser', 'badpassword');
if (!$conn) {
print db2_conn_errormsg();
}
?>
Powyższy przykład wyświetli:
[IBM][CLI Driver] SQL1013N The database alias name or database name "BADNAME" could not be found. SQLSTATE=42705 SQLCODE=-1013
Zobacz też:
- db2_conn_error() - Returns a string containing the SQLSTATE returned by the last connection attempt
- db2_connect() - Returns a connection to a database
- db2_stmt_error() - Returns a string containing the SQLSTATE returned by an SQL statement
- db2_stmt_errormsg() - Returns a string containing the last SQL statement error message
db2_connect
(PECL ibm_db2 >= 1.0.0)
db2_connect — Returns a connection to a database
Opis
$database
, string $username
, string $password
[, array $options
] )Creates a new connection to an IBM DB2 Universal Database, IBM Cloudscape, or Apache Derby database.
Parametry
-
database -
For a cataloged connection to a database,
databaserepresents the database alias in the DB2 client catalog.For an uncataloged connection to a database,
databaserepresents a complete connection string in the following format:DATABASE=
where the parameters represent the following values:database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=username;PWD=password;-
database -
The name of the database.
-
hostname -
The hostname or IP address of the database server.
-
port -
The TCP/IP port on which the database is listening for requests.
-
username -
The username with which you are connecting to the database.
-
password -
The password with which you are connecting to the database.
-
-
username -
The username with which you are connecting to the database.
For uncataloged connections, you must pass a
NULLvalue or empty string. -
password -
The password with which you are connecting to the database.
For uncataloged connections, you must pass a
NULLvalue or empty string. -
options -
An associative array of connection options that affect the behavior of the connection, where valid array keys include:
-
autocommit -
Passing the DB2_AUTOCOMMIT_ON value turns autocommit on for this connection handle.
Passing the DB2_AUTOCOMMIT_OFF value turns autocommit off for this connection handle.
-
DB2_ATTR_CASE -
Passing the DB2_CASE_NATURAL value specifies that column names are returned in natural case.
Passing the DB2_CASE_LOWER value specifies that column names are returned in lower case.
Passing the DB2_CASE_UPPER value specifies that column names are returned in upper case.
-
CURSOR -
Passing the DB2_FORWARD_ONLY value specifies a forward-only cursor for a statement resource. This is the default cursor type and is supported on all database servers.
Passing the DB2_SCROLLABLE value specifies a scrollable cursor for a statement resource. This mode enables random access to rows in a result set, but currently is supported only by IBM DB2 Universal Database.
The following new option is available in ibm_db2 version 1.7.0 and later.
-
trustedcontext -
Passing the DB2_TRUSTED_CONTEXT_ENABLE value turns trusted context on for this connection handle. This parameter cannot be set using db2_set_option().
This key works only if the database is cataloged (even if the database is local), or if you specify the full DSN when you create the connection.
To catalog the database, use following commands:
db2 catalog tcpip node loopback remote <SERVERNAME> server <SERVICENAME> db2 catalog database <LOCALDBNAME> as <REMOTEDBNAME> at node loopback db2 "update dbm cfg using svcename <SERVICENAME>" db2set DB2COMM=TCPIP
The following new i5/OS options are available in ibm_db2 version 1.5.1 and later.
-
i5_lib -
A character value that indicates the default library that will be used for resolving unqualified file references. This is not valid if the connection is using system naming mode.
-
i5_naming -
DB2_I5_NAMING_ON value turns on DB2 UDB CLI iSeries system naming mode. Files are qualified using the slash (/) delimiter. Unqualified files are resolved using the library list for the job.
DB2_I5_NAMING_OFF value turns off DB2 UDB CLI default naming mode, which is SQL naming. Files are qualified using the period (.) delimiter. Unqualified files are resolved using either the default library or the current user ID.
-
i5_commit -
The
i5_commitattribute should be set before the db2_connect(). If the value is changed after the connection has been established, and the connection is to a remote data source, the change does not take effect until the next successful db2_connect() for the connection handle.Informacja:
The php.ini setting
ibm_db2.i5_allow_commit==0 or DB2_I5_TXN_NO_COMMIT is the default, but may be overridden with thei5_commitoption.DB2_I5_TXN_NO_COMMIT - Commitment control is not used.
DB2_I5_TXN_READ_UNCOMMITTED - Dirty reads, nonrepeatable reads, and phantoms are possible.
DB2_I5_TXN_READ_COMMITTED - Dirty reads are not possible. Nonrepeatable reads, and phantoms are possible.
DB2_I5_TXN_REPEATABLE_READ - Dirty reads and nonrepeatable reads are not possible. Phantoms are possible.
DB2_I5_TXN_SERIALIZABLE - Transactions are serializable. Dirty reads, non-repeatable reads, and phantoms are not possible
-
i5_query_optimize -
DB2_FIRST_IO All queries are optimized with the goal of returning the first page of output as fast as possible. This goal works well when the output is controlled by a user who is most likely to cancel the query after viewing the first page of output data. Queries coded with an OPTIMIZE FOR nnn ROWS clause honor the goal specified by the clause.
DB2_ALL_IO All queries are optimized with the goal of running the entire query to completion in the shortest amount of elapsed time. This is a good option when the output of a query is being written to a file or report, or the interface is queuing the output data. Queries coded with an OPTIMIZE FOR nnn ROWS clause honor the goal specified by the clause. This is the default.
-
i5_dbcs_alloc -
DB2_I5_DBCS_ALLOC_ON value turns on DB2 6X allocation scheme for DBCS translation column size growth.
DB2_I5_DBCS_ALLOC_OFF value turns off DB2 6X allocation scheme for DBCS translation column size growth.
Note: php.ini setting
ibm_db2.i5_dbcs_alloc==0 or DB2_I5_DBCS_ALLOC_OFF is the default, but may be overridden with thei5_dbcs_allocoption. -
i5_date_fmt -
DB2_I5_FMT_ISO - The International Organization for Standardization (ISO) date format yyyy-mm-dd is used. This is the default.
DB2_I5_FMT_USA - The United States date format mm/dd/yyyy is used.
DB2_I5_FMT_EUR - The European date format dd.mm.yyyy is used.
DB2_I5_FMT_JIS - The Japanese Industrial Standard date format yyyy-mm-dd is used.
DB2_I5_FMT_MDY - The date format mm/dd/yyyy is used.
DB2_I5_FMT_DMY - The date format dd/mm/yyyy is used.
DB2_I5_FMT_YMD - The date format yy/mm/dd is used.
DB2_I5_FMT_JUL - The Julian date format yy/ddd is used.
DB2_I5_FMT_JOB - The job default is used.
-
i5_date_sep -
DB2_I5_SEP_SLASH - A slash ( / ) is used as the date separator. This is the default.
DB2_I5_SEP_DASH - A dash ( - ) is used as the date separator.
DB2_I5_SEP_PERIOD - A period ( . ) is used as the date separator.
DB2_I5_SEP_COMMA - A comma ( , ) is used as the date separator.
DB2_I5_SEP_BLANK - A blank is used as the date separator.
DB2_I5_SEP_JOB - The job default is used
-
i5_time_fmt -
DB2_I5_FMT_ISO - The International Organization for Standardization (ISO) time format hh.mm.ss is used. This is the default.
DB2_I5_FMT_USA - The United States time format hh:mmxx is used, where xx is AM or PM.
DB2_I5_FMT_EUR - The European time format hh.mm.ss is used.
DB2_I5_FMT_JIS - The Japanese Industrial Standard time format hh:mm:ss is used.
DB2_I5_FMT_HMS - The hh:mm:ss format is used.
-
i5_time_sep -
DB2_I5_SEP_COLON - A colon ( : ) is used as the time separator. This is the default.
DB2_I5_SEP_PERIOD - A period ( . ) is used as the time separator.
DB2_I5_SEP_COMMA - A comma ( , ) is used as the time separator.
DB2_I5_SEP_BLANK - A blank is used as the time separator.
DB2_I5_SEP_JOB - The job default is used.
-
i5_decimal_sep -
DB2_I5_SEP_PERIOD - A period ( . ) is used as the decimal separator. This is the default.
DB2_I5_SEP_COMMA - A comma ( , ) is used as the decimal separator.
DB2_I5_SEP_JOB - The job default is used.
The following new i5/OS option is available in ibm_db2 version 1.8.0 and later.
-
i5_libl -
A character value that indicates the library list that will be used for resolving unqualified file references. Specify the library list elements separated by blanks 'i5_libl'=>"MYLIB YOURLIB ANYLIB".
Informacja:
i5_liblcalls qsys2/qcmdexc('cmd',cmdlen), which is only available in i5/OS V5R4 and later.
-
Zwracane wartości
Returns a connection handle resource if the connection attempt is
successful. If the connection attempt fails, db2_connect()
returns FALSE.
Przykłady
Przykład #1 Creating a cataloged connection
Cataloged connections require you to have previously cataloged the target database through the DB2 Command Line Processor (CLP) or DB2 Configuration Assistant.
<?php
$database = 'SAMPLE';
$user = 'db2inst1';
$password = 'ibmdb2';
$conn = db2_connect($database, $user, $password);
if ($conn) {
echo "Connection succeeded.";
db2_close($conn);
}
else {
echo "Connection failed.";
}
?>
Powyższy przykład wyświetli:
Connection succeeded.
Przykład #2 Creating an uncataloged connection
An uncataloged connection enables you to dynamically connect to a database.
<?php
$database = 'SAMPLE';
$user = 'db2inst1';
$password = 'ibmdb2';
$hostname = 'localhost';
$port = 50000;
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;" .
"HOSTNAME=$hostname;PORT=$port;PROTOCOL=TCPIP;UID=$user;PWD=$password;";
$conn = db2_connect($conn_string, '', '');
if ($conn) {
echo "Connection succeeded.";
db2_close($conn);
}
else {
echo "Connection failed.";
}
?>
Powyższy przykład wyświetli:
Connection succeeded.
Przykład #3 Creating a connection with autocommit off by default
Passing an array of options to db2_connect() enables you to modify the default behavior of the connection handle.
<?php
$database = 'SAMPLE';
$user = 'db2inst1';
$password = 'ibmdb2';
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF);
$conn = db2_connect($database, $user, $password, $options);
if ($conn) {
echo "Connection succeeded.\n";
if (db2_autocommit($conn)) {
echo "Autocommit is on.\n";
}
else {
echo "Autocommit is off.\n";
}
db2_close($conn);
}
else {
echo "Connection failed.";
}
?>
Powyższy przykład wyświetli:
Connection succeeded. Autocommit is off.
Przykład #4 i5/OS best performance
To achieve best performance for your i5/OS ibm_db2 1.5.1 PHP application use the default host, userid, and password for your db2_connect().
<?php
$library = "ADC";
$i5 = db2_connect("", "", "", array("i5_lib"=>"qsys2"));
$result = db2_exec($i5,
"select * from systables where table_schema = '$library'");
while ($row = db2_fetch_both($result)) {
echo $row['TABLE_NAME']."</br>";
}
db2_close($i5);
?>
Powyższy przykład wyświetli:
ANIMALS NAMES PICTURES
Przykład #5 Using trusted context
The following example shows how to enable trusted context, switch users, and get the current user ID.
<?php
$database = "SAMPLE";
$hostname = "localhost";
$port = 50000;
$authID = "db2inst1";
$auth_pass = "ibmdb2";
$tc_user = "tcuser";
$tc_pass = "tcpassword";
$dsn = "DATABASE=$database;HOSTNAME=$hostname;PORT=$port;
PROTOCOL=TCPIP;UID=$authID;PWD=$auth_pass;";
$options = array ("trustedcontext" => DB2_TRUSTED_CONTEXT_ENABLE);
$tc_conn = db2_connect($dsn, "", "", $options);
if($tc_conn) {
echo "Explicit trusted connection succeeded.\n";
if(db2_get_option($tc_conn, "trustedcontext")) {
$userBefore = db2_get_option($tc_conn, "trusted_user");
//Do some work as user 1.
//Switching to trusted user.
$parameters = array("trusted_user" => $tc_user,
"trusted_password" => $tcuser_pass);
$res = db2_set_option ($tc_conn, $parameters, 1);
$userAfter = db2_get_option($tc_conn, "trusted_user");
//Do more work as trusted user.
if($userBefore != $userAfter) {
echo "User has been switched." . "\n";
}
}
db2_close($tc_conn);
}
else {
echo "Explicit trusted connection failed.\n";
}
?>
Powyższy przykład wyświetli:
Explicit trusted connection succeeded. User has been switched.
Zobacz też:
- db2_close() - Closes a database connection
- db2_pconnect() - Returns a persistent connection to a database
db2_cursor_type
(PECL ibm_db2 >= 1.0.0)
db2_cursor_type — Returns the cursor type used by a statement resource
Opis
$stmt
)Returns the cursor type used by a statement resource. Use this to determine if you are working with a forward-only cursor or scrollable cursor.
Parametry
-
stmt -
A valid statement resource.
Zwracane wartości
Returns either DB2_FORWARD_ONLY if the statement resource uses a forward-only cursor or DB2_SCROLLABLE if the statement resource uses a scrollable cursor.
db2_escape_string
(PECL ibm_db2 >= 1.6.0)
db2_escape_string — Used to escape certain characters
Opis
$string_literal
)Prepends backslashes to special characters in the string argument.
Parametry
-
string_literal -
The string that contains special characters that need to be modified. Characters that are prepended with a backslash are \x00, \n, \r, \, ', " and \x1a.
Zwracane wartości
Returns string_literal with the special characters
noted above prepended with backslashes.
Przykłady
Przykład #1 A db2_escape_string() example
Result of using the db2_escape_string() function
<?php
$conn = db2_connect($database, $user, $password);
if ($conn) {
$str[0] = "All characters: \x00 , \n , \r , \ , ' , \" , \x1a .";
$str[1] = "Backslash (\). Single quote ('). Double quote (\")";
$str[2] = "The NULL character \0 must be quoted as well";
$str[3] = "Intersting characters: \x1a , \x00 .";
$str[4] = "Nothing to quote";
$str[5] = 200676;
$str[6] = "";
foreach( $str as $string ) {
echo "db2_escape_string: " . db2_escape_string($string). "\n";
}
}
?>
Powyższy przykład wyświetli:
db2_escape_string: All characters: \0 , \n , \r , \\ , \' , \" , \Z . db2_escape_string: Backslash (\\). Single quote (\'). Double quote (\") db2_escape_string: The NULL character \0 must be quoted as well db2_escape_string: Intersting characters: \Z , \0 . db2_escape_string: Nothing to quote db2_escape_string: 200676 db2_escape_string:
db2_exec
(PECL ibm_db2 >= 1.0.0)
db2_exec — Executes an SQL statement directly
Opis
$connection
, string $statement
[, array $options
] )Executes an SQL statement directly.
If you plan to interpolate PHP variables into the SQL statement, understand that this is one of the more common security exposures. Consider calling db2_prepare() to prepare an SQL statement with parameter markers for input values. Then you can call db2_execute() to pass in the input values and avoid SQL injection attacks.
If you plan to repeatedly issue the same SQL statement with different parameters, consider calling db2_prepare() and db2_execute() to enable the database server to reuse its access plan and increase the efficiency of your database access.
Parametry
-
connection -
A valid database connection resource variable as returned from db2_connect() or db2_pconnect().
-
statement -
An SQL statement. The statement cannot contain any parameter markers.
-
options -
An associative array containing statement options. You can use this parameter to request a scrollable cursor on database servers that support this functionality.
For a description of valid statement options, see db2_set_option().
Zwracane wartości
Returns a statement resource if the SQL statement was issued successfully,
or FALSE if the database failed to execute the SQL statement.
Przykłady
Przykład #1 Creating a table with db2_exec()
The following example uses db2_exec() to issue a set of DDL statements in the process of creating a table.
<?php
$conn = db2_connect($database, $user, $password);
// Create the test table
$create = 'CREATE TABLE animals (id INTEGER, breed VARCHAR(32),
name CHAR(16), weight DECIMAL(7,2))';
$result = db2_exec($conn, $create);
if ($result) {
print "Successfully created the table.\n";
}
// Populate the test table
$animals = array(
array(0, 'cat', 'Pook', 3.2),
array(1, 'dog', 'Peaches', 12.3),
array(2, 'horse', 'Smarty', 350.0),
array(3, 'gold fish', 'Bubbles', 0.1),
array(4, 'budgerigar', 'Gizmo', 0.2),
array(5, 'goat', 'Rickety Ride', 9.7),
array(6, 'llama', 'Sweater', 150)
);
foreach ($animals as $animal) {
$rc = db2_exec($conn, "INSERT INTO animals (id, breed, name, weight)
VALUES ({$animal[0]}, '{$animal[1]}', '{$animal[2]}', {$animal[3]})");
if ($rc) {
print "Insert... ";
}
}
?>
Powyższy przykład wyświetli:
Successfully created the table. Insert... Insert... Insert... Insert... Insert... Insert... Insert...
Przykład #2 Executing a SELECT statement with a scrollable cursor
The following example demonstrates how to request a scrollable cursor for an SQL statement issued by db2_exec().
<?php
$conn = db2_connect($database, $user, $password);
$sql = "SELECT name FROM animals
WHERE weight < 10.0
ORDER BY name";
if ($conn) {
require_once('prepare.inc');
$stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
while ($row = db2_fetch_array($stmt)) {
print "$row[0]\n";
}
}
?>
Powyższy przykład wyświetli:
Bubbles Gizmo Pook Rickety Ride
Przykład #3 Returning XML data as an SQL ResultSet
The following example demonstrates how to work with documents stored in a XML column using the SAMPLE database. Using some pretty simple SQL/XML, this example returns some of the nodes in a XML document in an SQL ResultSet format that most users are familiar with.
<?php
$conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");
$query = 'SELECT * FROM XMLTABLE(
XMLNAMESPACES (DEFAULT \'http://posample.org\'),
\'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
COLUMNS
"CID" VARCHAR (50) PATH \'@Cid\',
"NAME" VARCHAR (50) PATH \'name\',
"PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
) AS T
WHERE NAME = \'Kathy Smith\'
';
$stmt = db2_exec($conn, $query);
while($row = db2_fetch_object($stmt)){
printf("$row->CID $row->NAME $row->PHONE\n");
}
db2_close($conn);
?>
Powyższy przykład wyświetli:
1000 Kathy Smith 416-555-1358 1001 Kathy Smith 905-555-7258
Przykład #4 Performing a "JOIN" with XML data
The following example works with documents stored in 2 different XML columns in the SAMPLE database. It creates 2 temporary tables from the XML documents from 2 different columns and returns an SQL ResultSet with information regarding shipping status for the customer.
<?php
$conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");
$query = '
SELECT A.CID, A.NAME, A.PHONE, C.PONUM, C.STATUS
FROM
XMLTABLE(
XMLNAMESPACES (DEFAULT \'http://posample.org\'),
\'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
COLUMNS
"CID" BIGINT PATH \'@Cid\',
"NAME" VARCHAR (50) PATH \'name\',
"PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
) as A,
PURCHASEORDER AS B,
XMLTABLE (
XMLNAMESPACES (DEFAULT \'http://posample.org\'),
\'db2-fn:xmlcolumn("PURCHASEORDER.PORDER")/PurchaseOrder\'
COLUMNS
"PONUM" BIGINT PATH \'@PoNum\',
"STATUS" VARCHAR (50) PATH \'@Status\'
) as C
WHERE A.CID = B.CUSTID AND
B.POID = C.PONUM AND
A.NAME = \'Kathy Smith\'
';
$stmt = db2_exec($conn, $query);
while($row = db2_fetch_object($stmt)){
printf("$row->CID $row->NAME $row->PHONE $row->PONUM $row->STATUS\n");
}
db2_close($conn);
?>
Powyższy przykład wyświetli:
1001 Kathy Smith 905-555-7258 5002 Shipped
Przykład #5 Returning SQL data as part of a larger XML document
The following example works with a portion of the PRODUCT.DESCRIPTION documents in the SAMPLE database. It creates a XML document containing product description (XML data) and pricing info (SQL data).
<?php
$conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");
$query = '
SELECT
XMLSERIALIZE(
XMLQUERY(\'
declare boundary-space strip;
declare default element namespace "http://posample.org";
<promoList> {
for $prod in $doc/product
where $prod/description/price < 10.00
order by $prod/description/price ascending
return(
<promoitem> {
$prod,
<startdate> {$start} </startdate>,
<enddate> {$end} </enddate>,
<promoprice> {$promo} </promoprice>
} </promoitem>
)
} </promoList>
\' passing by ref DESCRIPTION AS "doc",
PROMOSTART as "start",
PROMOEND as "end",
PROMOPRICE as "promo"
RETURNING SEQUENCE)
AS CLOB (32000))
AS NEW_PRODUCT_INFO
FROM PRODUCT
WHERE PID = \'100-100-01\'
';
$stmt = db2_exec($conn, $query);
while($row = db2_fetch_array($stmt)){
printf("$row[0]\n");
}
db2_close($conn);
?>
Powyższy przykład wyświetli:
<promoList xmlns="http://posample.org">
<promoitem>
<product pid="100-100-01">
<description>
<name>Snow Shovel, Basic 22 inch</name>
<details>Basic Snow Shovel, 22 inches wide, straight handle with D-Grip</details>
<price>9.99</price>
<weight>1 kg</weight>
</description>
</product>
<startdate>2004-11-19</startdate>
<enddate>2004-12-19</enddate>
<promoprice>7.25</promoprice>
</promoitem>
</promoList>
Zobacz też:
- db2_execute() - Executes a prepared SQL statement
- db2_prepare() - Prepares an SQL statement to be executed
db2_execute
(PECL ibm_db2 >= 1.0.0)
db2_execute — Executes a prepared SQL statement
Opis
$stmt
[, array $parameters
] )db2_execute() executes an SQL statement that was prepared by db2_prepare().
If the SQL statement returns a result set, for example, a SELECT statement or a CALL to a stored procedure that returns one or more result sets, you can retrieve a row as an array from the stmt resource using db2_fetch_assoc(), db2_fetch_both(), or db2_fetch_array(). Alternatively, you can use db2_fetch_row() to move the result set pointer to the next row and fetch a column at a time from that row with db2_result().
Refer to db2_prepare() for a brief discussion of the advantages of using db2_prepare() and db2_execute() rather than db2_exec().
Parametry
-
stmt -
A prepared statement returned from db2_prepare().
-
parameters -
An array of input parameters matching any parameter markers contained in the prepared statement.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Preparing and executing an SQL statement with parameter markers
The following example prepares an INSERT statement that accepts four parameter markers, then iterates over an array of arrays containing the input values to be passed to db2_execute().
<?php
$pet = array(0, 'cat', 'Pook', 3.2);
$insert = 'INSERT INTO animals (id, breed, name, weight)
VALUES (?, ?, ?, ?)';
$stmt = db2_prepare($conn, $insert);
if ($stmt) {
$result = db2_execute($stmt, $pet);
if ($result) {
print "Successfully added new pet.";
}
}
?>
Powyższy przykład wyświetli:
Successfully added new pet.
Przykład #2 Calling a stored procedure with an OUT parameter
The following example prepares a CALL statement that accepts one parameter marker representing an OUT parameter, binds the PHP variable $my_pets to the parameter using db2_bind_param(), then issues db2_execute() to execute the CALL statement. After the CALL to the stored procedure has been made, the value of $num_pets changes to reflect the value returned by the stored procedure for that OUT parameter.
<?php
$num_pets = 0;
$res = db2_prepare($conn, "CALL count_my_pets(?)");
$rc = db2_bind_param($res, 1, "num_pets", DB2_PARAM_OUT);
$rc = db2_execute($res);
print "I have $num_pets pets!";
?>
Powyższy przykład wyświetli:
I have 7 pets!
Przykład #3 Returning XML data as an SQL ResultSet
The following example demonstrates how to work with documents stored in a XML column using the SAMPLE database. Using some pretty simple SQL/XML, this example returns some of the nodes in a XML document in an SQL ResultSet format that most users are familiar with.
<?php
$conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");
$query = 'SELECT * FROM XMLTABLE(
XMLNAMESPACES (DEFAULT \'http://posample.org\'),
\'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
COLUMNS
"CID" VARCHAR (50) PATH \'@Cid\',
"NAME" VARCHAR (50) PATH \'name\',
"PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
) AS T
WHERE NAME = ?
';
$stmt = db2_prepare($conn, $query);
$name = 'Kathy Smith';
if ($stmt) {
db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
db2_execute($stmt);
while($row = db2_fetch_object($stmt)){
printf("$row->CID $row->NAME $row->PHONE\n");
}
}
db2_close($conn);
?>
Powyższy przykład wyświetli:
1000 Kathy Smith 416-555-1358 1001 Kathy Smith 905-555-7258
Przykład #4 Performing a "JOIN" with XML data
The following example works with documents stored in 2 different XML columns in the SAMPLE database. It creates 2 temporary tables from the XML documents from 2 different columns and returns an SQL ResultSet with information regarding shipping status for the customer.
<?php
$conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");
$query = '
SELECT A.CID, A.NAME, A.PHONE, C.PONUM, C.STATUS
FROM
XMLTABLE(
XMLNAMESPACES (DEFAULT \'http://posample.org\'),
\'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
COLUMNS
"CID" BIGINT PATH \'@Cid\',
"NAME" VARCHAR (50) PATH \'name\',
"PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
) as A,
PURCHASEORDER AS B,
XMLTABLE (
XMLNAMESPACES (DEFAULT \'http://posample.org\'),
\'db2-fn:xmlcolumn("PURCHASEORDER.PORDER")/PurchaseOrder\'
COLUMNS
"PONUM" BIGINT PATH \'@PoNum\',
"STATUS" VARCHAR (50) PATH \'@Status\'
) as C
WHERE A.CID = B.CUSTID AND
B.POID = C.PONUM AND
A.NAME = ?
';
$stmt = db2_prepare($conn, $query);
$name = 'Kathy Smith';
if ($stmt) {
db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
db2_execute($stmt);
while($row = db2_fetch_object($stmt)){
printf("$row->CID $row->NAME $row->PHONE $row->PONUM $row->STATUS\n");
}
}
db2_close($conn);
?>
Powyższy przykład wyświetli:
1001 Kathy Smith 905-555-7258 5002 Shipped
Przykład #5 Returning SQL data as part of a larger XML document
The following example works with a portion of the PRODUCT.DESCRIPTION documents in the SAMPLE database. It creates a XML document containing product description (XML data) and pricing info (SQL data).
<?php
$conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");
$query = '
SELECT
XMLSERIALIZE(
XMLQUERY(\'
declare boundary-space strip;
declare default element namespace "http://posample.org";
<promoList> {
for $prod in $doc/product
where $prod/description/price < 10.00
order by $prod/description/price ascending
return(
<promoitem> {
$prod,
<startdate> {$start} </startdate>,
<enddate> {$end} </enddate>,
<promoprice> {$promo} </promoprice>
} </promoitem>
)
} </promoList>
\' passing by ref DESCRIPTION AS "doc",
PROMOSTART as "start",
PROMOEND as "end",
PROMOPRICE as "promo"
RETURNING SEQUENCE)
AS CLOB (32000))
AS NEW_PRODUCT_INFO
FROM PRODUCT
WHERE PID = ?
';
$stmt = db2_prepare($conn, $query);
$pid = "100-100-01";
if ($stmt) {
db2_bind_param($stmt, 1, "pid", DB2_PARAM_IN);
db2_execute($stmt);
while($row = db2_fetch_array($stmt)){
printf("$row[0]\n");
}
}
db2_close($conn);
?>
Powyższy przykład wyświetli:
<promoList xmlns="http://posample.org">
<promoitem>
<product pid="100-100-01">
<description>
<name>Snow Shovel, Basic 22 inch</name>
<details>Basic Snow Shovel, 22 inches wide, straight handle with D-Grip</details>
<price>9.99</price>
<weight>1 kg</weight>
</description>
</product>
<startdate>2004-11-19</startdate>
<enddate>2004-12-19</enddate>
<promoprice>7.25</promoprice>
</promoitem>
</promoList>
Zobacz też:
- db2_exec() - Executes an SQL statement directly
- db2_fetch_array() - Returns an array, indexed by column position, representing a row in a result set
- db2_fetch_assoc() - Returns an array, indexed by column name, representing a row in a result set
- db2_fetch_both() - Returns an array, indexed by both column name and position, representing a row in a result set
- db2_fetch_row() - Sets the result set pointer to the next row or requested row
- db2_prepare() - Prepares an SQL statement to be executed
- db2_result() - Returns a single column from a row in the result set
db2_fetch_array
(PECL ibm_db2 >= 1.0.1)
db2_fetch_array — Returns an array, indexed by column position, representing a row in a result set
Opis
$stmt
[, int $row_number = -1
] )Returns an array, indexed by column position, representing a row in a result set. The columns are 0-indexed.
Parametry
-
stmt -
A valid stmt resource containing a result set.
-
row_number -
Requests a specific 1-indexed row from the result set. Passing this parameter results in a PHP warning if the result set uses a forward-only cursor.
Zwracane wartości
Returns a 0-indexed array with column values indexed by the column position
representing the next or requested row in the result set. Returns FALSE if
there are no rows left in the result set, or if the row requested by
row_number does not exist in the result set.
Przykłady
Przykład #1 Iterating through a forward-only cursor
If you call db2_fetch_array() without a specific row number, it automatically retrieves the next row in the result set.
<?php
$sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
$stmt = db2_prepare($conn, $sql);
$result = db2_execute($stmt);
while ($row = db2_fetch_array($stmt)) {
printf ("%-5d %-16s %-32s %10s\n",
$row[0], $row[1], $row[2], $row[3]);
}
?>
Powyższy przykład wyświetli:
0 Pook cat 3.20 5 Rickety Ride goat 9.70 2 Smarty horse 350.00
Przykład #2 Retrieving specific rows with db2_fetch_array() from a scrollable cursor
If your result set uses a scrollable cursor, you can call db2_fetch_array() with a specific row number. The following example retrieves every other row in the result set, starting with the second row.
<?php
$sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
$result = db2_exec($stmt, $sql, array('cursor' => DB2_SCROLLABLE));
$i=2;
while ($row = db2_fetch_array($result, $i)) {
printf ("%-5d %-16s %-32s %10s\n",
$row[0], $row[1], $row[2], $row[3]);
$i = $i + 2;
}
?>
Powyższy przykład wyświetli:
0 Pook cat 3.20 5 Rickety Ride goat 9.70 2 Smarty horse 350.00
Zobacz też:
- db2_fetch_assoc() - Returns an array, indexed by column name, representing a row in a result set
- db2_fetch_both() - Returns an array, indexed by both column name and position, representing a row in a result set
- db2_fetch_object() - Returns an object with properties representing columns in the fetched row
- db2_fetch_row() - Sets the result set pointer to the next row or requested row
- db2_result() - Returns a single column from a row in the result set
db2_fetch_assoc
(PECL ibm_db2 >= 1.0.0)
db2_fetch_assoc — Returns an array, indexed by column name, representing a row in a result set
Opis
$stmt
[, int $row_number = -1
] )Returns an array, indexed by column name, representing a row in a result set.
Parametry
-
stmt -
A valid stmt resource containing a result set.
-
row_number -
Requests a specific 1-indexed row from the result set. Passing this parameter results in a PHP warning if the result set uses a forward-only cursor.
Zwracane wartości
Returns an associative array with column values indexed by the column name
representing the next or requested row in the result set. Returns FALSE if
there are no rows left in the result set, or if the row requested by
row_number does not exist in the result set.
Przykłady
Przykład #1 Iterating through a forward-only cursor
If you call db2_fetch_assoc() without a specific row number, it automatically retrieves the next row in the result set.
<?php
$sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
$stmt = db2_prepare($conn, $sql);
$result = db2_execute($stmt);
while ($row = db2_fetch_assoc($stmt)) {
printf ("%-5d %-16s %-32s %10s\n",
$row['ID'], $row['NAME'], $row['BREED'], $row['WEIGHT']);
}
?>
Powyższy przykład wyświetli:
0 Pook cat 3.20 5 Rickety Ride goat 9.70 2 Smarty horse 350.00
Przykład #2 Retrieving specific rows with db2_fetch_assoc() from a scrollable cursor
If your result set uses a scrollable cursor, you can call db2_fetch_assoc() with a specific row number. The following example retrieves every other row in the result set, starting with the second row.
<?php
$sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
$result = db2_exec($stmt, $sql, array('cursor' => DB2_SCROLLABLE));
$i=2;
while ($row = db2_fetch_assoc($result, $i)) {
printf ("%-5d %-16s %-32s %10s\n",
$row['ID'], $row['NAME'], $row['BREED'], $row['WEIGHT']);
$i = $i + 2;
}
?>
Powyższy przykład wyświetli:
0 Pook cat 3.20 5 Rickety Ride goat 9.70 2 Smarty horse 350.00
Zobacz też:
- db2_fetch_array() - Returns an array, indexed by column position, representing a row in a result set
- db2_fetch_both() - Returns an array, indexed by both column name and position, representing a row in a result set
- db2_fetch_object() - Returns an object with properties representing columns in the fetched row
- db2_fetch_row() - Sets the result set pointer to the next row or requested row
- db2_result() - Returns a single column from a row in the result set
db2_fetch_both
(PECL ibm_db2 >= 1.0.0)
db2_fetch_both — Returns an array, indexed by both column name and position, representing a row in a result set
Opis
$stmt
[, int $row_number = -1
] )Returns an array, indexed by both column name and position, representing a row in a result set. Note that the row returned by db2_fetch_both() requires more memory than the single-indexed arrays returned by db2_fetch_assoc() or db2_fetch_array().
Parametry
-
stmt -
A valid stmt resource containing a result set.
-
row_number -
Requests a specific 1-indexed row from the result set. Passing this parameter results in a PHP warning if the result set uses a forward-only cursor.
Zwracane wartości
Returns an associative array with column values indexed by both the column
name and 0-indexed column number. The array represents the next or
requested row in the result set. Returns FALSE if there are no rows left
in the result set, or if the row requested by
row_number does not exist in the result set.
Przykłady
Przykład #1 Iterating through a forward-only cursor
If you call db2_fetch_both() without a specific row number, it automatically retrieves the next row in the result set. The following example accesses columns in the returned array by both column name and by numeric index.
<?php
$sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
$stmt = db2_prepare($conn, $sql);
$result = db2_execute($stmt);
while ($row = db2_fetch_both($stmt)) {
printf ("%-5d %-16s %-32s %10s\n",
$row['ID'], $row[0], $row['BREED'], $row[3]);
}
?>
Powyższy przykład wyświetli:
0 Pook cat 3.20 5 Rickety Ride goat 9.70 2 Smarty horse 350.00
Przykład #2 Retrieving specific rows with db2_fetch_both() from a scrollable cursor
If your result set uses a scrollable cursor, you can call db2_fetch_both() with a specific row number. The following example retrieves every other row in the result set, starting with the second row.
<?php
$sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
$result = db2_exec($stmt, $sql, array('cursor' => DB2_SCROLLABLE));
$i=2;
while ($row = db2_fetch_both($result, $i)) {
printf ("%-5d %-16s %-32s %10s\n",
$row[0], $row['NAME'], $row[2], $row['WEIGHT']);
$i = $i + 2;
}
?>
Powyższy przykład wyświetli:
0 Pook cat 3.20 5 Rickety Ride goat 9.70 2 Smarty horse 350.00
Zobacz też:
- db2_fetch_array() - Returns an array, indexed by column position, representing a row in a result set
- db2_fetch_assoc() - Returns an array, indexed by column name, representing a row in a result set
- db2_fetch_object() - Returns an object with properties representing columns in the fetched row
- db2_fetch_row() - Sets the result set pointer to the next row or requested row
- db2_result() - Returns a single column from a row in the result set
db2_fetch_object
(PECL ibm_db2 >= 1.0.0)
db2_fetch_object — Returns an object with properties representing columns in the fetched row
Opis
$stmt
[, int $row_number = -1
] )Returns an object in which each property represents a column returned in the row fetched from a result set.
Parametry
-
stmt -
A valid stmt resource containing a result set.
-
row_number -
Requests a specific 1-indexed row from the result set. Passing this parameter results in a PHP warning if the result set uses a forward-only cursor.
Zwracane wartości
Returns an object representing a single row in the result set. The properties of the object map to the names of the columns in the result set.
The IBM DB2, Cloudscape, and Apache Derby database servers typically fold column names to upper-case, so the object properties will reflect that case.
If your SELECT statement calls a scalar function to modify the value of a column, the database servers return the column number as the name of the column in the result set. If you prefer a more descriptive column name and object property, you can use the AS clause to assign a name to the column in the result set.
Returns FALSE if no row was retrieved.
Przykłady
Przykład #1 A db2_fetch_object() example
The following example issues a SELECT statement with a scalar function, RTRIM, that removes whitespace from the end of the column. Rather than creating an object with the properties "BREED" and "2", we use the AS clause in the SELECT statement to assign the name "name" to the modified column. The database server folds the column names to upper-case, resulting in an object with the properties "BREED" and "NAME".
<?php
$conn = db2_connect($database, $user, $password);
$sql = "SELECT breed, RTRIM(name) AS name
FROM animals
WHERE id = ?";
if ($conn) {
$stmt = db2_prepare($conn, $sql);
db2_execute($stmt, array(0));
while ($pet = db2_fetch_object($stmt)) {
echo "Come here, {$pet->NAME}, my little {$pet->BREED}!";
}
db2_close($conn);
}
?>
Powyższy przykład wyświetli:
Come here, Pook, my little cat!
Zobacz też:
- db2_fetch_array() - Returns an array, indexed by column position, representing a row in a result set
- db2_fetch_assoc() - Returns an array, indexed by column name, representing a row in a result set
- db2_fetch_both() - Returns an array, indexed by both column name and position, representing a row in a result set
- db2_fetch_row() - Sets the result set pointer to the next row or requested row
- db2_result() - Returns a single column from a row in the result set
db2_fetch_row
(PECL ibm_db2 >= 1.0.0)
db2_fetch_row — Sets the result set pointer to the next row or requested row
Opis
$stmt
[, int $row_number
] )Use db2_fetch_row() to iterate through a result set, or to point to a specific row in a result set if you requested a scrollable cursor.
To retrieve individual fields from the result set, call the db2_result() function.
Rather than calling db2_fetch_row() and db2_result(), most applications will call one of db2_fetch_assoc(), db2_fetch_both(), or db2_fetch_array() to advance the result set pointer and return a complete row as an array.
Parametry
-
stmt -
A valid stmt resource.
-
row_number -
With scrollable cursors, you can request a specific row number in the result set. Row numbering is 1-indexed.
Zwracane wartości
Returns TRUE if the requested row exists in the result set. Returns
FALSE if the requested row does not exist in the result set.
Przykłady
Przykład #1 Iterating through a result set
The following example demonstrates how to iterate through a result set with db2_fetch_row() and retrieve columns from the result set with db2_result().
<?php
$sql = 'SELECT name, breed FROM animals WHERE weight < ?';
$stmt = db2_prepare($conn, $sql);
db2_execute($stmt, array(10));
while (db2_fetch_row($stmt)) {
$name = db2_result($stmt, 0);
$breed = db2_result($stmt, 1);
print "$name $breed";
}
?>
Powyższy przykład wyświetli:
cat Pook gold fish Bubbles budgerigar Gizmo goat Rickety Ride
Przykład #2 i5/OS recommended alternatives to db2_fetch_row/db2_result
On i5/OS it is recommended that you use db2_fetch_both(), db2_fetch_array(), or db2_fetch_object() over db2_fetch_row()/db2_result(). In general db2_fetch_row()/db2_result() have more issues with various column types in EBCIDIC to ASCII translation, including possible truncation in DBCS applications. You may also find the performance of db2_fetch_both(), db2_fetch_array(), and db2_fetch_object() to be superior to db2_fetch_row()/db2_result().
<?php
$conn = db2_connect("","","");
$sql = 'SELECT SPECIFIC_SCHEMA, SPECIFIC_NAME, ROUTINE_SCHEMA, ROUTINE_NAME, ROUTINE_TYPE, ROUTINE_CREATED, ROUTINE_BODY, IN_PARMS, OUT_PARMS, INOUT_PARMS, PARAMETER_STYLE, EXTERNAL_NAME, EXTERNAL_LANGUAGE FROM QSYS2.SYSROUTINES FETCH FIRST 2 ROWS ONLY';
$stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
while ($row = db2_fetch_both($stmt)){
echo "<br>db2_fetch_both {$row['SPECIFIC_NAME']} {$row['ROUTINE_CREATED']} {$row[5]}";
}
$stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
while ($row = db2_fetch_array($stmt)){
echo "<br>db2_fetch_array {$row[1]} {$row[5]}";
}
$stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
while ($row = db2_fetch_object($stmt)){
echo "<br>db2_fetch_object {$row->SPECIFIC_NAME} {$row->ROUTINE_CREATED}";
}
db2_close($conn);
?>
Powyższy przykład wyświetli:
db2_fetch_both MATCH_ANIMAL 2006-08-25-17.10.23.775000 2006-08-25-17.10.23.775000 db2_fetch_both MULTIRESULTS 2006-10-17-10.11.05.308000 2006-10-17-10.11.05.308000 db2_fetch_array MATCH_ANIMAL 2006-08-25-17.10.23.775000 db2_fetch_array MULTIRESULTS 2006-10-17-10.11.05.308000 db2_fetch_object MATCH_ANIMAL 2006-08-25-17.10.23.775000 db2_fetch_object MULTIRESULTS 2006-10-17-10.11.05.308000
Zobacz też:
- db2_fetch_array() - Returns an array, indexed by column position, representing a row in a result set
- db2_fetch_assoc() - Returns an array, indexed by column name, representing a row in a result set
- db2_fetch_both() - Returns an array, indexed by both column name and position, representing a row in a result set
- db2_fetch_object() - Returns an object with properties representing columns in the fetched row
- db2_result() - Returns a single column from a row in the result set
db2_field_display_size
(PECL ibm_db2 >= 1.0.0)
db2_field_display_size — Returns the maximum number of bytes required to display a column
Opis
Returns the maximum number of bytes required to display a column in a result set.
Parametry
-
stmt -
Specifies a statement resource containing a result set.
-
column -
Specifies the column in the result set. This can either be an integer representing the 0-indexed position of the column, or a string containing the name of the column.
Zwracane wartości
Returns an integer value with the maximum number of bytes required to
display the specified column. If the column does not exist in the result
set, db2_field_display_size() returns FALSE.
Zobacz też:
- db2_field_name() - Returns the name of the column in the result set
- db2_field_num() - Returns the position of the named column in a result set
- db2_field_precision() - Returns the precision of the indicated column in a result set
- db2_field_scale() - Returns the scale of the indicated column in a result set
- db2_field_type() - Returns the data type of the indicated column in a result set
- db2_field_width() - Returns the width of the current value of the indicated column in a result set
db2_field_name
(PECL ibm_db2 >= 1.0.0)
db2_field_name — Returns the name of the column in the result set
Opis
Returns the name of the specified column in the result set.
Parametry
-
stmt -
Specifies a statement resource containing a result set.
-
column -
Specifies the column in the result set. This can either be an integer representing the 0-indexed position of the column, or a string containing the name of the column.
Zwracane wartości
Returns a string containing the name of the specified column. If the
specified column does not exist in the result
set, db2_field_name() returns FALSE.
Zobacz też:
- db2_field_display_size() - Returns the maximum number of bytes required to display a column
- db2_field_num() - Returns the position of the named column in a result set
- db2_field_precision() - Returns the precision of the indicated column in a result set
- db2_field_scale() - Returns the scale of the indicated column in a result set
- db2_field_type() - Returns the data type of the indicated column in a result set
- db2_field_width() - Returns the width of the current value of the indicated column in a result set
db2_field_num
(PECL ibm_db2 >= 1.0.0)
db2_field_num — Returns the position of the named column in a result set
Opis
Returns the position of the named column in a result set.
Parametry
-
stmt -
Specifies a statement resource containing a result set.
-
column -
Specifies the column in the result set. This can either be an integer representing the 0-indexed position of the column, or a string containing the name of the column.
Zwracane wartości
Returns an integer containing the 0-indexed position of the named column in
the result set. If the specified column does not exist in the result set,
db2_field_num() returns FALSE.
Zobacz też:
- db2_field_display_size() - Returns the maximum number of bytes required to display a column
- db2_field_name() - Returns the name of the column in the result set
- db2_field_precision() - Returns the precision of the indicated column in a result set
- db2_field_scale() - Returns the scale of the indicated column in a result set
- db2_field_type() - Returns the data type of the indicated column in a result set
- db2_field_width() - Returns the width of the current value of the indicated column in a result set
db2_field_precision
(PECL ibm_db2 >= 1.0.0)
db2_field_precision — Returns the precision of the indicated column in a result set
Opis
Returns the precision of the indicated column in a result set.
Parametry
-
stmt -
Specifies a statement resource containing a result set.
-
column -
Specifies the column in the result set. This can either be an integer representing the 0-indexed position of the column, or a string containing the name of the column.
Zwracane wartości
Returns an integer containing the precision of the specified column. If the
specified column does not exist in the result set,
db2_field_precision() returns FALSE.
Zobacz też:
- db2_field_display_size() - Returns the maximum number of bytes required to display a column
- db2_field_name() - Returns the name of the column in the result set
- db2_field_num() - Returns the position of the named column in a result set
- db2_field_scale() - Returns the scale of the indicated column in a result set
- db2_field_type() - Returns the data type of the indicated column in a result set
- db2_field_width() - Returns the width of the current value of the indicated column in a result set
db2_field_scale
(PECL ibm_db2 >= 1.0.0)
db2_field_scale — Returns the scale of the indicated column in a result set
Opis
Returns the scale of the indicated column in a result set.
Parametry
-
stmt -
Specifies a statement resource containing a result set.
-
column -
Specifies the column in the result set. This can either be an integer representing the 0-indexed position of the column, or a string containing the name of the column.
Zwracane wartości
Returns an integer containing the scale of the specified column. If the
specified column does not exist in the result set,
db2_field_scale() returns FALSE.
Zobacz też:
- db2_field_display_size() - Returns the maximum number of bytes required to display a column
- db2_field_name() - Returns the name of the column in the result set
- db2_field_num() - Returns the position of the named column in a result set
- db2_field_precision() - Returns the precision of the indicated column in a result set
- db2_field_type() - Returns the data type of the indicated column in a result set
- db2_field_width() - Returns the width of the current value of the indicated column in a result set
db2_field_type
(PECL ibm_db2 >= 1.0.0)
db2_field_type — Returns the data type of the indicated column in a result set
Opis
Returns the data type of the indicated column in a result set.
Parametry
-
stmt -
Specifies a statement resource containing a result set.
-
column -
Specifies the column in the result set. This can either be an integer representing the 0-indexed position of the column, or a string containing the name of the column.
Zwracane wartości
Returns a string containing the defined data type of the specified column.
If the specified column does not exist in the result set,
db2_field_type() returns FALSE.
Zobacz też:
- db2_field_display_size() - Returns the maximum number of bytes required to display a column
- db2_field_name() - Returns the name of the column in the result set
- db2_field_num() - Returns the position of the named column in a result set
- db2_field_precision() - Returns the precision of the indicated column in a result set
- db2_field_scale() - Returns the scale of the indicated column in a result set
- db2_field_width() - Returns the width of the current value of the indicated column in a result set
db2_field_width
(PECL ibm_db2 >= 1.0.0)
db2_field_width — Returns the width of the current value of the indicated column in a result set
Opis
Returns the width of the current value of the indicated column in a result set. This is the maximum width of the column for a fixed-length data type, or the actual width of the column for a variable-length data type.
Parametry
-
stmt -
Specifies a statement resource containing a result set.
-
column -
Specifies the column in the result set. This can either be an integer representing the 0-indexed position of the column, or a string containing the name of the column.
Zwracane wartości
Returns an integer containing the width of the specified character or
binary data type column in a result set. If the specified column does not
exist in the result set, db2_field_width() returns
FALSE.
Zobacz też:
- db2_field_display_size() - Returns the maximum number of bytes required to display a column
- db2_field_name() - Returns the name of the column in the result set
- db2_field_num() - Returns the position of the named column in a result set
- db2_field_precision() - Returns the precision of the indicated column in a result set
- db2_field_scale() - Returns the scale of the indicated column in a result set
- db2_field_type() - Returns the data type of the indicated column in a result set
db2_foreign_keys
(PECL ibm_db2 >= 1.0.0)
db2_foreign_keys — Returns a result set listing the foreign keys for a table
Opis
$connection
, string $qualifier
, string $schema
, string $table-name
)Returns a result set listing the foreign keys for a table.
Parametry
-
connection -
A valid connection to an IBM DB2, Cloudscape, or Apache Derby database.
-
qualifier -
A qualifier for DB2 databases running on OS/390 or z/OS servers. For other databases, pass
NULLor an empty string. -
schema -
The schema which contains the tables. If
schemaisNULL, db2_foreign_keys() matches the schema for the current connection. -
table-name -
The name of the table.
Zwracane wartości
Returns a statement resource with a result set containing rows describing the foreign keys for the specified table. The result set is composed of the following columns:
| Column name | Description |
|---|---|
| PKTABLE_CAT | Name of the catalog for the table containing the primary key. The value is NULL if this table does not have catalogs. |
| PKTABLE_SCHEM | Name of the schema for the table containing the primary key. |
| PKTABLE_NAME | Name of the table containing the primary key. |
| PKCOLUMN_NAME | Name of the column containing the primary key. |
| FKTABLE_CAT | Name of the catalog for the table containing the foreign key. The value is NULL if this table does not have catalogs. |
| FKTABLE_SCHEM | Name of the schema for the table containing the foreign key. |
| FKTABLE_NAME | Name of the table containing the foreign key. |
| FKCOLUMN_NAME | Name of the column containing the foreign key. |
| KEY_SEQ | 1-indexed position of the column in the key. |
| UPDATE_RULE | Integer value representing the action applied to the foreign key when the SQL operation is UPDATE. |
| DELETE_RULE | Integer value representing the action applied to the foreign key when the SQL operation is DELETE. |
| FK_NAME | The name of the foreign key. |
| PK_NAME | The name of the primary key. |
| DEFERRABILITY | An integer value representing whether the foreign key deferrability is SQL_INITIALLY_DEFERRED, SQL_INITIALLY_IMMEDIATE, or SQL_NOT_DEFERRABLE. |
Zobacz też:
- db2_column_privileges() - Returns a result set listing the columns and associated privileges for a table
- db2_columns() - Returns a result set listing the columns and associated metadata for a table
- db2_primary_keys() - Returns a result set listing primary keys for a table
- db2_procedure_columns() - Returns a result set listing stored procedure parameters
- db2_procedures() - Returns a result set listing the stored procedures registered in a database
- db2_special_columns() - Returns a result set listing the unique row identifier columns for a table
- db2_statistics() - Returns a result set listing the index and statistics for a table
- db2_table_privileges() - Returns a result set listing the tables and associated privileges in a database
- db2_tables() - Returns a result set listing the tables and associated metadata in a database
db2_free_result
(PECL ibm_db2 >= 1.0.0)
db2_free_result — Frees resources associated with a result set
Opis
$stmt
)Frees the system and database resources that are associated with a result set. These resources are freed implicitly when a script finishes, but you can call db2_free_result() to explicitly free the result set resources before the end of the script.
Parametry
-
stmt -
A valid statement resource.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
db2_free_stmt
(PECL ibm_db2 >= 1.0.0)
db2_free_stmt — Frees resources associated with the indicated statement resource
Opis
$stmt
)Frees the system and database resources that are associated with a statement resource. These resources are freed implicitly when a script finishes, but you can call db2_free_stmt() to explicitly free the statement resources before the end of the script.
Parametry
-
stmt -
A valid statement resource.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
db2_get_option
(PECL ibm_db2 >= 1.6.0)
db2_get_option — Retrieves an option value for a statement resource or a connection resource
Opis
$resource
, string $option
)Retrieves the value of a specified option value for a statement resource or a connection resource.
Parametry
-
resource -
A valid statement resource as returned from db2_prepare() or a valid connection resource as returned from db2_connect() or db2_pconnect().
-
option -
A valid statement or connection options. The following new options are available as of ibm_db2 version 1.6.0. They provide useful tracking information that can be set during execution with db2_get_option().
Informacja:
Prior versions of ibm_db2 do not support these new options.
When the value in each option is being set, some servers might not handle the entire length provided and might truncate the value.
To ensure that the data specified in each option is converted correctly when transmitted to a host system, use only the characters A through Z, 0 through 9, and the underscore (_) or period (.).
-
userid -
SQL_ATTR_INFO_USERID - A pointer to a null-terminated character string used to identify the client user ID sent to the host database server when using DB2 Connect.
Informacja:
DB2 for z/OS and OS/390 servers support up to a length of 16 characters. This user-id is not to be confused with the authentication user-id, it is for identification purposes only and is not used for any authorization.
-
acctstr -
SQL_ATTR_INFO_ACCTSTR - A pointer to a null-terminated character string used to identify the client accounting string sent to the host database server when using DB2 Connect.
Informacja:
DB2 for z/OS and OS/390 servers support up to a length of 200 characters.
-
applname -
SQL_ATTR_INFO_APPLNAME - A pointer to a null-terminated character string used to identify the client application name sent to the host database server when using DB2 Connect.
Informacja:
DB2 for z/OS and OS/390 servers support up to a length of 32 characters.
-
wrkstnname -
SQL_ATTR_INFO_WRKSTNNAME - A pointer to a null-terminated character string used to identify the client workstation name sent to the host database server when using DB2 Connect.
Informacja:
DB2 for z/OS and OS/390 servers support up to a length of 18 characters.
-
The following table specifies which options are compatible with the available resource types:
| Key | Value | Resource Type | ||
|---|---|---|---|---|
| Connection | Statement | Result Set | ||
| userid | SQL_ATTR_INFO_USERID | X | X | - |
| acctstr | SQL_ATTR_INFO_ACCTSTR | X | X | - |
| applname | SQL_ATTR_INFO_APPLNAME | X | X | - |
| wrkstnname | SQL_ATTR_INFO_WRKSTNNAME | X | X | - |
Zwracane wartości
Returns the current setting of the connection attribute provided on success
lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 Setting and retrieving parameters through a connection resource
<?php
/* Database Connection Parameters */
$database = 'SAMPLE';
$user = 'db2inst1';
$password = 'ibmdb2';
/* Obtain Connection Resource */
$conn = db2_connect($database, $user, $password);
echo "Client attributes passed through connection string:\n";
/* Create the associative options array with valid key-value pairs */
/* Assign the attributes through connection string */
/* Access the options specified */
$options1 = array('userid' => 'db2inst1');
$conn1 = db2_connect($database, $user, $password, $options1);
$val = db2_get_option($conn1, 'userid');
echo $val . "\n";
$options2 = array('acctstr' => 'account');
$conn2 = db2_connect($database, $user, $password, $options2);
$val = db2_get_option($conn2, 'acctstr');
echo $val . "\n";
$options3 = array('applname' => 'myapp');
$conn3 = db2_connect($database, $user, $password, $options3);
$val = db2_get_option($conn3, 'applname');
echo $val . "\n";
$options4 = array('wrkstnname' => 'workstation');
$conn4 = db2_connect($database, $user, $password, $options4);
$val = db2_get_option($conn4, 'wrkstnname');
echo $val . "\n";
echo "Client attributes passed post-connection:\n";
/* Create the associative options array with valid key-value pairs */
/* Assign the attributes after a connection is made */
/* Access the options specified */
$options5 = array('userid' => 'db2inst1');
$conn5 = db2_connect($database, $user, $password);
$rc = db2_set_option($conn5, $options5, 1);
$val = db2_get_option($conn5, 'userid');
echo $val . "\n";
$options6 = array('acctstr' => 'account');
$conn6 = db2_connect($database, $user, $password);
$rc = db2_set_option($conn6, $options6, 1);
$val = db2_get_option($conn6, 'acctstr');
echo $val . "\n";
$options7 = array('applname' => 'myapp');
$conn7 = db2_connect($database, $user, $password);
$rc = db2_set_option($conn7, $options7, 1);
$val = db2_get_option($conn7, 'applname');
echo $val . "\n";
$options8 = array('wrkstnname' => 'workstation');
$conn8 = db2_connect($database, $user, $password);
$rc = db2_set_option($conn8, $options8, 1);
$val = db2_get_option($conn8, 'wrkstnname');
echo $val . "\n";
?>
Powyższy przykład wyświetli:
Client attributes passed through connection string: db2inst1 account myapp workstation Client attributes passed post-connection: db2inst1 account myapp workstation
Zobacz też:
- db2_connect() - Returns a connection to a database
- db2_cursor_type() - Returns the cursor type used by a statement resource
- db2_exec() - Executes an SQL statement directly
- db2_set_option() - Set options for connection or statement resources
- db2_pconnect() - Returns a persistent connection to a database
- db2_prepare() - Prepares an SQL statement to be executed
db2_last_insert_id
(PECL ibm_db2 >= 1.7.1)
db2_last_insert_id — Returns the auto generated ID of the last insert query that successfully executed on this connection
Opis
$resource
)Returns the auto generated ID of the last insert query that successfully executed on this connection.
The result of this function is not affected by any of the following:
-
A single row INSERT statement with a VALUES clause for a table without an identity column.
-
A multiple row INSERT statement with a VALUES clause.
-
An INSERT statement with a fullselect.
-
A ROLLBACK TO SAVEPOINT statement.
Parametry
-
resource -
A valid connection resource as returned from db2_connect() or db2_pconnect(). The value of this parameter cannot be a statement resource or result set resource.
Zwracane wartości
Returns the auto generated ID of last insert query that successfully executed on this connection.
Przykłady
Przykład #1 A db2_last_insert_id() example
The following example shows how to return the auto generated ID of last insert query that successfully executed on this connection.
<?php
$database = "SAMPLE";
$user = "db2inst1";
$password = "ibmdb2";
$conn = db2_connect($database, $user, $password);
if($conn) {
$createTable = "CREATE TABLE lastInsertID
(id integer GENERATED BY DEFAULT AS IDENTITY, name varchar(20))";
$insertTable = "INSERT INTO lastInsertID (name) VALUES ('Temp Name')";
$stmt = @db2_exec($conn, $createTable);
/* Checking for single row inserted. */
$stmt = db2_exec($conn, $insertTable);
$ret = db2_last_insert_id($conn);
if($ret) {
echo "Last Insert ID is : " . $ret . "\n";
} else {
echo "No Last insert ID.\n";
}
db2_close($conn);
}
else {
echo "Connection failed.";
}
?>
Powyższy przykład wyświetli:
Last Insert ID is : 1
db2_lob_read
(PECL ibm_db2 >= 1.6.0)
db2_lob_read — Gets a user defined size of LOB files with each invocation
Opis
$stmt
, int $colnum
, int $length
)Use db2_lob_read() to iterate through a specified column of a result set and retrieve a user defined size of LOB data.
Parametry
-
stmt -
A valid stmt resource containing LOB data.
-
colnum -
A valid column number in the result set of the stmt resource.
-
length -
The size of the LOB data to be retrieved from the stmt resource.
Zwracane wartości
Returns the amount of data the user specifies. Returns
FALSE if the data cannot be retrieved.
Przykłady
Przykład #1 Iterating through different types of data
<?php
/* Database Connection Parameters */
$db = 'SAMPLE';
$username = 'db2inst1';
$password = 'ibmdb2';
/* Obtain Connection Resource */
$conn = db2_connect($db,$username,$password);
if ($conn) {
$drop = 'DROP TABLE clob_stream';
$result = @db2_exec( $conn, $drop );
$create = 'CREATE TABLE clob_stream (id INTEGER, my_clob CLOB)';
$result = db2_exec( $conn, $create );
$variable = "";
$stmt = db2_prepare($conn, "INSERT INTO clob_stream (id,my_clob) VALUES (1, ?)");
$variable = "THIS IS A CLOB TEST. THIS IS A CLOB TEST.";
db2_bind_param($stmt, 1, "variable", DB2_PARAM_IN);
db2_execute($stmt);
$sql = "SELECT id,my_clob FROM clob_stream";
$result = db2_prepare($conn, $sql);
db2_execute($result);
db2_fetch_row($result);
$i = 0;
/* Read LOB data */
while ($data = db2_lob_read($result, 2, 6)) {
echo "Loop $i: $data\n";
$i = $i + 1;
}
$drop = 'DROP TABLE blob_stream';
$result = @db2_exec( $conn, $drop );
$create = 'CREATE TABLE blob_stream (id INTEGER, my_blob CLOB)';
$result = db2_exec( $conn, $create );
$variable = "";
$stmt = db2_prepare($conn, "INSERT INTO blob_stream (id,my_blob) VALUES (1, ?)");
$variable = "THIS IS A BLOB TEST. THIS IS A BLOB TEST.";
db2_bind_param($stmt, 1, "variable", DB2_PARAM_IN);
db2_execute($stmt);
$sql = "SELECT id,my_blob FROM blob_stream";
$result = db2_prepare($conn, $sql);
db2_execute($result);
db2_fetch_row($result);
$i = 0;
/* Read LOB data */
while ($data = db2_lob_read($result, 2, 6)) {
echo "Loop $i: $data\n";
$i = $i + 1;
}
} else {
echo 'no connection: ' . db2_conn_errormsg();
}
?>
Powyższy przykład wyświetli:
Loop 0: THIS I Loop 1: S A CL Loop 2: OB TES Loop 3: T. THI Loop 4: S IS A Loop 5: CLOB Loop 6: TEST. Loop 0: THIS I Loop 1: S A BL Loop 2: OB TES Loop 3: T. THI Loop 4: S IS A Loop 5: BLOB Loop 6: TEST.
Zobacz też:
- db2_bind_param() - Binds a PHP variable to an SQL statement parameter
- db2_exec() - Executes an SQL statement directly
- db2_execute() - Executes a prepared SQL statement
- db2_fetch_row() - Sets the result set pointer to the next row or requested row
- db2_prepare() - Prepares an SQL statement to be executed
- db2_result() - Returns a single column from a row in the result set
db2_next_result
(PECL ibm_db2 >= 1.0.0)
db2_next_result — Requests the next result set from a stored procedure
Opis
$stmt
)A stored procedure can return zero or more result sets. While you handle the first result set in exactly the same way you would handle the results returned by a simple SELECT statement, to fetch the second and subsequent result sets from a stored procedure you must call the db2_next_result() function and return the result to a uniquely named PHP variable.
Zwracane wartości
Returns a new statement resource containing the next result set if the
stored procedure returned another result set. Returns FALSE if the stored
procedure did not return another result set.
Przykłady
Przykład #1 Calling a stored procedure that returns multiple result sets
In the following example, we call a stored procedure that returns three result sets. The first result set is fetched directly from the same statement resource on which we invoked the CALL statement, while the second and third result sets are fetched from statement resources returned from our calls to the db2_next_result() function.
<?php
$conn = db2_connect($database, $user, $password);
if ($conn) {
$stmt = db2_exec($conn, 'CALL multiResults()');
print "Fetching first result set\n";
while ($row = db2_fetch_array($stmt)) {
var_dump($row);
}
print "\nFetching second result set\n";
$res = db2_next_result($stmt);
if ($res) {
while ($row = db2_fetch_array($res)) {
var_dump($row);
}
}
print "\nFetching third result set\n";
$res2 = db2_next_result($stmt);
if ($res2) {
while ($row = db2_fetch_array($res2)) {
var_dump($row);
}
}
db2_close($conn);
}
?>
Powyższy przykład wyświetli:
Fetching first result set
array(2) {
[0]=>
string(16) "Bubbles "
[1]=>
int(3)
}
array(2) {
[0]=>
string(16) "Gizmo "
[1]=>
int(4)
}
Fetching second result set
array(4) {
[0]=>
string(16) "Sweater "
[1]=>
int(6)
[2]=>
string(5) "llama"
[3]=>
string(6) "150.00"
}
array(4) {
[0]=>
string(16) "Smarty "
[1]=>
int(2)
[2]=>
string(5) "horse"
[3]=>
string(6) "350.00"
}
Fetching third result set
array(1) {
[0]=>
string(16) "Bubbles "
}
array(1) {
[0]=>
string(16) "Gizmo "
}
db2_num_fields
(PECL ibm_db2 >= 1.0.0)
db2_num_fields — Returns the number of fields contained in a result set
Opis
$stmt
)Returns the number of fields contained in a result set. This is most useful for handling the result sets returned by dynamically generated queries, or for result sets returned by stored procedures, where your application cannot otherwise know how to retrieve and use the results.
Parametry
-
stmt -
A valid statement resource containing a result set.
Zwracane wartości
Returns an integer value representing the number of fields in the result
set associated with the specified statement resource. Returns FALSE if
the statement resource is not a valid input value.
Przykłady
Przykład #1 Retrieving the number of fields in a result set
The following example demonstrates how to retrieve the number of fields returned in a result set.
<?php
$sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
$stmt = db2_prepare($conn, $sql);
db2_execute($stmt, $sql);
$columns = db2_num_fields($stmt);
echo "There are {$columns} columns in the result set.";
?>
Powyższy przykład wyświetli:
There are 4 columns in the result set.
Zobacz też:
- db2_execute() - Executes a prepared SQL statement
- db2_field_display_size() - Returns the maximum number of bytes required to display a column
- db2_field_name() - Returns the name of the column in the result set
- db2_field_num() - Returns the position of the named column in a result set
- db2_field_precision() - Returns the precision of the indicated column in a result set
- db2_field_scale() - Returns the scale of the indicated column in a result set
- db2_field_type() - Returns the data type of the indicated column in a result set
- db2_field_width() - Returns the width of the current value of the indicated column in a result set
db2_num_rows
(PECL ibm_db2 >= 1.0.0)
db2_num_rows — Returns the number of rows affected by an SQL statement
Opis
$stmt
)Returns the number of rows deleted, inserted, or updated by an SQL statement.
To determine the number of rows that will be returned by a SELECT statement, issue SELECT COUNT(*) with the same predicates as your intended SELECT statement and retrieve the value.
If your application logic checks the number of rows returned by a SELECT
statement and branches if the number of rows is 0, consider modifying your
application to attempt to return the first row with one of
db2_fetch_assoc(), db2_fetch_both(),
db2_fetch_array(), or db2_fetch_row(),
and branch if the fetch function returns FALSE.
Informacja:
If you issue a SELECT statement using a scrollable cursor, db2_num_rows() returns the number of rows returned by the SELECT statement. However, the overhead associated with scrollable cursors significantly degrades the performance of your application, so if this is the only reason you are considering using scrollable cursors, you should use a forward-only cursor and either call SELECT COUNT(*) or rely on the boolean return value of the fetch functions to achieve the equivalent functionality with much better performance.
Parametry
-
stmt -
A valid stmt resource containing a result set.
Zwracane wartości
Returns the number of rows affected by the last SQL statement issued by the specified statement handle.
db2_pclose
(PECL ibm_db2 >= 1.8.0)
db2_pclose — Closes a persistent database connection
Opis
$resource
)This function closes a DB2 client connection created with db2_pconnect() and returns the corresponding resources to the database server.
Informacja:
This function is only available on i5/OS in response to i5/OS system administration requests.
If you have a persistent DB2 client connection created with db2_pconnect(), you may use this function to close the connection. To avoid substantial connection performance penalties, this function should only be used in rare cases when the persistent connection has become unresponsive or the persistent connection will not be needed for a long period of time.
Parametry
-
connection -
Specifies an active DB2 client connection.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Closing a persistent connection
The following example demonstrates a successful attempt to close a connection to an IBM DB2 i5/OS database.
<?php
$conn = db2_pconnect('', '', '');
$rc = db2_pclose($conn);
if ($rc) {
echo "Connection was successfully closed.";
}
?>
Powyższy przykład wyświetli:
Connection was successfully closed.
Zobacz też:
- db2_close() - Closes a database connection
- db2_pconnect() - Returns a persistent connection to a database
db2_pconnect
(PECL ibm_db2 >= 1.0.0)
db2_pconnect — Returns a persistent connection to a database
Opis
$database
, string $username
, string $password
[, array $options
] )Returns a persistent connection to an IBM DB2 Universal Database, IBM Cloudscape, or Apache Derby database.
For more information on persistent connections, refer to Stałe połączenia z bazami danych.
Calling db2_close() on a persistent connection always
returns TRUE, but the underlying DB2 client connection remains open and
waiting to serve the next matching db2_pconnect()
request.
Users running version 1.9.0 or later of ibm_db2 should be aware that the extension will perform a transaction rollback on persistent connections at the end of a request, thus ending the transaction. This prevents the transaction block from carrying over to the next request which uses that connection if script execution ends before the transaction block does.
Parametry
-
database -
The database alias in the DB2 client catalog.
-
username -
The username with which you are connecting to the database.
-
password -
The password with which you are connecting to the database.
-
options -
An associative array of connection options that affect the behavior of the connection, where valid array keys include:
-
autocommit -
Passing the DB2_AUTOCOMMIT_ON value turns autocommit on for this connection handle.
Passing the DB2_AUTOCOMMIT_OFF value turns autocommit off for this connection handle.
-
DB2_ATTR_CASE -
Passing the DB2_CASE_NATURAL value specifies that column names are returned in natural case.
Passing the DB2_CASE_LOWER value specifies that column names are returned in lower case.
Passing the DB2_CASE_UPPER value specifies that column names are returned in upper case.
-
CURSOR -
Passing the DB2_FORWARD_ONLY value specifies a forward-only cursor for a statement resource. This is the default cursor type and is supported on all database servers.
Passing the DB2_SCROLLABLE value specifies a scrollable cursor for a statement resource. This mode enables random access to rows in a result set, but currently is supported only by IBM DB2 Universal Database.
The following new option is available in ibm_db2 version 1.7.0 and later.
-
trustedcontext -
Passing the DB2_TRUSTED_CONTEXT_ENABLE value turns trusted context on for this connection handle. This parameter cannot be set using db2_set_option().
This key works only if the database is cataloged (even if the database is local), or if you specify the full DSN when you create the connection.
To catalog the database, use following commands:
db2 catalog tcpip node loopback remote <SERVERNAME> server <SERVICENAME> db2 catalog database <LOCALDBNAME> as <REMOTEDBNAME> at node loopback db2 "update dbm cfg using svcename <SERVICENAME>" db2set DB2COMM=TCPIP
The following new i5/OS options are available in ibm_db2 version 1.5.1 and later.
WskazówkaConflicting connection attributes used in conjunction with persistent connections can produce indeterminate results on i5/OS. Site policies should be establish for all applications using each persistent connection user profile. The default DB2_AUTOCOMMIT_ON is suggested when using persistent connections.
-
i5_lib -
A character value that indicates the default library that will be used for resolving unqualified file references. This is not valid if the connection is using system naming mode.
-
i5_naming -
DB2_I5_NAMING_ON value turns on DB2 UDB CLI iSeries system naming mode. Files are qualified using the slash (/) delimiter. Unqualified files are resolved using the library list for the job.
DB2_I5_NAMING_OFF value turns off DB2 UDB CLI default naming mode, which is SQL naming. Files are qualified using the period (.) delimiter. Unqualified files are resolved using either the default library or the current user ID.
-
i5_commit -
The
i5_commitattribute should be set before the db2_pconnect(). If the value is changed after the connection has been established, and the connection is to a remote data source, the change does not take effect until the next successful db2_pconnect() for the connection handle.Informacja:
The php.ini setting
ibm_db2.i5_allow_commit==0 or DB2_I5_TXN_NO_COMMIT is the default, but may be overridden with thei5_commitoption.DB2_I5_TXN_NO_COMMIT - Commitment control is not used.
DB2_I5_TXN_READ_UNCOMMITTED - Dirty reads, nonrepeatable reads, and phantoms are possible.
DB2_I5_TXN_READ_COMMITTED - Dirty reads are not possible. Nonrepeatable reads, and phantoms are possible.
DB2_I5_TXN_REPEATABLE_READ - Dirty reads and nonrepeatable reads are not possible. Phantoms are possible.
DB2_I5_TXN_SERIALIZABLE - Transactions are serializable. Dirty reads, non-repeatable reads, and phantoms are not possible
-
i5_query_optimize -
DB2_FIRST_IO All queries are optimized with the goal of returning the first page of output as fast as possible. This goal works well when the output is controlled by a user who is most likely to cancel the query after viewing the first page of output data. Queries coded with an OPTIMIZE FOR nnn ROWS clause honor the goal specified by the clause.
DB2_ALL_IO All queries are optimized with the goal of running the entire query to completion in the shortest amount of elapsed time. This is a good option when the output of a query is being written to a file or report, or the interface is queuing the output data. Queries coded with an OPTIMIZE FOR nnn ROWS clause honor the goal specified by the clause. This is the default.
-
i5_dbcs_alloc -
DB2_I5_DBCS_ALLOC_ON value turns on DB2 6X allocation scheme for DBCS translation column size growth.
DB2_I5_DBCS_ALLOC_OFF value turns off DB2 6X allocation scheme for DBCS translation column size growth.
Informacja:
The php.ini setting
ibm_db2.i5_dbcs_alloc==0 or DB2_I5_DBCS_ALLOC_OFF is the default, but may be overridden with thei5_dbcs_allocoption. -
i5_date_fmt -
DB2_I5_FMT_ISO - The International Organization for Standardization (ISO) date format yyyy-mm-dd is used. This is the default.
DB2_I5_FMT_USA - The United States date format mm/dd/yyyy is used.
DB2_I5_FMT_EUR - The European date format dd.mm.yyyy is used.
DB2_I5_FMT_JIS - The Japanese Industrial Standard date format yyyy-mm-dd is used.
DB2_I5_FMT_MDY - The date format mm/dd/yyyy is used.
DB2_I5_FMT_DMY - The date format dd/mm/yyyy is used.
DB2_I5_FMT_YMD - The date format yy/mm/dd is used.
DB2_I5_FMT_JUL - The Julian date format yy/ddd is used.
DB2_I5_FMT_JOB - The job default is used.
-
i5_date_sep -
DB2_I5_SEP_SLASH - A slash ( / ) is used as the date separator. This is the default.
DB2_I5_SEP_DASH - A dash ( - ) is used as the date separator.
DB2_I5_SEP_PERIOD - A period ( . ) is used as the date separator.
DB2_I5_SEP_COMMA - A comma ( , ) is used as the date separator.
DB2_I5_SEP_BLANK - A blank is used as the date separator.
DB2_I5_SEP_JOB - The job default is used
-
i5_time_fmt -
DB2_I5_FMT_ISO - The International Organization for Standardization (ISO) time format hh.mm.ss is used. This is the default.
DB2_I5_FMT_USA - The United States time format hh:mmxx is used, where xx is AM or PM.
DB2_I5_FMT_EUR - The European time format hh.mm.ss is used.
DB2_I5_FMT_JIS - The Japanese Industrial Standard time format hh:mm:ss is used.
DB2_I5_FMT_HMS - The hh:mm:ss format is used.
-
i5_time_sep -
DB2_I5_SEP_COLON - A colon ( : ) is used as the time separator. This is the default.
DB2_I5_SEP_PERIOD - A period ( . ) is used as the time separator.
DB2_I5_SEP_COMMA - A comma ( , ) is used as the time separator.
DB2_I5_SEP_BLANK - A blank is used as the time separator.
DB2_I5_SEP_JOB - The job default is used.
-
i5_decimal_sep -
DB2_I5_SEP_PERIOD - A period ( . ) is used as the decimal separator. This is the default.
DB2_I5_SEP_COMMA - A comma ( , ) is used as the decimal separator.
DB2_I5_SEP_JOB - The job default is used.
The following new i5/OS option is available in ibm_db2 version 1.8.0 and later.
-
i5_libl -
A character value that indicates the library list that will be used for resolving unqualified file references. Specify the library list elements separated by blanks 'i5_libl'=>"MYLIB YOURLIB ANYLIB".
Informacja:
i5_libl calls qsys2/qcmdexc('cmd',cmdlen), which is only available in i5/OS V5R4 and later.
-
Zwracane wartości
Returns a connection handle resource if the connection attempt is
successful. db2_pconnect() tries to reuse an existing
connection resource that exactly matches the
database, username, and
password parameters. If the connection attempt fails,
db2_pconnect() returns FALSE.
Rejestr zmian
| Wersja | Opis |
|---|---|
| ibm_db2 1.9.0 | Active transactions within a persistent connection will be rolled back at the end of each request. |
| ibm_db2 1.8.0 |
The i5_libl option is available for i5/OS
users.
|
| ibm_db2 1.7.0 |
The trustedcontext option is available.
|
| ibm_db2 1.5.1 |
The i5_lib, i5_naming,
i5_commit,
i5_query_optimize,
i5_dbcs_alloc,
i5_date_fmt,
i5_date_sep,
i5_time_fmt, i5_time_sep
and i5_decimal_sep options are available for
i5/OS users.
|
Przykłady
Przykład #1 A db2_pconnect() example
In the following example, the first call to db2_pconnect() returns a new persistent connection resource. The second call to db2_pconnect() returns a persistent connection resource that simply reuses the first persistent connection resource.
<?php
$database = 'SAMPLE';
$user = 'db2inst1';
$password = 'ibmdb2';
$pconn = db2_pconnect($database, $user, $password);
if ($pconn) {
echo "Persistent connection succeeded.";
}
else {
echo "Persistent connection failed.";
}
$pconn2 = db2_pconnect($database, $user, $password);
if ($pconn) {
echo "Second persistent connection succeeded.";
}
else {
echo "Second persistent connection failed.";
}
?>
Powyższy przykład wyświetli:
Persistent connection succeeded. Second persistent connection succeeded.
Przykład #2 Using trusted context
The following example shows how to enable trusted context, switch users, and get the current user ID.
<?php
$database = "SAMPLE";
$hostname = "localhost";
$port = 50000;
$authID = "db2inst1";
$auth_pass = "ibmdb2";
$tc_user = "tcuser";
$tc_pass = "tcpassword";
$dsn = "DATABASE=$database;HOSTNAME=$hostname;PORT=$port;
PROTOCOL=TCPIP;UID=$authID;PWD=$auth_pass;";
$options = array ("trustedcontext" => DB2_TRUSTED_CONTEXT_ENABLE);
$tc_conn = db2_pconnect($dsn, "", "", $options);
if($tc_conn) {
echo "Explicit trusted connection succeeded.\n";
if(db2_get_option($tc_conn, "trustedcontext")) {
$userBefore = db2_get_option($tc_conn, "trusted_user");
//Do some work as user 1.
//Switching to trusted user.
$parameters = array("trusted_user" => $tc_user,
"trusted_password" => $tcuser_pass);
$res = db2_set_option ($tc_conn, $parameters, 1);
$userAfter = db2_get_option($tc_conn, "trusted_user");
//Do more work as trusted user.
if($userBefore != $userAfter) {
echo "User has been switched." . "\n";
}
}
db2_close($tc_conn);
}
else {
echo "Explicit trusted connection failed.\n";
}
?>
Powyższy przykład wyświetli:
Explicit trusted connection succeeded. User has been switched.
db2_prepare
(PECL ibm_db2 >= 1.0.0)
db2_prepare — Prepares an SQL statement to be executed
Opis
$connection
, string $statement
[, array $options
] )db2_prepare() creates a prepared SQL statement which can include 0 or more parameter markers (? characters) representing parameters for input, output, or input/output. You can pass parameters to the prepared statement using db2_bind_param(), or for input values only, as an array passed to db2_execute().
There are three main advantages to using prepared statements in your application:
-
Performance: when you prepare a statement, the database server creates an optimized access plan for retrieving data with that statement. Subsequently issuing the prepared statement with db2_execute() enables the statements to reuse that access plan and avoids the overhead of dynamically creating a new access plan for every statement you issue.
-
Security: when you prepare a statement, you can include parameter markers for input values. When you execute a prepared statement with input values for placeholders, the database server checks each input value to ensure that the type matches the column definition or parameter definition.
-
Advanced functionality: Parameter markers not only enable you to pass input values to prepared SQL statements, they also enable you to retrieve OUT and INOUT parameters from stored procedures using db2_bind_param().
Parametry
-
connection -
A valid database connection resource variable as returned from db2_connect() or db2_pconnect().
-
statement -
An SQL statement, optionally containing one or more parameter markers..
-
options -
An associative array containing statement options. You can use this parameter to request a scrollable cursor on database servers that support this functionality.
For a description of valid statement options, see db2_set_option().
Zwracane wartości
Returns a statement resource if the SQL statement was successfully parsed and
prepared by the database server. Returns FALSE if the database server
returned an error. You can determine which error was returned by calling
db2_stmt_error() or db2_stmt_errormsg().
Przykłady
Przykład #1 Preparing and executing an SQL statement with parameter markers
The following example prepares an INSERT statement that accepts four parameter markers, then iterates over an array of arrays containing the input values to be passed to db2_execute().
<?php
$animals = array(
array(0, 'cat', 'Pook', 3.2),
array(1, 'dog', 'Peaches', 12.3),
array(2, 'horse', 'Smarty', 350.0),
);
$insert = 'INSERT INTO animals (id, breed, name, weight)
VALUES (?, ?, ?, ?)';
$stmt = db2_prepare($conn, $insert);
if ($stmt) {
foreach ($animals as $animal) {
$result = db2_execute($stmt, $animal);
}
}
?>
Zobacz też:
- db2_bind_param() - Binds a PHP variable to an SQL statement parameter
- db2_execute() - Executes a prepared SQL statement
- db2_stmt_error() - Returns a string containing the SQLSTATE returned by an SQL statement
- db2_stmt_errormsg() - Returns a string containing the last SQL statement error message
db2_primary_keys
(PECL ibm_db2 >= 1.0.0)
db2_primary_keys — Returns a result set listing primary keys for a table
Opis
$connection
, string $qualifier
, string $schema
, string $table-name
)Returns a result set listing the primary keys for a table.
Parametry
-
connection -
A valid connection to an IBM DB2, Cloudscape, or Apache Derby database.
-
qualifier -
A qualifier for DB2 databases running on OS/390 or z/OS servers. For other databases, pass
NULLor an empty string. -
schema -
The schema which contains the tables. If
schemaisNULL, db2_primary_keys() matches the schema for the current connection. -
table-name -
The name of the table.
Zwracane wartości
Returns a statement resource with a result set containing rows describing the primary keys for the specified table. The result set is composed of the following columns:
| Column name | Description |
|---|---|
| TABLE_CAT | Name of the catalog for the table containing the primary key. The value is NULL if this table does not have catalogs. |
| TABLE_SCHEM | Name of the schema for the table containing the primary key. |
| TABLE_NAME | Name of the table containing the primary key. |
| COLUMN_NAME | Name of the column containing the primary key. |
| KEY_SEQ | 1-indexed position of the column in the key. |
| PK_NAME | The name of the primary key. |
Zobacz też:
- db2_column_privileges() - Returns a result set listing the columns and associated privileges for a table
- db2_columns() - Returns a result set listing the columns and associated metadata for a table
- db2_foreign_keys() - Returns a result set listing the foreign keys for a table
- db2_procedure_columns() - Returns a result set listing stored procedure parameters
- db2_procedures() - Returns a result set listing the stored procedures registered in a database
- db2_special_columns() - Returns a result set listing the unique row identifier columns for a table
- db2_statistics() - Returns a result set listing the index and statistics for a table
- db2_table_privileges() - Returns a result set listing the tables and associated privileges in a database
- db2_tables() - Returns a result set listing the tables and associated metadata in a database
db2_procedure_columns
(PECL ibm_db2 >= 1.0.0)
db2_procedure_columns — Returns a result set listing stored procedure parameters
Opis
$connection
, string $qualifier
, string $schema
, string $procedure
, string $parameter
)Returns a result set listing the parameters for one or more stored procedures.
Parametry
-
connection -
A valid connection to an IBM DB2, Cloudscape, or Apache Derby database.
-
qualifier -
A qualifier for DB2 databases running on OS/390 or z/OS servers. For other databases, pass
NULLor an empty string. -
schema -
The schema which contains the procedures. This parameter accepts a search pattern containing _ and % as wildcards.
-
procedure -
The name of the procedure. This parameter accepts a search pattern containing _ and % as wildcards.
-
parameter -
The name of the parameter. This parameter accepts a search pattern containing _ and % as wildcards. If this parameter is
NULL, all parameters for the specified stored procedures are returned.
Zwracane wartości
Returns a statement resource with a result set containing rows describing the parameters for the stored procedures matching the specified parameters. The rows are composed of the following columns:
| Column name | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| PROCEDURE_CAT | The catalog that contains the procedure. The value is NULL if
this table does not have catalogs. |
||||||||
| PROCEDURE_SCHEM | Name of the schema that contains the stored procedure. | ||||||||
| PROCEDURE_NAME | Name of the procedure. | ||||||||
| COLUMN_NAME | Name of the parameter. | ||||||||
| COLUMN_TYPE |
An integer value representing the type of the parameter:
|
||||||||
| DATA_TYPE | The SQL data type for the parameter represented as an integer value. | ||||||||
| TYPE_NAME | A string representing the data type for the parameter. | ||||||||
| COLUMN_SIZE | An integer value representing the size of the parameter. | ||||||||
| BUFFER_LENGTH | Maximum number of bytes necessary to store data for this parameter. | ||||||||
| DECIMAL_DIGITS |
The scale of the parameter, or NULL where scale is not applicable.
|
||||||||
| NUM_PREC_RADIX |
An integer value of either 10 (representing
an exact numeric data type), 2 (representing an
approximate numeric data type), or NULL (representing a data type for
which radix is not applicable).
|
||||||||
| NULLABLE | An integer value representing whether the parameter is nullable or not. | ||||||||
| REMARKS | Description of the parameter. | ||||||||
| COLUMN_DEF | Default value for the parameter. | ||||||||
| SQL_DATA_TYPE | An integer value representing the size of the parameter. | ||||||||
| SQL_DATETIME_SUB |
Returns an integer value representing a datetime subtype code,
or NULL for SQL data types to which this does not apply.
|
||||||||
| CHAR_OCTET_LENGTH |
Maximum length in octets for a character data type parameter, which
matches COLUMN_SIZE for single-byte character set data, or NULL for
non-character data types.
|
||||||||
| ORDINAL_POSITION | The 1-indexed position of the parameter in the CALL statement. | ||||||||
| IS_NULLABLE |
A string value where 'YES' means that the parameter accepts or
returns NULL values and 'NO' means that the parameter does not
accept or return NULL values.
|
Zobacz też:
- db2_column_privileges() - Returns a result set listing the columns and associated privileges for a table
- db2_columns() - Returns a result set listing the columns and associated metadata for a table
- db2_foreign_keys() - Returns a result set listing the foreign keys for a table
- db2_primary_keys() - Returns a result set listing primary keys for a table
- db2_procedures() - Returns a result set listing the stored procedures registered in a database
- db2_special_columns() - Returns a result set listing the unique row identifier columns for a table
- db2_statistics() - Returns a result set listing the index and statistics for a table
- db2_table_privileges() - Returns a result set listing the tables and associated privileges in a database
- db2_tables() - Returns a result set listing the tables and associated metadata in a database
db2_procedures
(PECL ibm_db2 >= 1.0.0)
db2_procedures — Returns a result set listing the stored procedures registered in a database
Opis
$connection
, string $qualifier
, string $schema
, string $procedure
)Returns a result set listing the stored procedures registered in a database.
Parametry
-
connection -
A valid connection to an IBM DB2, Cloudscape, or Apache Derby database.
-
qualifier -
A qualifier for DB2 databases running on OS/390 or z/OS servers. For other databases, pass
NULLor an empty string. -
schema -
The schema which contains the procedures. This parameter accepts a search pattern containing _ and % as wildcards.
-
procedure -
The name of the procedure. This parameter accepts a search pattern containing _ and % as wildcards.
Zwracane wartości
Returns a statement resource with a result set containing rows describing the stored procedures matching the specified parameters. The rows are composed of the following columns:
| Column name | Description |
|---|---|
| PROCEDURE_CAT | The catalog that contains the procedure. The value is NULL if
this table does not have catalogs. |
| PROCEDURE_SCHEM | Name of the schema that contains the stored procedure. |
| PROCEDURE_NAME | Name of the procedure. |
| NUM_INPUT_PARAMS | Number of input (IN) parameters for the stored procedure. |
| NUM_OUTPUT_PARAMS | Number of output (OUT) parameters for the stored procedure. |
| NUM_RESULT_SETS | Number of result sets returned by the stored procedure. |
| REMARKS | Any comments about the stored procedure. |
| PROCEDURE_TYPE | Always returns 1, indicating that the stored procedure does not return a return value. |
Zobacz też:
- db2_column_privileges() - Returns a result set listing the columns and associated privileges for a table
- db2_columns() - Returns a result set listing the columns and associated metadata for a table
- db2_foreign_keys() - Returns a result set listing the foreign keys for a table
- db2_primary_keys() - Returns a result set listing primary keys for a table
- db2_procedure_columns() - Returns a result set listing stored procedure parameters
- db2_special_columns() - Returns a result set listing the unique row identifier columns for a table
- db2_statistics() - Returns a result set listing the index and statistics for a table
- db2_table_privileges() - Returns a result set listing the tables and associated privileges in a database
- db2_tables() - Returns a result set listing the tables and associated metadata in a database
db2_result
(PECL ibm_db2 >= 1.0.0)
db2_result — Returns a single column from a row in the result set
Opis
Use db2_result() to return the value of a specified column in the current row of a result set. You must call db2_fetch_row() before calling db2_result() to set the location of the result set pointer.
Parametry
-
stmt -
A valid stmt resource.
-
column -
Either an integer mapping to the 0-indexed field in the result set, or a string matching the name of the column.
Zwracane wartości
Returns the value of the requested field if the field exists in the result set. Returns NULL if the field does not exist, and issues a warning.
Przykłady
Przykład #1 A db2_result() example
The following example demonstrates how to iterate through a result set with db2_fetch_row() and retrieve columns from the result set with db2_result().
<?php
$sql = 'SELECT name, breed FROM animals WHERE weight < ?';
$stmt = db2_prepare($conn, $sql);
db2_execute($stmt, array(10));
while (db2_fetch_row($stmt)) {
$name = db2_result($stmt, 0);
$breed = db2_result($stmt, 'BREED');
print "$name $breed";
}
?>
Powyższy przykład wyświetli:
cat Pook gold fish Bubbles budgerigar Gizmo goat Rickety Ride
Zobacz też:
- db2_fetch_array() - Returns an array, indexed by column position, representing a row in a result set
- db2_fetch_assoc() - Returns an array, indexed by column name, representing a row in a result set
- db2_fetch_both() - Returns an array, indexed by both column name and position, representing a row in a result set
- db2_fetch_object() - Returns an object with properties representing columns in the fetched row
- db2_fetch_row() - Sets the result set pointer to the next row or requested row
db2_rollback
(PECL ibm_db2 >= 1.0.0)
db2_rollback — Rolls back a transaction
Opis
$connection
)Rolls back an in-progress transaction on the specified connection resource and begins a new transaction. PHP applications normally default to AUTOCOMMIT mode, so db2_rollback() normally has no effect unless AUTOCOMMIT has been turned off for the connection resource.
Parametry
-
connection -
A valid database connection resource variable as returned from db2_connect() or db2_pconnect().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Rolling back a DELETE statement
In the following example, we count the number of rows in a table, turn off AUTOCOMMIT mode on a database connection, delete all of the rows in the table and return the count of 0 to prove that the rows have been removed. We then issue db2_rollback() and return the updated count of rows in the table to show that the number is the same as before we issued the DELETE statement. The return to the original state of the table demonstrates that the roll back of the transaction succeeded.
<?php
$conn = db2_connect($database, $user, $password);
if ($conn) {
$stmt = db2_exec($conn, "SELECT count(*) FROM animals");
$res = db2_fetch_array( $stmt );
echo $res[0] . "\n";
// Turn AUTOCOMMIT off
db2_autocommit($conn, DB2_AUTOCOMMIT_OFF);
// Delete all rows from ANIMALS
db2_exec($conn, "DELETE FROM animals");
$stmt = db2_exec($conn, "SELECT count(*) FROM animals");
$res = db2_fetch_array( $stmt );
echo $res[0] . "\n";
// Roll back the DELETE statement
db2_rollback( $conn );
$stmt = db2_exec( $conn, "SELECT count(*) FROM animals" );
$res = db2_fetch_array( $stmt );
echo $res[0] . "\n";
db2_close($conn);
}
?>
Powyższy przykład wyświetli:
7 0 7
Zobacz też:
- db2_autocommit() - Returns or sets the AUTOCOMMIT state for a database connection
- db2_commit() - Commits a transaction
db2_server_info
(PECL ibm_db2 >= 1.1.1)
db2_server_info — Returns an object with properties that describe the DB2 database server
Opis
$connection
)This function returns an object with read-only properties that return information about the IBM DB2, Cloudscape, or Apache Derby database server. The following table lists the database server properties:
| Property name | Return type | Description |
|---|---|---|
| DBMS_NAME | string | The name of the database server to which you are connected. For DB2 servers this is a combination of DB2 followed by the operating system on which the database server is running. |
| DBMS_VER | string | The version of the database server, in the form of a string "MM.mm.uuuu" where MM is the major version, mm is the minor version, and uuuu is the update. For example, "08.02.0001" represents major version 8, minor version 2, update 1. |
| DB_CODEPAGE | int | The code page of the database to which you are connected. |
| DB_NAME | string | The name of the database to which you are connected. |
| DFT_ISOLATION | string |
The default transaction isolation level supported by the server:
|
| IDENTIFIER_QUOTE_CHAR | string | The character used to delimit an identifier. |
| INST_NAME | string | The instance on the database server that contains the database. |
| ISOLATION_OPTION | array | An array of the isolation options supported by the database server. The isolation options are described in the DFT_ISOLATION property. |
| KEYWORDS | array | An array of the keywords reserved by the database server. |
| LIKE_ESCAPE_CLAUSE | bool | TRUE if the database server supports the
use of % and _ wildcard
characters. FALSE if the database server does not
support these wildcard characters. |
| MAX_COL_NAME_LEN | int | Maximum length of a column name supported by the database server, expressed in bytes. |
| MAX_IDENTIFIER_LEN | int | Maximum length of an SQL identifier supported by the database server, expressed in characters. |
| MAX_INDEX_SIZE | int | Maximum size of columns combined in an index supported by the database server, expressed in bytes. |
| MAX_PROC_NAME_LEN | int | Maximum length of a procedure name supported by the database server, expressed in bytes. |
| MAX_ROW_SIZE | int | Maximum length of a row in a base table supported by the database server, expressed in bytes. |
| MAX_SCHEMA_NAME_LEN | int | Maximum length of a schema name supported by the database server, expressed in bytes. |
| MAX_STATEMENT_LEN | int | Maximum length of an SQL statement supported by the database server, expressed in bytes. |
| MAX_TABLE_NAME_LEN | int | Maximum length of a table name supported by the database server, expressed in bytes. |
| NON_NULLABLE_COLUMNS | bool | TRUE if the database server supports columns that can be
defined as NOT NULL, FALSE if the database server does not support
columns defined as NOT NULL. |
| PROCEDURES | bool | TRUE if the database server supports the use of the CALL
statement to call stored procedures, FALSE if the database
server does not support the CALL statement. |
| SPECIAL_CHARS | string | A string containing all of the characters other than a-Z, 0-9, and underscore that can be used in an identifier name. |
| SQL_CONFORMANCE | string |
The level of conformance to the ANSI/ISO SQL-92 specification offered by the database server:
|
Parametry
-
connection -
Specifies an active DB2 client connection.
Zwracane wartości
Returns an object on a successful call. Returns FALSE on failure.
Przykłady
Przykład #1 A db2_server_info() example
To retrieve information about the server, you must pass a valid database connection resource to db2_server_info().
<?php
$conn = db2_connect('sample', 'db2inst1', 'ibmdb2');
$server = db2_server_info( $conn );
if ($server) {
echo "DBMS_NAME: "; var_dump( $server->DBMS_NAME );
echo "DBMS_VER: "; var_dump( $server->DBMS_VER );
echo "DB_CODEPAGE: "; var_dump( $server->DB_CODEPAGE );
echo "DB_NAME: "; var_dump( $server->DB_NAME );
echo "INST_NAME: "; var_dump( $server->INST_NAME );
echo "SPECIAL_CHARS: "; var_dump( $server->SPECIAL_CHARS );
echo "KEYWORDS: "; var_dump( sizeof($server->KEYWORDS) );
echo "DFT_ISOLATION: "; var_dump( $server->DFT_ISOLATION );
echo "ISOLATION_OPTION: ";
$il = '';
foreach( $server->ISOLATION_OPTION as $opt )
{
$il .= $opt." ";
}
var_dump( $il );
echo "SQL_CONFORMANCE: "; var_dump( $server->SQL_CONFORMANCE );
echo "PROCEDURES: "; var_dump( $server->PROCEDURES );
echo "IDENTIFIER_QUOTE_CHAR: "; var_dump( $server->IDENTIFIER_QUOTE_CHAR );
echo "LIKE_ESCAPE_CLAUSE: "; var_dump( $server->LIKE_ESCAPE_CLAUSE );
echo "MAX_COL_NAME_LEN: "; var_dump( $server->MAX_COL_NAME_LEN );
echo "MAX_ROW_SIZE: "; var_dump( $server->MAX_ROW_SIZE );
echo "MAX_IDENTIFIER_LEN: "; var_dump( $server->MAX_IDENTIFIER_LEN );
echo "MAX_INDEX_SIZE: "; var_dump( $server->MAX_INDEX_SIZE );
echo "MAX_PROC_NAME_LEN: "; var_dump( $server->MAX_PROC_NAME_LEN );
echo "MAX_SCHEMA_NAME_LEN: "; var_dump( $server->MAX_SCHEMA_NAME_LEN );
echo "MAX_STATEMENT_LEN: "; var_dump( $server->MAX_STATEMENT_LEN );
echo "MAX_TABLE_NAME_LEN: "; var_dump( $server->MAX_TABLE_NAME_LEN );
echo "NON_NULLABLE_COLUMNS: "; var_dump( $server->NON_NULLABLE_COLUMNS );
db2_close($conn);
}
?>
Powyższy przykład wyświetli:
DBMS_NAME: string(9) "DB2/LINUX" DBMS_VER: string(10) "08.02.0000" DB_CODEPAGE: int(1208) DB_NAME: string(6) "SAMPLE" INST_NAME: string(8) "db2inst1" SPECIAL_CHARS: string(2) "@#" KEYWORDS: int(179) DFT_ISOLATION: string(2) "CS" ISOLATION_OPTION: string(12) "UR CS RS RR " SQL_CONFORMANCE: string(7) "FIPS127" PROCEDURES: bool(true) IDENTIFIER_QUOTE_CHAR: string(1) """ LIKE_ESCAPE_CLAUSE: bool(true) MAX_COL_NAME_LEN: int(30) MAX_ROW_SIZE: int(32677) MAX_IDENTIFIER_LEN: int(18) MAX_INDEX_SIZE: int(1024) MAX_PROC_NAME_LEN: int(128) MAX_SCHEMA_NAME_LEN: int(30) MAX_STATEMENT_LEN: int(2097152) MAX_TABLE_NAME_LEN: int(128) NON_NULLABLE_COLUMNS: bool(true)
Zobacz też:
- db2_client_info() - Returns an object with properties that describe the DB2 database client
db2_set_option
(PECL ibm_db2 >= 1.0.0)
db2_set_option — Set options for connection or statement resources
Opis
$resource
, array $options
, int $type
)Sets options for a statement resource or a connection resource. You cannot set options for result set resources.
Parametry
-
resource -
A valid statement resource as returned from db2_prepare() or a valid connection resource as returned from db2_connect() or db2_pconnect().
-
options -
An associative array containing valid statement or connection options. This parameter can be used to change autocommit values, cursor types (scrollable or forward), and to specify the case of the column names (lower, upper, or natural) that will appear in a result set.
-
autocommit -
Passing DB2_AUTOCOMMIT_ON turns autocommit on for the specified connection resource.
Passing DB2_AUTOCOMMIT_OFF turns autocommit off for the specified connection resource.
-
cursor -
Passing DB2_FORWARD_ONLY specifies a forward-only cursor for a statement resource. This is the default cursor type, and is supported by all database servers.
Passing DB2_SCROLLABLE specifies a scrollable cursor for a statement resource. Scrollable cursors enable result set rows to be accessed in non-sequential order, but are only supported by IBM DB2 Universal Database databases.
-
binmode -
Passing DB2_BINARY specifies that binary data will be returned as is. This is the default mode. This is the equivalent of setting ibm_db2.binmode=1 in php.ini.
Passing DB2_CONVERT specifies that binary data will be converted to hexadecimal encoding, and will be returned as such. This is the equivalent of setting ibm_db2.binmode=2 in php.ini.
Passing DB2_PASSTHRU specifies that binary data will be converted to
NULL. This is the equivalent of setting ibm_db2.binmode=3 in php.ini. -
db2_attr_case -
Passing DB2_CASE_LOWER specifies that column names of the result set are returned in lower case.
Passing DB2_CASE_UPPER specifies that column names of the result set are returned in upper case.
Passing DB2_CASE_NATURAL specifies that column names of the result set are returned in natural case.
-
deferred_prepare -
Passing DB2_DEFERRED_PREPARE_ON turns deferred prepare on for the specified statement resource.
Passing DB2_DEFERRED_PREPARE_OFF turns deferred prepare off for the specified statement resource.
The following new i5/OS options are available in ibm_db2 version 1.5.1 and later. These options apply only when running PHP and ibm_db2 natively on i5 systems.
-
i5_fetch_only -
DB2_I5_FETCH_ON - Cursors are read-only and cannot be used for positioned updates or deletes. This is the default unless SQL_ATTR_FOR_FETCH_ONLY environment has been set to SQL_FALSE.
DB2_I5_FETCH_OFF - Cursors can be used for positioned updates and deletes.
The following new option is available in ibm_db2 version 1.8.0 and later.
-
rowcount -
DB2_ROWCOUNT_PREFETCH_ON - Client can request the full row count prior to fetching, which means that db2_num_rows() returns the number of rows selected even when a ROLLFORWARD_ONLY cursor is used.
DB2_ROWCOUNT_PREFETCH_OFF - Client cannot request the full row count prior to fetching.
The following new options are available in ibm_db2 version 1.7.0 and later.
-
trusted_user -
To switch the user to a trusted user, pass the User ID (String) of the trusted user as the value of this key. This option can be set on a connection resource only. To use this option, trusted context must be enabled on the connection resource.
-
trusted_password -
The password (String) that corresponds to the user specified by the trusted_user key.
The following new options are available in ibm_db2 version 1.6.0 and later. These options provide useful tracking information that can be accessed during execution with db2_get_option().
Informacja:
When the value in each option is being set, some servers might not handle the entire length provided and might truncate the value.
To ensure that the data specified in each option is converted correctly when transmitted to a host system, use only the characters A through Z, 0 through 9, and the underscore (_) or period (.).
-
userid -
SQL_ATTR_INFO_USERID - A pointer to a null-terminated character string used to identify the client user ID sent to the host database server when using DB2 Connect.
Informacja:
DB2 for z/OS and OS/390 servers support up to a length of 16 characters. This user-id is not to be confused with the authentication user-id, it is for identification purposes only and is not used for any authorization.
-
acctstr -
SQL_ATTR_INFO_ACCTSTR - A pointer to a null-terminated character string used to identify the client accounting string sent to the host database server when using DB2 Connect.
Informacja:
DB2 for z/OS and OS/390 servers support up to a length of 200 characters.
-
applname -
SQL_ATTR_INFO_APPLNAME - A pointer to a null-terminated character string used to identify the client application name sent to the host database server when using DB2 Connect.
Informacja:
DB2 for z/OS and OS/390 servers support up to a length of 32 characters.
-
wrkstnname -
SQL_ATTR_INFO_WRKSTNNAME - A pointer to a null-terminated character string used to identify the client workstation name sent to the host database server when using DB2 Connect.
Informacja:
DB2 for z/OS and OS/390 servers support up to a length of 18 characters.
-
-
type -
An integer value that specifies the type of resource that was passed into the function. The type of resource and this value must correspond.
Passing 1 as the value specifies that a connection resource has been passed into the function.
Passing any integer not equal to 1 as the value specifies that a statement resource has been passed into the function.
The following table specifies which options are compatible with the available resource types:
| Key | Value | Resource Type | ||
|---|---|---|---|---|
| Connection | Statement | Result Set | ||
| autocommit | DB2_AUTOCOMMIT_ON | X | - | - |
| autocommit | DB2_AUTOCOMMIT_OFF | X | - | - |
| cursor | DB2_SCROLLABLE | - | X | - |
| cursor | DB2_FORWARD_ONLY | - | X | - |
| binmode | DB2_BINARY | X | X | - |
| binmode | DB2_CONVERT | X | X | - |
| binmode | DB2_PASSTHRU | X | X | - |
| db2_attr_case | DB2_CASE_LOWER | X | X | - |
| db2_attr_case | DB2_CASE_UPPER | X | X | - |
| db2_attr_case | DB2_CASE_NATURAL | X | X | - |
| deferred_prepare | DB2_DEFERRED_PREPARE_ON | - | X | - |
| deferred_prepare | DB2_DEFERRED_PREPARE_OFF | - | X | - |
| i5_fetch_only | DB2_I5_FETCH_ON | - | X | - |
| i5_fetch_only | DB2_I5_FETCH_OFF | - | X | - |
| rowcount | DB2_ROWCOUNT_PREFETCH_ON | - | X | - |
| rowcount | DB2_ROWCOUNT_PREFETCH_OFF | - | X | - |
| trusted_user | <USER NAME> (String) | X | - | - |
| trusted_password | <PASSWORD> (String) | X | - | - |
| userid | SQL_ATTR_INFO_USERID | X | X | - |
| acctstr | SQL_ATTR_INFO_ACCTSTR | X | X | - |
| applname | SQL_ATTR_INFO_APPLNAME | X | X | - |
| wrkstnname | SQL_ATTR_INFO_WRKSTNNAME | X | X | - |
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Setting one parameter with a connection resource
<?php
/* Database Connection Parameters */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';
/* Connection String */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";
/* Obtain Connection Resource */
$conn = db2_connect($conn_string, '', '');
/* Create the associative options array with valid key-value pairs */
$options = array('autocommit' => DB2_AUTOCOMMIT_ON);
/* Call the function using the correct resource, options array, and type values */
$result = db2_set_option($conn, $options, 1);
/* Check if all options could be set correctly */
if($result)
{
echo 'Options Set Successfully';
}
else
{
echo 'Could Not Set Options';
}
?>
Powyższy przykład wyświetli:
Options Set Successfully
Przykład #2 Setting multiple parameters with a connection resource
<?php
/* Database Connection Parameters */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';
/* Connection String */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";
/* Obtain Connection Resource */
$conn = db2_connect($conn_string, '', '');
/* Create the associative options array with valid key-value pairs */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
'binmode' => DB2_PASSTHRU,
'db2_attr_case' => DB2_CASE_UPPER,
'cursor' => DB2_SCROLLABLE);
/* Call the function using the correct resource, options array, and type values */
$result = db2_set_option($conn, $options, 1);
/* Check if all options could be set correctly */
if($result)
{
echo 'Options Set Successfully';
}
else
{
echo 'Could Not Set Options';
}
?>
Powyższy przykład wyświetli:
Options Set Successfully
Przykład #3 Setting multiple parameters with an invalid key
<?php
/* Database Connection Parameters */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';
/* Connection String */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";
/* Obtain Connection Resource */
$conn = db2_connect($conn_string, '', '');
/* Create the associative options array with valid key-value pairs */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
'MY_INVALID_KEY' => DB2_PASSTHRU,
'db2_attr_case' => DB2_CASE_UPPER,
'cursor' => DB2_SCROLLABLE);
/* Call the function using the correct resource, options array, and type values */
$result = db2_set_option($conn, $options, 1);
/* Check if all options could be set correctly */
if($result)
{
echo 'Options Set Successfully';
}
else
{
echo 'Could Not Set Options';
}
?>
Powyższy przykład wyświetli:
Could Not Set Options
Przykład #4 Setting multiple parameters with an invalid value
<?php
/* Database Connection Parameters */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';
/* Connection String */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";
/* Obtain Connection Resource */
$conn = db2_connect($conn_string, '', '');
/* Create the associative options array with valid key-value pairs */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
'binmode' => 'INVALID_VALUE',
'db2_attr_case' => DB2_CASE_UPPER,
'cursor' => DB2_SCROLLABLE);
/* Call the function using the correct resource, options array, and type values */
$result = db2_set_option($conn, $options, 1);
/* Check if all options could be set correctly */
if($result)
{
echo 'Options Set Successfully';
}
else
{
echo 'Could Not Set Options';
}
?>
Powyższy przykład wyświetli:
Could Not Set Options
Przykład #5 Setting multiple parameters with a connection resource and the wrong type
<?php
/* Database Connection Parameters */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';
/* Connection String */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";
/* Obtain Connection Resource */
$conn = db2_connect($conn_string, '', '');
/* Create the associative options array with valid key-value pairs */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
'binmode' => DB2_PASSTHRU,
'db2_attr_case' => DB2_CASE_UPPER,
'cursor' => DB2_SCROLLABLE);
/* Call the function using the correct resource, options array, and the wrong type value */
$result = db2_set_option($conn, $options, 2);
/* Check if all options could be set correctly */
if($result)
{
echo 'Options Set Successfully';
}
else
{
echo 'Could Not Set Options';
}
?>
Powyższy przykład wyświetli:
Could Not Set Options
Przykład #6 Setting multiple parameters with the wrong resource
<?php
/* Database Connection Parameters */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';
/* Connection String */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";
/* Obtain Connection Resource */
$conn = db2_connect($conn_string, '', '');
/* Create the associative options array with valid key-value pairs */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
'binmode' => DB2_PASSTHRU,
'db2_attr_case' => DB2_CASE_UPPER,
'cursor' => DB2_SCROLLABLE);
$stmt = db2_prepare($conn, 'SELECT * FROM EMPLOYEE');
/* Call the function using the wrong resource, and the correct options array, and type values */
$result = db2_set_option($stmt, $options, 1);
/* Check if all options could be set correctly */
if($result)
{
echo 'Options Set Successfully';
}
else
{
echo 'Could Not Set Options';
}
?>
Powyższy przykład wyświetli:
Could Not Set Options
Przykład #7 Putting it all together
<?php
/* Database Connection Parameters */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';
/* Connection String */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";
/* Obtain Connection Resource */
$conn = db2_connect($conn_string, '', '');
/* Create the associative options array with valid key-value pairs */
$options = array('db2_attr_case' => DB2_CASE_LOWER,
'cursor' => DB2_SCROLLABLE);
$stmt = db2_prepare($conn, 'SELECT * FROM EMPLOYEE WHERE EMPNO = ? OR EMPNO = ?');
/* Call the function using the correct resource, options array, and type values */
$option_result = db2_set_option($stmt, $options, 2);
$result = db2_execute($stmt, array('000130', '000140'));
/* Get Row 2 before Row 1 since Scrollable Cursor */
print_r(db2_fetch_assoc($stmt, 2));
print '<br /><br />';
print_r(db2_fetch_assoc($stmt, 1));
?>
Powyższy przykład wyświetli:
Array
(
[empno] => 000140
[firstnme] => HEATHER
[midinit] => A
[lastname] => NICHOLLS
[workdept] => C01
[phoneno] => 1793
[hiredate] => 1976-12-15
[job] => ANALYST
[edlevel] => 18
[sex] => F
[birthdate] => 1946-01-19
[salary] => 28420.00
[bonus] => 600.00
[comm] => 2274.00
)
Array
(
[empno] => 000130
[firstnme] => DELORES
[midinit] => M
[lastname] => QUINTANA
[workdept] => C01
[phoneno] => 4578
[hiredate] => 1971-07-28
[job] => ANALYST
[edlevel] => 16
[sex] => F
[birthdate] => 1925-09-15
[salary] => 23800.00
[bonus] => 500.00
[comm] => 1904.00
)Przykład #8 i5/OS cursors are read-only
<?php
$conn = db2_connect("", "", "", array("i5_lib"=>"nobody"));
$stmt = db2_prepare($conn, 'select * from names where first = ?');
$name = "first2";
db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
$options = array("i5_fetch_only"=>DB2_I5_FETCH_ON);
db2_set_option($stmt,$options,0);
if (db2_execute($stmt)) {
while ($row = db2_fetch_array($stmt)) {
echo "{$row[0]} {$row[1]}";
}
}
?>
Powyższy przykład wyświetli:
first2 last2
Zobacz też:
- db2_connect() - Returns a connection to a database
- db2_pconnect() - Returns a persistent connection to a database
- db2_exec() - Executes an SQL statement directly
- db2_prepare() - Prepares an SQL statement to be executed
- db2_cursor_type() - Returns the cursor type used by a statement resource
db2_special_columns
(PECL ibm_db2 >= 1.0.0)
db2_special_columns — Returns a result set listing the unique row identifier columns for a table
Opis
$connection
, string $qualifier
, string $schema
, string $table_name
, int $scope
)Returns a result set listing the unique row identifier columns for a table.
Parametry
-
connection -
A valid connection to an IBM DB2, Cloudscape, or Apache Derby database.
-
qualifier -
A qualifier for DB2 databases running on OS/390 or z/OS servers. For other databases, pass
NULLor an empty string. -
schema -
The schema which contains the tables.
-
table_name -
The name of the table.
-
scope -
Integer value representing the minimum duration for which the unique row identifier is valid. This can be one of the following values:
Integer value SQL constant Description 0 SQL_SCOPE_CURROW Row identifier is valid only while the cursor is positioned on the row. 1 SQL_SCOPE_TRANSACTION Row identifier is valid for the duration of the transaction. 2 SQL_SCOPE_SESSION Row identifier is valid for the duration of the connection.
Zwracane wartości
Returns a statement resource with a result set containing rows with unique row identifier information for a table. The rows are composed of the following columns:
| Column name | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| SCOPE |
|
||||||||||||
| COLUMN_NAME | Name of the unique column. | ||||||||||||
| DATA_TYPE | SQL data type for the column. | ||||||||||||
| TYPE_NAME | Character string representation of the SQL data type for the column. | ||||||||||||
| COLUMN_SIZE | An integer value representing the size of the column. | ||||||||||||
| BUFFER_LENGTH | Maximum number of bytes necessary to store data from this column. | ||||||||||||
| DECIMAL_DIGITS |
The scale of the column, or NULL where scale is not applicable.
|
||||||||||||
| NUM_PREC_RADIX |
An integer value of either 10 (representing
an exact numeric data type), 2 (representing an
approximate numeric data type), or NULL (representing a data type for
which radix is not applicable).
|
||||||||||||
| PSEUDO_COLUMN | Always returns 1. |
Zobacz też:
- db2_column_privileges() - Returns a result set listing the columns and associated privileges for a table
- db2_columns() - Returns a result set listing the columns and associated metadata for a table
- db2_foreign_keys() - Returns a result set listing the foreign keys for a table
- db2_primary_keys() - Returns a result set listing primary keys for a table
- db2_procedure_columns() - Returns a result set listing stored procedure parameters
- db2_procedures() - Returns a result set listing the stored procedures registered in a database
- db2_statistics() - Returns a result set listing the index and statistics for a table
- db2_table_privileges() - Returns a result set listing the tables and associated privileges in a database
- db2_tables() - Returns a result set listing the tables and associated metadata in a database
db2_statistics
(PECL ibm_db2 >= 1.0.0)
db2_statistics — Returns a result set listing the index and statistics for a table
Opis
$connection
, string $qualifier
, string $schema
, string $table-name
, bool $unique
)Returns a result set listing the index and statistics for a table.
Parametry
-
connection -
A valid connection to an IBM DB2, Cloudscape, or Apache Derby database.
-
qualifier -
A qualifier for DB2 databases running on OS/390 or z/OS servers. For other databases, pass
NULLor an empty string. -
schema -
The schema that contains the targeted table. If this parameter is
NULL, the statistics and indexes are returned for the schema of the current user. -
table_name -
The name of the table.
-
unique -
An integer value representing the type of index information to return.
-
0 -
Return only the information for unique indexes on the table.
-
1 -
Return the information for all indexes on the table.
-
Zwracane wartości
Returns a statement resource with a result set containing rows describing the statistics and indexes for the base tables matching the specified parameters. The rows are composed of the following columns:
| Column name | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| TABLE_CAT | The catalog that contains the table. The value is NULL if
this table does not have catalogs. |
||||||||||
| TABLE_SCHEM | Name of the schema that contains the table. | ||||||||||
| TABLE_NAME | Name of the table. | ||||||||||
| NON_UNIQUE |
An integer value representing whether the index prohibits unique values, or whether the row represents statistics on the table itself:
|
||||||||||
| INDEX_QUALIFIER | A string value representing the qualifier that would have to be prepended to INDEX_NAME to fully qualify the index. | ||||||||||
| INDEX_NAME | A string representing the name of the index. | ||||||||||
| TYPE |
An integer value representing the type of information contained in this row of the result set:
|
||||||||||
| ORDINAL_POSITION | The 1-indexed position of the column in the index. NULL if
the row contains statistics information about the table itself. |
||||||||||
| COLUMN_NAME | The name of the column in the index. NULL if the row
contains statistics information about the table itself. |
||||||||||
| ASC_OR_DESC |
A if the column is sorted in ascending order,
D if the column is sorted in descending order,
NULL if the row contains statistics information about the table
itself.
|
||||||||||
| CARDINALITY |
If the row contains information about an index, this column contains an integer value representing the number of unique values in the index. If the row contains information about the table itself, this column contains an integer value representing the number of rows in the table. |
||||||||||
| PAGES |
If the row contains information about an index, this column contains an integer value representing the number of pages used to store the index. If the row contains information about the table itself, this column contains an integer value representing the number of pages used to store the table. |
||||||||||
| FILTER_CONDITION | Always returns NULL. |
Zobacz też:
- db2_column_privileges() - Returns a result set listing the columns and associated privileges for a table
- db2_columns() - Returns a result set listing the columns and associated metadata for a table
- db2_foreign_keys() - Returns a result set listing the foreign keys for a table
- db2_primary_keys() - Returns a result set listing primary keys for a table
- db2_procedure_columns() - Returns a result set listing stored procedure parameters
- db2_procedures() - Returns a result set listing the stored procedures registered in a database
- db2_special_columns() - Returns a result set listing the unique row identifier columns for a table
- db2_table_privileges() - Returns a result set listing the tables and associated privileges in a database
- db2_tables() - Returns a result set listing the tables and associated metadata in a database
db2_stmt_error
(PECL ibm_db2 >= 1.0.0)
db2_stmt_error — Returns a string containing the SQLSTATE returned by an SQL statement
Opis
$stmt
] )Returns a string containing the SQLSTATE value returned by an SQL statement.
If you do not pass a statement resource as an argument to db2_stmt_error(), the driver returns the SQLSTATE value associated with the last attempt to return a statement resource, for example, from db2_prepare() or db2_exec().
To learn what the SQLSTATE value means, you can issue the following command
at a DB2 Command Line Processor prompt:
db2 '? . You
can also call db2_stmt_errormsg() to retrieve an
explicit error message and the associated SQLCODE value.
sqlstate-value'
Parametry
-
stmt -
A valid statement resource.
Zwracane wartości
Returns a string containing an SQLSTATE value.
Zobacz też:
- db2_conn_error() - Returns a string containing the SQLSTATE returned by the last connection attempt
- db2_conn_errormsg() - Returns the last connection error message and SQLCODE value
- db2_stmt_errormsg() - Returns a string containing the last SQL statement error message
db2_stmt_errormsg
(PECL ibm_db2 >= 1.0.0)
db2_stmt_errormsg — Returns a string containing the last SQL statement error message
Opis
$stmt
] )Returns a string containing the last SQL statement error message.
If you do not pass a statement resource as an argument to db2_stmt_errormsg(), the driver returns the error message associated with the last attempt to return a statement resource, for example, from db2_prepare() or db2_exec().
Parametry
-
stmt -
A valid statement resource.
Zwracane wartości
Returns a string containing the error message and SQLCODE value for the last error that occurred issuing an SQL statement.
Zobacz też:
- db2_conn_error() - Returns a string containing the SQLSTATE returned by the last connection attempt
- db2_conn_errormsg() - Returns the last connection error message and SQLCODE value
- db2_stmt_error() - Returns a string containing the SQLSTATE returned by an SQL statement
db2_table_privileges
(PECL ibm_db2 >= 1.0.0)
db2_table_privileges — Returns a result set listing the tables and associated privileges in a database
Opis
$connection
[, string $qualifier
[, string $schema
[, string $table_name
]]] )Returns a result set listing the tables and associated privileges in a database.
Parametry
-
connection -
A valid connection to an IBM DB2, Cloudscape, or Apache Derby database.
-
qualifier -
A qualifier for DB2 databases running on OS/390 or z/OS servers. For other databases, pass
NULLor an empty string. -
schema -
The schema which contains the tables. This parameter accepts a search pattern containing _ and % as wildcards.
-
table_name -
The name of the table. This parameter accepts a search pattern containing _ and % as wildcards.
Zwracane wartości
Returns a statement resource with a result set containing rows describing the privileges for the tables that match the specified parameters. The rows are composed of the following columns:
| Column name | Description |
|---|---|
| TABLE_CAT | The catalog that contains the table. The value is NULL if
this table does not have catalogs. |
| TABLE_SCHEM | Name of the schema that contains the table. |
| TABLE_NAME | Name of the table. |
| GRANTOR | Authorization ID of the user who granted the privilege. |
| GRANTEE | Authorization ID of the user to whom the privilege was granted. |
| PRIVILEGE | The privilege that has been granted. This can be one of ALTER, CONTROL, DELETE, INDEX, INSERT, REFERENCES, SELECT, or UPDATE. |
| IS_GRANTABLE | A string value of "YES" or "NO" indicating whether the grantee can grant the privilege to other users. |
Zobacz też:
- db2_column_privileges() - Returns a result set listing the columns and associated privileges for a table
- db2_columns() - Returns a result set listing the columns and associated metadata for a table
- db2_foreign_keys() - Returns a result set listing the foreign keys for a table
- db2_primary_keys() - Returns a result set listing primary keys for a table
- db2_procedure_columns() - Returns a result set listing stored procedure parameters
- db2_procedures() - Returns a result set listing the stored procedures registered in a database
- db2_special_columns() - Returns a result set listing the unique row identifier columns for a table
- db2_statistics() - Returns a result set listing the index and statistics for a table
- db2_tables() - Returns a result set listing the tables and associated metadata in a database
db2_tables
(PECL ibm_db2 >= 1.0.0)
db2_tables — Returns a result set listing the tables and associated metadata in a database
Opis
$connection
[, string $qualifier
[, string $schema
[, string $table-name
[, string $table-type
]]]] )Returns a result set listing the tables and associated metadata in a database.
Parametry
-
connection -
A valid connection to an IBM DB2, Cloudscape, or Apache Derby database.
-
qualifier -
A qualifier for DB2 databases running on OS/390 or z/OS servers. For other databases, pass
NULLor an empty string. -
schema -
The schema which contains the tables. This parameter accepts a search pattern containing _ and % as wildcards.
-
table-name -
The name of the table. This parameter accepts a search pattern containing _ and % as wildcards.
-
table-type -
A list of comma-delimited table type identifiers. To match all table types, pass
NULLor an empty string. Valid table type identifiers include: ALIAS, HIERARCHY TABLE, INOPERATIVE VIEW, NICKNAME, MATERIALIZED QUERY TABLE, SYSTEM TABLE, TABLE, TYPED TABLE, TYPED VIEW, and VIEW.
Zwracane wartości
Returns a statement resource with a result set containing rows describing the tables that match the specified parameters. The rows are composed of the following columns:
| Column name | Description |
|---|---|
| TABLE_CAT | The catalog that contains the table. The value is NULL if
this table does not have catalogs. |
| TABLE_SCHEM | Name of the schema that contains the table. |
| TABLE_NAME | Name of the table. |
| TABLE_TYPE | Table type identifier for the table. |
| REMARKS | Description of the table. |
Zobacz też:
- db2_column_privileges() - Returns a result set listing the columns and associated privileges for a table
- db2_columns() - Returns a result set listing the columns and associated metadata for a table
- db2_foreign_keys() - Returns a result set listing the foreign keys for a table
- db2_primary_keys() - Returns a result set listing primary keys for a table
- db2_procedure_columns() - Returns a result set listing stored procedure parameters
- db2_procedures() - Returns a result set listing the stored procedures registered in a database
- db2_special_columns() - Returns a result set listing the unique row identifier columns for a table
- db2_statistics() - Returns a result set listing the index and statistics for a table
- db2_table_privileges() - Returns a result set listing the tables and associated privileges in a database
Spis treści
- db2_autocommit — Returns or sets the AUTOCOMMIT state for a database connection
- db2_bind_param — Binds a PHP variable to an SQL statement parameter
- db2_client_info — Returns an object with properties that describe the DB2 database client
- db2_close — Closes a database connection
- db2_column_privileges — Returns a result set listing the columns and associated privileges for a table
- db2_columns — Returns a result set listing the columns and associated metadata for a table
- db2_commit — Commits a transaction
- db2_conn_error — Returns a string containing the SQLSTATE returned by the last connection attempt
- db2_conn_errormsg — Returns the last connection error message and SQLCODE value
- db2_connect — Returns a connection to a database
- db2_cursor_type — Returns the cursor type used by a statement resource
- db2_escape_string — Used to escape certain characters
- db2_exec — Executes an SQL statement directly
- db2_execute — Executes a prepared SQL statement
- db2_fetch_array — Returns an array, indexed by column position, representing a row in a result set
- db2_fetch_assoc — Returns an array, indexed by column name, representing a row in a result set
- db2_fetch_both — Returns an array, indexed by both column name and position, representing a row in a result set
- db2_fetch_object — Returns an object with properties representing columns in the fetched row
- db2_fetch_row — Sets the result set pointer to the next row or requested row
- db2_field_display_size — Returns the maximum number of bytes required to display a column
- db2_field_name — Returns the name of the column in the result set
- db2_field_num — Returns the position of the named column in a result set
- db2_field_precision — Returns the precision of the indicated column in a result set
- db2_field_scale — Returns the scale of the indicated column in a result set
- db2_field_type — Returns the data type of the indicated column in a result set
- db2_field_width — Returns the width of the current value of the indicated column in a result set
- db2_foreign_keys — Returns a result set listing the foreign keys for a table
- db2_free_result — Frees resources associated with a result set
- db2_free_stmt — Frees resources associated with the indicated statement resource
- db2_get_option — Retrieves an option value for a statement resource or a connection resource
- db2_last_insert_id — Returns the auto generated ID of the last insert query that successfully executed on this connection
- db2_lob_read — Gets a user defined size of LOB files with each invocation
- db2_next_result — Requests the next result set from a stored procedure
- db2_num_fields — Returns the number of fields contained in a result set
- db2_num_rows — Returns the number of rows affected by an SQL statement
- db2_pclose — Closes a persistent database connection
- db2_pconnect — Returns a persistent connection to a database
- db2_prepare — Prepares an SQL statement to be executed
- db2_primary_keys — Returns a result set listing primary keys for a table
- db2_procedure_columns — Returns a result set listing stored procedure parameters
- db2_procedures — Returns a result set listing the stored procedures registered in a database
- db2_result — Returns a single column from a row in the result set
- db2_rollback — Rolls back a transaction
- db2_server_info — Returns an object with properties that describe the DB2 database server
- db2_set_option — Set options for connection or statement resources
- db2_special_columns — Returns a result set listing the unique row identifier columns for a table
- db2_statistics — Returns a result set listing the index and statistics for a table
- db2_stmt_error — Returns a string containing the SQLSTATE returned by an SQL statement
- db2_stmt_errormsg — Returns a string containing the last SQL statement error message
- db2_table_privileges — Returns a result set listing the tables and associated privileges in a database
- db2_tables — Returns a result set listing the tables and associated metadata in a database
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- IBM DB2 Funkcje
- db2_autocommit — Returns or sets the AUTOCOMMIT state for a database connection
- db2_bind_param — Binds a PHP variable to an SQL statement parameter
- db2_client_info — Returns an object with properties that describe the DB2 database client
- db2_close — Closes a database connection
- db2_column_privileges — Returns a result set listing the columns and associated privileges for a table
- db2_columns — Returns a result set listing the columns and associated metadata for a table
- db2_commit — Commits a transaction
- db2_conn_error — Returns a string containing the SQLSTATE returned by the last connection attempt
- db2_conn_errormsg — Returns the last connection error message and SQLCODE value
- db2_connect — Returns a connection to a database
- db2_cursor_type — Returns the cursor type used by a statement resource
- db2_escape_string — Used to escape certain characters
- db2_exec — Executes an SQL statement directly
- db2_execute — Executes a prepared SQL statement
- db2_fetch_array — Returns an array, indexed by column position, representing a row in a result set
- db2_fetch_assoc — Returns an array, indexed by column name, representing a row in a result set
- db2_fetch_both — Returns an array, indexed by both column name and position, representing a row in a result set
- db2_fetch_object — Returns an object with properties representing columns in the fetched row
- db2_fetch_row — Sets the result set pointer to the next row or requested row
- db2_field_display_size — Returns the maximum number of bytes required to display a column
- db2_field_name — Returns the name of the column in the result set
- db2_field_num — Returns the position of the named column in a result set
- db2_field_precision — Returns the precision of the indicated column in a result set
- db2_field_scale — Returns the scale of the indicated column in a result set
- db2_field_type — Returns the data type of the indicated column in a result set
- db2_field_width — Returns the width of the current value of the indicated column in a result set
- db2_foreign_keys — Returns a result set listing the foreign keys for a table
- db2_free_result — Frees resources associated with a result set
- db2_free_stmt — Frees resources associated with the indicated statement resource
- db2_get_option — Retrieves an option value for a statement resource or a connection resource
- db2_last_insert_id — Returns the auto generated ID of the last insert query that successfully executed on this connection
- db2_lob_read — Gets a user defined size of LOB files with each invocation
- db2_next_result — Requests the next result set from a stored procedure
- db2_num_fields — Returns the number of fields contained in a result set
- db2_num_rows — Returns the number of rows affected by an SQL statement
- db2_pclose — Closes a persistent database connection
- db2_pconnect — Returns a persistent connection to a database
- db2_prepare — Prepares an SQL statement to be executed
- db2_primary_keys — Returns a result set listing primary keys for a table
- db2_procedure_columns — Returns a result set listing stored procedure parameters
- db2_procedures — Returns a result set listing the stored procedures registered in a database
- db2_result — Returns a single column from a row in the result set
- db2_rollback — Rolls back a transaction
- db2_server_info — Returns an object with properties that describe the DB2 database server
- db2_set_option — Set options for connection or statement resources
- db2_special_columns — Returns a result set listing the unique row identifier columns for a table
- db2_statistics — Returns a result set listing the index and statistics for a table
- db2_stmt_error — Returns a string containing the SQLSTATE returned by an SQL statement
- db2_stmt_errormsg — Returns a string containing the last SQL statement error message
- db2_table_privileges — Returns a result set listing the tables and associated privileges in a database
- db2_tables — Returns a result set listing the tables and associated metadata in a database
Informix
Wstęp
The Informix driver for Informix (IDS) 7.x, SE 7.x, Universal Server (IUS) 9.x and IDS 2000 is implemented in "ifx.ec" and "php_informix.h" in the informix extension directory. IDS 7.x support is fairly complete, with full support for BYTE and TEXT columns. IUS 9.x support is partly finished: the new data types are there, but SLOB and CLOB support is still under construction.
Informacja:
To rozszerzenie zostało przeniesione do repozytorium » PECL i nie jest rozprowadzane z PHP od wersji 5.2.1.
Instalacja/Konfiguracja
Spis treści
Wymagania
Informacja: Configuration notes
You need a version of ESQL/C to compile the PHP Informix driver. ESQL/C versions from 7.2x on should be OK. ESQL/C is now part of the Informix Client SDK.
Make sure that the "INFORMIXDIR" variable has been set, and that $INFORMIXDIR/bin is in your PATH before you run the "configure" script.
Instalacja
To be able to use the functions defined in this module you must compile your PHP interpreter using the configure line --with-informix[=DIR] , where DIR is the Informix base install directory, defaults to nothing.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
Informacja:
Make sure that the Informix environment variables INFORMIXDIR and INFORMIXSERVER are available to the PHP ifx driver, and that the INFORMIX bin directory is in the PATH. Check this by running a script that contains a call to phpinfo() before you start testing. The phpinfo() output should list these environment variables. This is true for both CGI php and Apache mod_php. You may have to set these environment variables in your Apache startup script.
The Informix shared libraries should also be available to the loader (check LD_LIBRARY_PATH or ld.so.conf/ldconfig).
Informacja: Some notes on the use of BLOBs (TEXT and BYTE columns)
BLOBs are normally addressed by BLOB identifiers. Select queries return a "blob id" for every BYTE and TEXT column. You can get at the contents with "string_var = ifx_get_blob($blob_id);" if you choose to get the BLOBs in memory (with: "ifx_blobinfile(0);"). If you prefer to receive the content of BLOB columns in a file, use "ifx_blobinfile(1);", and "ifx_get_blob($blob_id);" will get you the filename. Use normal file I/O to get at the blob contents.
For insert/update queries you must create these "blob id's" yourself with "ifx_create_blob();". You then plug the blob id's into an array, and replace the blob columns with a question mark (?) in the query string. For updates/inserts, you are responsible for setting the blob contents with ifx_update_blob().
The behaviour of BLOB columns can be altered by configuration variables that also can be set at runtime:
configuration variable: ifx.textasvarchar
configuration variable: ifx.byteasvarchar
runtime functions:
ifx_textasvarchar(0): use blob id's for select queries with TEXT columns
ifx_byteasvarchar(0): use blob id's for select queries with BYTE columns
ifx_textasvarchar(1): return TEXT columns as if they were VARCHAR columns, so that you don't need to use blob id's for select queries.
ifx_byteasvarchar(1): return BYTE columns as if they were VARCHAR columns, so that you don't need to use blob id's for select queries.
configuration variable: ifx.blobinfile
runtime function:
ifx_blobinfile_mode(0): return BYTE columns in memory, the blob id lets you get at the contents.
ifx_blobinfile_mode(1): return BYTE columns in a file, the blob id lets you get at the file name.
If you set ifx_text/byteasvarchar to 1, you can use TEXT and BYTE columns in select queries just like normal (but rather long) VARCHAR fields. Since all strings are "counted" in PHP, this remains "binary safe". It is up to you to handle this correctly. The returned data can contain anything, you are responsible for the contents.
If you set ifx_blobinfile to 1, use the file name returned by ifx_get_blob(..) to get at the blob contents. Note that in this case YOU ARE RESPONSIBLE FOR DELETING THE TEMPORARY FILES CREATED BY INFORMIX when fetching the row. Every new row fetched will create new temporary files for every BYTE column.
The location of the temporary files can be influenced by the environment variable "blobdir", default is "." (the current directory). Something like: putenv(blobdir=tmpblob"); will ease the cleaning up of temp files accidentally left behind (their names all start with "blb").
Informacja: Automatically trimming "char" (SQLCHAR and SQLNCHAR) data
This can be set with the configuration variable
ifx.charasvarchar: if set to 1 trailing spaces will be automatically trimmed, to save you some "chopping".
Informacja:
NULLvalues
The configuration variable ifx.nullformat (and the runtime function ifx_nullformat()) when set to
TRUEwill returnNULLcolumns as the string "NULL", when set toFALSEthey return the empty string. This allows you to discriminate betweenNULLcolumns and empty columns.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| ifx.allow_persistent | "1" | PHP_INI_SYSTEM | Removed in PHP 5.2.1. |
| ifx.max_persistent | "-1" | PHP_INI_SYSTEM | Removed in PHP 5.2.1. |
| ifx.max_links | "-1" | PHP_INI_SYSTEM | Removed in PHP 5.2.1. |
| ifx.default_host | NULL | PHP_INI_SYSTEM | Removed in PHP 5.2.1. |
| ifx.default_user | NULL | PHP_INI_SYSTEM | Removed in PHP 5.2.1. |
| ifx.default_password | NULL | PHP_INI_SYSTEM | Removed in PHP 5.2.1. |
| ifx.blobinfile | "1" | PHP_INI_ALL | Removed in PHP 5.2.1. |
| ifx.textasvarchar | "0" | PHP_INI_ALL | Removed in PHP 5.2.1. |
| ifx.byteasvarchar | "0" | PHP_INI_ALL | Removed in PHP 5.2.1. |
| ifx.charasvarchar | "0" | PHP_INI_ALL | Removed in PHP 5.2.1. |
| ifx.nullformat | "0" | PHP_INI_ALL | Removed in PHP 5.2.1. |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
ifx.allow_persistentboolean -
Whether to allow persistent Informix connections.
-
ifx.max_persistentinteger -
The maximum number of persistent Informix connections per process.
-
ifx.max_linksinteger -
The maximum number of Informix connections per process, including persistent connections.
-
ifx.default_hoststring -
The default host to connect to when no host is specified in ifx_connect() or ifx_pconnect(). Doesn't apply in tryb bezpieczny.
-
ifx.default_userstring -
The default user id to use when none is specified in ifx_connect() or ifx_pconnect(). Doesn't apply in tryb bezpieczny.
-
ifx.default_passwordstring -
The default password to use when none is specified in ifx_connect() or ifx_pconnect(). Doesn't apply in tryb bezpieczny.
-
ifx.blobinfileboolean -
Set to
TRUEif you want to return blob columns in a file,FALSEif you want them in memory. You can override the setting at runtime with ifx_blobinfile_mode(). -
ifx.textasvarcharboolean -
Set to
TRUEif you want to return TEXT columns as normal strings in select statements,FALSEif you want to use blob id parameters. You can override the setting at runtime with ifx_textasvarchar(). -
ifx.byteasvarcharboolean -
Set to
TRUEif you want to return BYTE columns as normal strings in select queries,FALSEif you want to use blob id parameters. You can override the setting at runtime with ifx_textasvarchar(). -
ifx.charasvarcharboolean -
Set to
TRUEif you want to trim trailing spaces from CHAR columns when fetching them. -
ifx.nullformatboolean -
Set to
TRUEif you want to returnNULLcolumns as the literal string "NULL",FALSEif you want them returned as the empty string "". You can override this setting at runtime with ifx_nullformat().
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
Informix Funkcje
ifx_affected_rows
(PHP 4, PHP <=5.2.0)
ifx_affected_rows — Get number of rows affected by a query
Opis
$result_id
)
Returns the number of rows affected by a query associated with
result_id.
For inserts, updates and deletes the number is the real number (sqlerrd[2]) of affected rows. For selects it is an estimate (sqlerrd[0]). Don't rely on it. The database server can never return the actual number of rows that will be returned by a SELECT because it has not even begun fetching them at this stage (just after the "PREPARE" when the optimizer has determined the query plan).
Useful after ifx_prepare() to limit queries to reasonable result sets.
Zwracane wartości
Returns the number of rows as an integer.
Przykłady
Przykład #1 Informix affected rows
<?php
$rid = ifx_prepare("select * from emp
where name like " . $name, $connid);
if (! $rid) {
/* ... error ... */
}
$rowcount = ifx_affected_rows($rid);
if ($rowcount > 1000) {
printf ("Too many rows in result set (%d)\n<br />", $rowcount);
die ("Please restrict your query<br />\n");
}
?>
ifx_blobinfile_mode
(PHP 4, PHP <=5.2.0)
ifx_blobinfile_mode — Set the default blob mode for all select queries
Opis
$mode
)Set the default blob mode for all select queries.
Parametry
-
mode -
Mode "0" means save Byte-Blobs in memory, and mode "1" means save Byte-Blobs in a file.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
ifx_byteasvarchar
(PHP 4, PHP <=5.2.0)
ifx_byteasvarchar — Set the default byte mode
Opis
$mode
)Sets the default byte mode for all select-queries.
Parametry
-
mode -
Mode "0" will return a blob id, and mode "1" will return a varchar with text content.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
ifx_close
(PHP 4, PHP <=5.2.0)
ifx_close — Close Informix connection
Opis
$link_identifier
] )ifx_close() closes the link to an Informix database that's associated with the specified link identifier.
Note that this isn't usually necessary, as non-persistent open links are automatically closed at the end of the script's execution.
ifx_close() will not close persistent links generated by ifx_pconnect().
Parametry
-
link_identifier -
The link identifier. If not specified, the last opened link is assumed.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Closing a Informix connection
<?php
$conn_id = ifx_connect ("mydb@ol_srv", "itsme", "mypassword");
/* ... some queries and stuff ... */
ifx_close($conn_id);
?>
Zobacz też:
- ifx_connect() - Open Informix server connection
- ifx_pconnect() - Open persistent Informix connection
ifx_connect
(PHP 4, PHP <=5.2.0)
ifx_connect — Open Informix server connection
Opis
$database
[, string $userid
[, string $password
]]] )ifx_connect() establishes a connection to an Informix server.
In case a second call is made to ifx_connect() with the same arguments, no new link will be established, but instead, the link identifier of the already opened link will be returned.
The link to the server will be closed as soon as the execution of the script ends, unless it's closed earlier by explicitly calling ifx_close().
Parametry
All of the arguments are optional, and if they're missing, defaults are taken from values supplied in php.ini (ifx.default_host for the host (Informix libraries will use INFORMIXSERVER environment value if not defined), ifx.default_user for user, ifx.default_password for the password (none if not defined).
-
database -
The database name, as a string.
-
userid -
The username, as a string.
-
password -
The password, as a string.
Zwracane wartości
Returns a connection identifier on success, or FALSE on error.
Przykłady
Przykład #1 Connect to a Informix database
<?php
$conn_id = ifx_connect ("mydb@ol_srv1", "imyself", "mypassword");
?>
Zobacz też:
- ifx_pconnect() - Open persistent Informix connection
- ifx_close() - Close Informix connection
ifx_copy_blob
(PHP 4, PHP <=5.2.0)
ifx_copy_blob — Duplicates the given blob object
Opis
$bid
)Duplicates the given blob object.
Parametry
-
bid -
A BLOB identifier.
Zwracane wartości
Returns the new blob object-id, or FALSE on errors.
ifx_create_blob
(PHP 4, PHP <=5.2.0)
ifx_create_blob — Creates an blob object
Opis
$type
, int $mode
, string $param
)Creates a blob object.
Parametry
-
type -
1 = TEXT, 0 = BYTE
-
mode -
0 = blob-object holds the content in memory, 1 = blob-object holds the content in file.
-
param -
if mode = 0: pointer to the content, if mode = 1: pointer to the filestring.
Zwracane wartości
Returns the new BLOB object-id, or FALSE on errors.
Zobacz też:
- ifx_copy_blob() - Duplicates the given blob object
- ifx_free_blob() - Deletes the blob object
ifx_create_char
(PHP 4, PHP <=5.2.0)
ifx_create_char — Creates an char object
Opis
$param
)Creates an char object.
Parametry
-
param -
The char content.
Zwracane wartości
Returns the new char object id, or FALSE on errors.
ifx_do
(PHP 4, PHP <=5.2.0)
ifx_do — Execute a previously prepared SQL-statement
Opis
$result_id
)Executes a previously prepared query or opens a cursor for it.
Does NOT free result_id on error.
Also sets the real number of ifx_affected_rows() for non-select statements for retrieval by ifx_affected_rows().
Parametry
-
result_id -
result_idis a valid resultid returned by ifx_query() or ifx_prepare() (select type queries only!).
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
Przykład #1 ifx_do() Example
<?php
$conn = fx_connect( "db", "user", "password" );
$result = ifx_prepare("SELECT customer_num, company FROM customer", $conn);
ifx_do($result);
?>
ifx_error
(PHP 4, PHP <=5.2.0)
ifx_error — Returns error code of last Informix call
Opis
$link_identifier
] )Returns in a string one character describing the general results of a statement and both SQLSTATE and SQLCODE associated with the most recent SQL statement executed.
Parametry
-
link_identifier -
The link identifier.
Zwracane wartości
The Informix error codes (SQLSTATE & SQLCODE) formatted as x [SQLSTATE = aa bbb SQLCODE=cccc].
where x = space : no error
E : error
N : no more data
W : warning
? : undefined
If the "x" character is anything other than space, SQLSTATE and SQLCODE describe the error in more detail.
See the Informix manual for the description of SQLSTATE and SQLCODE
ifx_errormsg
(PHP 4, PHP <=5.2.0)
ifx_errormsg — Returns error message of last Informix call
Opis
$errorcode
] )Returns the Informix error message associated with the most recent Informix error.
Parametry
-
errorcode -
If specified, the function will return the message corresponding to the specified code.
Zwracane wartości
Return the error message, as a string.
Przykłady
Przykład #1 ifx_errormsg() example
<?php
printf("%s\n<br>", ifx_errormsg(-201));
?>
ifx_fetch_row
(PHP 4, PHP <=5.2.0)
ifx_fetch_row — Get row as an associative array
Opis
Fetches one row of data from the result associated with the specified result identifier.
Subsequent calls to ifx_fetch_row() would return the
next row in the result set, or FALSE if there are no more rows.
Parametry
-
result_id -
result_idis a valid resultid returned by ifx_query() or ifx_prepare() (select type queries only!). -
position -
An optional parameter for a "fetch" operation on "scroll" cursors: NEXT, PREVIOUS, CURRENT, FIRST, LAST or a number. If you specify a number, an "absolute" row fetch is executed. This parameter is optional, and only valid for SCROLL cursors.
Zwracane wartości
Returns an associative array that corresponds to the fetched row, or
FALSE if there are no more rows.
Blob columns are returned as integer blob id values for use in ifx_get_blob() unless you have used ifx_textasvarchar(1) or ifx_byteasvarchar(1), in which case blobs are returned as string values.
Przykłady
Przykład #1 Informix fetch rows
<?php
$rid = ifx_prepare ("select * from emp where name like " . $name,
$connid, IFX_SCROLL);
if (! $rid) {
/* ... error ... */
}
$rowcount = ifx_affected_rows($rid);
if ($rowcount > 1000) {
printf ("Too many rows in result set (%d)\n<br />", $rowcount);
die ("Please restrict your query<br />\n");
}
if (! ifx_do ($rid)) {
/* ... error ... */
}
$row = ifx_fetch_row ($rid, "NEXT");
while (is_array($row)) {
for (reset($row); $fieldname=key($row); next($row)) {
$fieldvalue = $row[$fieldname];
printf ("%s = %s,", $fieldname, $fieldvalue);
}
printf("\n<br />");
$row = ifx_fetch_row($rid, "NEXT");
}
ifx_free_result ($rid);
?>
ifx_fieldproperties
(PHP 4, PHP <=5.2.0)
ifx_fieldproperties — List of SQL fieldproperties
Opis
$result_id
)Returns the Informix SQL fieldproperties of every field in the query as an associative array. Properties are encoded as: "SQLTYPE;length;precision;scale;ISNULLABLE" where SQLTYPE = the Informix type like "SQLVCHAR" etc. and ISNULLABLE = "Y" or "N".
Parametry
-
result_id -
result_idis a valid resultid returned by ifx_query() or ifx_prepare() (select type queries only!).
Zwracane wartości
Returns an associative array with fieldnames as key and the SQL
fieldproperties as data for a query with result_id.
Returns FALSE on errors.
Przykłady
Przykład #1 Informix SQL fieldproperties
<?php
$properties = ifx_fieldproperties($resultid);
if (!isset($properties)) {
/* ... error ... */
}
foreach ($properties as $fname => $val) {
echo "$fname:\t property = $val\n";
}
?>
ifx_fieldtypes
(PHP 4, PHP <=5.2.0)
ifx_fieldtypes — List of Informix SQL fields
Opis
$result_id
)
Returns an associative array with fieldnames as key and the SQL
fieldtypes as data for the query associated with
result_id.
Parametry
-
result_id -
result_idis a valid resultid returned by ifx_query() or ifx_prepare() (select type queries only!).
Zwracane wartości
Returns an associative array with fieldnames as key and the SQL
fieldtypes as data for query with
result_id. Returns FALSE on error.
Przykłady
Przykład #1 Fieldnames and SQL fieldtypes
<?php
$types = ifx_fieldtypes($resultid);
if (is_array($types)) {
foreach ($types as $fname => $val) {
echo "$fname:\t type = $val\n";
}
}
?>
ifx_free_blob
(PHP 4, PHP <=5.2.0)
ifx_free_blob — Deletes the blob object
Opis
$bid
)Deletes the blobobject for the given blob object-id.
Parametry
-
bid -
The BLOB object id.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
ifx_free_char
(PHP 4, PHP <=5.2.0)
ifx_free_char — Deletes the char object
Opis
$bid
)Deletes the charobject for the given char object-id.
Parametry
-
bid -
The char object id.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
ifx_free_result
(PHP 4, PHP <=5.2.0)
ifx_free_result — Releases resources for the query
Opis
$result_id
)
Releases resources for the query associated with
result_id.
Parametry
-
result_id -
result_idis a valid resultid returned by ifx_query() or ifx_prepare() (select type queries only!).
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
ifx_get_blob
(PHP 4, PHP <=5.2.0)
ifx_get_blob — Return the content of a blob object
Opis
$bid
)Returns the content of the blob object.
Parametry
-
bid -
The BLOB object id.
Zwracane wartości
The contents of the BLOB as a string, or FALSE on errors.
ifx_get_char
(PHP 4, PHP <=5.2.0)
ifx_get_char — Return the content of the char object
Opis
$bid
)Returns the content of the char object.
Parametry
-
bid -
The char object-id.
Zwracane wartości
Returns the contents as a string, or FALSE on errors.
ifx_getsqlca
(PHP 4, PHP <=5.2.0)
ifx_getsqlca — Get the contents of sqlca.sqlerrd[0..5] after a query
Opis
$result_id
)
Returns a pseudo-row with sqlca.sqlerrd[0] ... sqlca.sqlerrd[5] after the
query associated with result_id.
For inserts, updates and deletes the values returned are those as set by the server after executing the query. This gives access to the number of affected rows and the serial insert value. For SELECTs the values are those saved after the PREPARE statement. This gives access to the *estimated* number of affected rows. The use of this function saves the overhead of executing a SELECT dbinfo('sqlca.sqlerrdx') query, as it retrieves the values that were saved by the ifx driver at the appropriate moment.
Parametry
-
result_id -
result_idis a valid result id returned by ifx_query() or ifx_prepare() (select type queries only!).
Zwracane wartości
Returns an associative array with the following entries: sqlerrd0, sqlerrd1, sqlerrd2, sqlerrd3, sqlerrd4 and sqlerrd5.
Przykłady
Przykład #1 Retrieve Informix sqlca.sqlerrd[x] values
<?php
/* assume the first column of 'sometable' is a serial */
$qid = ifx_query("insert into sometable
values (0, '2nd column', 'another column') ", $connid);
if (!$qid) {
/* ... error ... */
}
$sqlca = ifx_getsqlca($qid);
$serial_value = $sqlca["sqlerrd1"];
echo "The serial value of the inserted row is : $serial_value<br />\n";
?>
ifx_htmltbl_result
(PHP 4, PHP <=5.2.0)
ifx_htmltbl_result — Formats all rows of a query into a HTML table
Opis
$result_id
[, string $html_table_options
] )
Formats and prints all rows of the result_id query
into a HTML table.
Parametry
-
result_id -
result_idis a valid resultid returned by ifx_query() or ifx_prepare() (select type queries only!). -
html_table_options -
This optional argument is a string of <table> tag options.
Zwracane wartości
Returns the number of fetched rows, or FALSE on errors.
Przykłady
Przykład #1 Informix results as HTML table
<?php
$rid = ifx_prepare ("select * from emp where name like " . $name,
$connid, IFX_SCROLL);
if (! $rid) {
/* ... error ... */
}
$rowcount = ifx_affected_rows ($rid);
if ($rowcount > 1000) {
printf ("Too many rows in result set (%d)\n<br />", $rowcount);
die ("Please restrict your query<br />\n");
}
if (! ifx_do($rid)) {
/* ... error ... */
}
ifx_htmltbl_result ($rid, "border=\"2\"");
ifx_free_result($rid);
?>
ifx_nullformat
(PHP 4, PHP <=5.2.0)
ifx_nullformat — Sets the default return value on a fetch row
Opis
$mode
)Sets the default return value of a NULL-value on a fetch row.
Parametry
-
mode -
Mode "0" returns "", and mode "1" returns "
NULL".
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
ifx_num_fields
(PHP 4, PHP <=5.2.0)
ifx_num_fields — Returns the number of columns in the query
Opis
$result_id
)After preparing or executing a query, this call gives you the number of columns in the query.
Parametry
-
result_id -
result_idis a valid resultid returned by ifx_query() or ifx_prepare() (select type queries only!).
Zwracane wartości
Returns the number of columns in query for
result_id, or FALSE on errors.
Przykłady
Przykład #1 ifx_num_fields() Example
<?php
$conn_id = ifx_connect("db", "user", "password");
$res_id = ifx_query("select * from systables", $conn_id);
echo ifx_num_fields($res_id);
?>
ifx_num_rows
(PHP 4, PHP <=5.2.0)
ifx_num_rows — Count the rows already fetched from a query
Opis
$result_id
)
Gives the number of rows fetched so far for a query with
result_id after a
ifx_query() or ifx_do()
query.
Parametry
-
result_id -
result_idis a valid resultid returned by ifx_query() or ifx_prepare() (select type queries only!).
Zwracane wartości
Returns the number of fetched rows or FALSE on errors.
ifx_pconnect
(PHP 4, PHP <=5.2.0)
ifx_pconnect — Open persistent Informix connection
Opis
$database
[, string $userid
[, string $password
]]] )ifx_pconnect() acts very much like ifx_connect() with two major differences.
First, when connecting, the function would first try to find a (persistent) link that's already open with the same host, username and password. If one is found, an identifier for it will be returned instead of opening a new connection.
Second, the connection to the SQL server will not be closed when the execution of the script ends. Instead, the link will remain open for future use (ifx_close() will not close links established by ifx_pconnect()).
This type of links is therefore called 'persistent'.
Parametry
All of the arguments are optional, and if they're missing, defaults are taken from values supplied in php.ini (ifx.default_host for the host (Informix libraries will use INFORMIXSERVER environment value if not defined), ifx.default_user for user, ifx.default_password for the password (none if not defined).
-
database -
The database name, as a string.
-
userid -
The username, as a string.
-
password -
The password, as a string.
Zwracane wartości
Returns: valid Informix persistent link identifier on success, or FALSE
on errors.
ifx_prepare
(PHP 4, PHP <=5.2.0)
ifx_prepare — Prepare an SQL-statement for execution
Opis
$query
, resource $link_identifier
[, int $cursor_def
], mixed $blobidarray
)
Prepares a query for later use with
ifx_do().
For "select-type" queries a cursor is declared and opened. Non-select queries are "execute immediate".
For either query type the number of (estimated or real) affected rows is saved for retrieval by ifx_affected_rows().
If the contents of the TEXT (or BYTE) column allow it, you can also use ifx_textasvarchar(1) and ifx_byteasvarchar(1). This allows you to treat TEXT (or BYTE) columns just as if they were ordinary (but long) VARCHAR columns for select queries, and you don't need to bother with blob id's.
With ifx_textasvarchar(0) or ifx_byteasvarchar(0) (the default situation), select queries will return BLOB columns as blob id's (integer value). You can get the value of the blob as a string or file with the blob functions (see below).
Parametry
-
query -
The query string.
-
link_identifier -
The link identifier.
-
cursor_def -
This optional parameter allows you to make this a scroll and/or hold cursor. It's a bitmask and can be either
IFX_SCROLL,IFX_HOLD, or both or'ed together. -
blobidarray -
If you have BLOB (BYTE or TEXT) columns in the query, you can add a
blobidarrayparameter containing the corresponding "blob ids", and you should replace those columns with a "?" in the query text.
Zwracane wartości
Returns a valid result identifier for use by ifx_do(),
or FALSE on errors.
ifx_query
(PHP 4, PHP <=5.2.0)
ifx_query — Send Informix query
Opis
$query
, resource $link_identifier
[, int $cursor_type
[, mixed $blobidarray
]] )
Sends a query to the currently active database on
the server that's associated with the specified link identifier.
For "select-type" queries a cursor is declared and opened. Non-select queries are "execute immediate".
For either query type the number of (estimated or real) affected rows is saved for retrieval by ifx_affected_rows().
If the contents of the TEXT (or BYTE) column allow it, you can also use ifx_textasvarchar(1) and ifx_byteasvarchar(1). This allows you to treat TEXT (or BYTE) columns just as if they were ordinary (but long) VARCHAR columns for select queries, and you don't need to bother with blob id's.
With ifx_textasvarchar(0) or ifx_byteasvarchar(0) (the default situation), select queries will return BLOB columns as blob id's (integer value). You can get the value of the blob as a string or file with the blob functions (see below).
Parametry
-
query -
The query string.
-
link_identifier -
The link identifier.
-
cursor_def -
This optional parameter allows you to make this a scroll and/or hold cursor. It's a bitmask and can be either
IFX_SCROLL,IFX_HOLD, or both or'ed together. I you omit this parameter the cursor is a normal sequential cursor. -
blobidarray -
If you have BLOB (BYTE or TEXT) columns in the query, you can add a
blobidarrayparameter containing the corresponding "blob ids", and you should replace those columns with a "?" in the query text.
Zwracane wartości
Returns valid Informix result identifier on success, or FALSE on errors.
Przykłady
Przykład #1 Show all rows of the "orders" table as a HTML table
<?php
ifx_textasvarchar(1); // use "text mode" for blobs
$res_id = ifx_query("select * from orders", $conn_id);
if (! $res_id) {
printf("Can't select orders : %s\n<br />%s<br />\n", ifx_error(), ifx_errormsg());
die;
}
ifx_htmltbl_result($res_id, "border=\"1\"");
ifx_free_result($res_id);
?>
Przykład #2 Insert some values into the "catalog" table
<?php
// create blob id's for a byte and text column
$textid = ifx_create_blob(0, 0, "Text column in memory");
$byteid = ifx_create_blob(1, 0, "Byte column in memory");
// store blob id's in a blobid array
$blobidarray[] = $textid;
$blobidarray[] = $byteid;
// launch query
$query = "insert into catalog (stock_num, manu_code, " .
"cat_descr,cat_picture) values(1,'HRO',?,?)";
$res_id = ifx_query($query, $conn_id, $blobidarray);
if (! $res_id) {
/* ... error ... */
}
// free result id
ifx_free_result($res_id);
?>
ifx_textasvarchar
(PHP 4, PHP <=5.2.0)
ifx_textasvarchar — Set the default text mode
Opis
$mode
)Sets the default text mode for all select-queries.
Parametry
-
mode -
Mode "0" will return a blob id, and mode "1" will return a varchar with text content.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
ifx_update_blob
(PHP 4, PHP <=5.2.0)
ifx_update_blob — Updates the content of the blob object
Opis
$bid
, string $content
)
Updates the content of the blob object for the given blob object
bid.
Parametry
-
bid -
A BLOB object identifier.
-
content -
The new data, as a string.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
ifx_update_char
(PHP 4, PHP <=5.2.0)
ifx_update_char — Updates the content of the char object
Opis
$bid
, string $content
)
Updates the content of the char object for the given char object
bid.
Parametry
-
bid -
A char object identifier.
-
content -
The new data, as a string.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
ifxus_close_slob
(PHP 4, PHP <=5.2.0)
ifxus_close_slob — Deletes the slob object
Opis
$bid
)
Deletes the slob object on the given slob object-id
bid.
Parametry
-
bid -
An existing slob id.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
ifxus_create_slob
(PHP 4, PHP <=5.2.0)
ifxus_create_slob — Creates an slob object and opens it
Opis
$mode
)Creates an slob object and opens it.
Parametry
-
mode -
A combination of
IFX_LO_RDONLY,IFX_LO_WRONLY,IFX_LO_APPENDIFX_LO_RDWR,IFX_LO_BUFFER,IFX_LO_NOBUFFER.
Zwracane wartości
Return the new slob object-id, or FALSE on errors.
Zobacz też:
- ifxus_close_slob() - Deletes the slob object
- ifxus_free_slob() - Deletes the slob object
ifxus_free_slob
(PHP 4, PHP <=5.2.0)
ifxus_free_slob — Deletes the slob object
Opis
$bid
)Deletes the slob object.
Parametry
-
bid -
An existing slob id.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
ifxus_open_slob
(PHP 4, PHP <=5.2.0)
ifxus_open_slob — Opens an slob object
Opis
$bid
, int $mode
)
Opens an slob object. bid should be an
existing slob id.
Parametry
-
bid -
An existing slob id.
-
mode -
A combination of
IFX_LO_RDONLY,IFX_LO_WRONLY,IFX_LO_APPENDIFX_LO_RDWR,IFX_LO_BUFFER,IFX_LO_NOBUFFER.
Zwracane wartości
Returns the new slob object-id, or FALSE on errors.
Zobacz też:
- ifxus_close_slob() - Deletes the slob object
- ifxus_free_slob() - Deletes the slob object
ifxus_read_slob
(PHP 4, PHP <=5.2.0)
ifxus_read_slob — Reads nbytes of the slob object
Opis
$bid
, int $nbytes
)
Reads nbytes of the slob object.
Parametry
-
bid -
An existing slob id.
-
nbytes -
The number of bytes to read.
Zwracane wartości
Returns the slob contents as a string, or FALSE on errors.
ifxus_seek_slob
(PHP 4, PHP <=5.2.0)
ifxus_seek_slob — Sets the current file or seek position
Opis
$bid
, int $mode
, int $offset
)Sets the current file or seek position of an open slob object.
Parametry
-
bid -
An existing slob id.
-
mode -
0 = LO_SEEK_SET, 1 = LO_SEEK_CUR, 2 = LO_SEEK_END.
-
offset -
A byte offset.
Zwracane wartości
Returns the seek position as an integer, or FALSE on errors.
ifxus_tell_slob
(PHP 4, PHP <=5.2.0)
ifxus_tell_slob — Returns the current file or seek position
Opis
$bid
)Returns the current file or seek position of an open slob object
Parametry
-
bid -
An existing slob id.
Zwracane wartości
Returns the seek position as an integer, or FALSE on errors.
ifxus_write_slob
(PHP 4, PHP <=5.2.0)
ifxus_write_slob — Writes a string into the slob object
Opis
$bid
, string $content
)Writes a string into the slob object.
Parametry
-
bid -
An existing slob id.
-
content -
The content to write, as a string.
Zwracane wartości
Returns the bytes written as an integer, or FALSE on errors.
Spis treści
- ifx_affected_rows — Get number of rows affected by a query
- ifx_blobinfile_mode — Set the default blob mode for all select queries
- ifx_byteasvarchar — Set the default byte mode
- ifx_close — Close Informix connection
- ifx_connect — Open Informix server connection
- ifx_copy_blob — Duplicates the given blob object
- ifx_create_blob — Creates an blob object
- ifx_create_char — Creates an char object
- ifx_do — Execute a previously prepared SQL-statement
- ifx_error — Returns error code of last Informix call
- ifx_errormsg — Returns error message of last Informix call
- ifx_fetch_row — Get row as an associative array
- ifx_fieldproperties — List of SQL fieldproperties
- ifx_fieldtypes — List of Informix SQL fields
- ifx_free_blob — Deletes the blob object
- ifx_free_char — Deletes the char object
- ifx_free_result — Releases resources for the query
- ifx_get_blob — Return the content of a blob object
- ifx_get_char — Return the content of the char object
- ifx_getsqlca — Get the contents of sqlca.sqlerrd[0..5] after a query
- ifx_htmltbl_result — Formats all rows of a query into a HTML table
- ifx_nullformat — Sets the default return value on a fetch row
- ifx_num_fields — Returns the number of columns in the query
- ifx_num_rows — Count the rows already fetched from a query
- ifx_pconnect — Open persistent Informix connection
- ifx_prepare — Prepare an SQL-statement for execution
- ifx_query — Send Informix query
- ifx_textasvarchar — Set the default text mode
- ifx_update_blob — Updates the content of the blob object
- ifx_update_char — Updates the content of the char object
- ifxus_close_slob — Deletes the slob object
- ifxus_create_slob — Creates an slob object and opens it
- ifxus_free_slob — Deletes the slob object
- ifxus_open_slob — Opens an slob object
- ifxus_read_slob — Reads nbytes of the slob object
- ifxus_seek_slob — Sets the current file or seek position
- ifxus_tell_slob — Returns the current file or seek position
- ifxus_write_slob — Writes a string into the slob object
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Informix Funkcje
- ifx_affected_rows — Get number of rows affected by a query
- ifx_blobinfile_mode — Set the default blob mode for all select queries
- ifx_byteasvarchar — Set the default byte mode
- ifx_close — Close Informix connection
- ifx_connect — Open Informix server connection
- ifx_copy_blob — Duplicates the given blob object
- ifx_create_blob — Creates an blob object
- ifx_create_char — Creates an char object
- ifx_do — Execute a previously prepared SQL-statement
- ifx_error — Returns error code of last Informix call
- ifx_errormsg — Returns error message of last Informix call
- ifx_fetch_row — Get row as an associative array
- ifx_fieldproperties — List of SQL fieldproperties
- ifx_fieldtypes — List of Informix SQL fields
- ifx_free_blob — Deletes the blob object
- ifx_free_char — Deletes the char object
- ifx_free_result — Releases resources for the query
- ifx_get_blob — Return the content of a blob object
- ifx_get_char — Return the content of the char object
- ifx_getsqlca — Get the contents of sqlca.sqlerrd[0..5] after a query
- ifx_htmltbl_result — Formats all rows of a query into a HTML table
- ifx_nullformat — Sets the default return value on a fetch row
- ifx_num_fields — Returns the number of columns in the query
- ifx_num_rows — Count the rows already fetched from a query
- ifx_pconnect — Open persistent Informix connection
- ifx_prepare — Prepare an SQL-statement for execution
- ifx_query — Send Informix query
- ifx_textasvarchar — Set the default text mode
- ifx_update_blob — Updates the content of the blob object
- ifx_update_char — Updates the content of the char object
- ifxus_close_slob — Deletes the slob object
- ifxus_create_slob — Creates an slob object and opens it
- ifxus_free_slob — Deletes the slob object
- ifxus_open_slob — Opens an slob object
- ifxus_read_slob — Reads nbytes of the slob object
- ifxus_seek_slob — Sets the current file or seek position
- ifxus_tell_slob — Returns the current file or seek position
- ifxus_write_slob — Writes a string into the slob object
Ingres DBMS, EDBC, i Enterprise Access Gateways
Wstęp
Rozszerzenie Ingres w PHP umożliwia połšczenie i wykonywanie zapytań w bazach danych Ingres DBMS, EDBC, i Enterprise Access Gateways.
Informacja:
To rozszerzenie zostało przeniesione do repozytorium » PECL i nie jest rozprowadzane z PHP od wersji 5.1.0.
Instalacja/Konfiguracja
Spis treści
Wymagania
Aby zbudować lub używać rozszerzenia PHP z bazą danych Ingres należy mieć przygotowane działające środowisko Ingres. Oprogramowanie klienta Ingres można pobrać z adresu: » http://esd.ingres.com/.
Instalacja
To rozszerzenie » PECL nie jest dołączane do PHP. Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/ingres.
Biblioteki DLL tego rozszerzenia PECL można pobrać z » http://esd.ingres.com/product/drivers/PHP/.
Aby te funkcje były dostępne należy » pobrać i skompilować to rozszerzenie używając opcji konfiguracji Ingres --with-ingres[=DIR] , gdzie DIR jest katalogiem instalacji Ingres. Jeśli zmienna środowiskowa II_SYSTEM nie jest poprawnie ustawiona, należy użyć opcji --with-ingres=DIR aby określić katalog docelowy instalacji Ingres.
Kod PHP napisany dla wersji 2.x i późniejszych nie jest kompatybilny z poprzednimi wersjami rozszerzenia PHP. Jednakże jest możliwe uruchomienie dwóch niekompatybilnych wydań w tym samym środowisku PHP poprzez ustawienie opcji --enable-ingres2 . Ta opcja konfiguracyjna zmienia nazwę rozszerzenia na ingres2, tym samym zmienia nazwy funkcji, ustawienia konfiguracji i stałe. Gdy ta opcja jest włączona, to na przykład funkcja ingres_connect() staje się: ingres2_connect().
Aby używać tego rozszerzenia, musi być określona systemowa zmienna środowiskowa II_SYSTEM. Użytkownicy systemów Linux i UNIX muszą zdefiniować np. ścieżkę do bibliotek współdzielonych LD_LIBRARY_PATH. Gdy rozszerzenie jest używane z serwerem Apache, to zmienne muszą być wyraźnie określone w pliku konfiguracyjnym serwera Apache. Dodatkowo dyrektywa PassEnv jest wymagana dla rozszerzenia Ingres, aby zostały prawidłowo załadowane biblioteki współdzielone. Na przykład:
Przykład #1 Przykład użycia PassEnv dla Ingres
<IfModule mod_env.c>
PassEnv II_SYSTEM
PassEnv LD_LIBRARY_PATH
</IfModule>
Informacja:
Przykłady konfiguracji Ingres dla różnych serwerów WWW i systemów operacyjnych znajdują się pod adresem: » http://community.ingres.com/wiki/Ingres_Articles#Ingres_and_Web_Servers.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| ingres.allow_persistent | "1" | PHP_INI_SYSTEM | Available since ingres 1.0.0 |
| ingres.array_index_start | "1" | PHP_INI_ALL | Available since ingres 1.4.0. |
| ingres.auto | "1" | PHP_INI_ALL | Available since ingres 2.0.0. |
| ingres.blob_segment_length | "4096" | PHP_INI_ALL | Available since ingres 1.2.0. |
| ingres.cursor_mode | "0" | PHP_INI_ALL | Available since ingres 1.1.0. |
| ingres.default_database | NULL | PHP_INI_ALL | Available since ingres 1.0.0 |
| ingres.default_password | NULL | PHP_INI_ALL | Available since ingres 1.0.0 |
| ingres.default_user | NULL | PHP_INI_ALL | Available since ingres 1.0.0 |
| ingres.describe | 1 | PHP_INI_ALL | Available since ingres 2.1.0 |
| ingres.fetch_buffer_size | 100 | PHP_INI_ALL | Available since ingres 2.1.0 |
| ingres.max_links | "-1" | PHP_INI_SYSTEM | Available since ingres 1.0.0 |
| ingres.max_persistent | "-1" | PHP_INI_SYSTEM | Available since ingres 1.0.0 |
| ingres.reuse_connection | "1" | PHP_INI_ALL | Available since ingres 2.0.0 |
| ingres.scrollable | "1" | PHP_INI_ALL | Available since ingres 2.0.0. |
| ingres.trace | "0" | PHP_INI_ALL | Available since ingres 2.0.0. |
| ingres.trace_connect | "0" | PHP_INI_ALL | Available since ingres 1.2.1. |
| ingres.utf8 | "1" | PHP_INI_ALL | Available since ingres 2.0.0. |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
ingres.allow_persistentboolean -
Specifies whether to allow persistent connections to Ingres
-
ingres.array_index_startinteger -
Specifies the start value for an integer key for arrays generated by ingres_fetch_row() or ingres_fetch_array(). By default
ingres.array_index_startis set to 1. If you wish to make the ingres extension behave like other database extensions set this configuration option to 0. -
ingres.autoboolean -
Enables or disables autocommit emulation. Ingres cannot have multiple cursors open with autocommit enabled. When enabled, the driver emulates autocommit.
-
ingres.blob_segment_lengthinteger -
Specifies the amount of memory to use when reading BLOB data, in bytes
-
ingres.cursor_modeinteger -
Specifies the default mode for cursors opened with ingres_prepare(). Valid values are
INGRES_CURSOR_UPDATEorINGRES_CURSOR_READONLY. -
ingres.default_databasestring -
Specifies the default database name to use when connecting to the database server if no other name is specified. Does not apply in tryb bezpieczny SQL.
-
ingres.default_passwordstring -
Specifies the default password to use when connecting to the database server if no other name is specified. Does not apply in tryb bezpieczny SQL.
-
ingres.default_userstring -
Specifies the default user name to use when connecting to the database server if no other name is specified. Does not apply in tryb bezpieczny SQL.
-
ingres.describeboolean -
Enables the use of DESCRIBE INPUT to determine the expected data types for queries that use parameters. Available with Ingres 9.1.0 and later. When disabled, queries that have parameters passed may need to manually describe the types of those parameters using the types parameter in ingres_query().
Informacja:
Enabling this feature with ingres_query() will cause additional communications traffic between this extension and the server. To minimize this additional traffic, use ingres_prepare() and ingres_execute().
-
ingres.fetch_buffer_sizeinteger -
Specifies the number of pre-fetch rows that ingres_fetch_array(), ingres_fetch_object() and ingres_fetch_row() will try and fetch in one fetch operation.
-
ingres.max_linksinteger -
Specifies the maximum number of Ingres sessions allowed per process or thread. The number of sessions should not exceed the total number of connected sessions configured within Ingres.
-
ingres.max_persistentinteger -
Specifies the maximum number of persistent Ingres sessions allowed per process or thread. The number of sessions should not exceed the total number of connected sessions configured within Ingres.
-
ingres.reuse_connectionboolean -
Reuses an existing active connection if connecting to the same database with the same user name
-
ingres.scrollableboolean -
Enables support for scrollable cursors. When fetching CLOB or BLOB data, this should be set to
FALSE. Available with Ingres 9.2.0 or later. -
ingres.traceboolean -
Enables simple tracing using
E_NOTICEmessages -
ingres.trace_connectboolean -
Prints
E_NOTICEmessages during ingres_connect() or ingres_pconnect() calls -
ingres.utf8boolean -
Assumes that strings being passed to National Character column types (NVARCHAR or NCHAR) are using UTF8 encoding and converts them to UTF16 for the server
Typy zasobów
ingres_connect() i ingres_pconnect() zwracają identyfikator połączenia Ingres.
ingres_query() i ingres_unbuffered_query() zwracają identyfikator wyniku Ingres.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
-
INGRES_ASSOC(integer) - Kolumny są zwracane do tablicy indeksowanej asocjacyjnie. Indeksy tablicy odpowiadają nazwom pól kolumn. Używane w: ingres_fetch_array().
-
INGRES_NUM(integer) - Kolumny są zwracane do tablicy indeksowanej numerycznie. Wartości pól są umieszczane na kolejnych pozycjach tablicy, zaczynając od 1. Aby zmienić tę wartość zobacz ingres.array_index_start. Używane w: ingres_fetch_array().
-
INGRES_BOTH(integer) - Kolumny są zwracane do tablicy indeksowanej zarówno asocjacyjnie, jak również numerycznie. Używane w: ingres_fetch_array().
-
INGRES_EXT_VERSION(string) - Określa wersję rozszerzenia Ingres. Dostępna od wersji 1.2.0 rozszerzenia PECL.
-
INGRES_API_VERSION(integer) - Określa wersję Ingres OpenAPI, z którą rozszerzenie zostało zbudowane. Dostępna od wersji 1.2.0 rozszerzenia PECL.
-
INGRES_CURSOR_READONLY(integer) - Określa, że kursory powinny być otwarte w trybie 'do odczytu'. Dostępna od wersji 1.2.0 rozszerzenia PECL. Używane w: ingres.cursor_mode.
-
INGRES_CURSOR_UPDATE(integer) - Określa, że kursory powinny być otwarte w trybie 'do modyfikacji'. Dostępna od wersji 1.2.0 rozszerzenia PECL. Używane w: ingres.cursor_mode.
-
INGRES_DATE_MULTINATIONAL(integer) - Równoważna z ustawieniem zmiennej środowiskowej II_DATE_FORMAT na MULTINATIONAL. Dostępna od wersji 1.2.0 rozszerzenia PECL. Używane w: ingres_connect(), ingres_pconnect() i ingres_set_environment(). Zobacz opcje środowiskowe w ingres_set_environment().
-
INGRES_DATE_MULTINATIONAL4(integer) - Równoważna z ustawieniem zmiennej środowiskowej II_DATE_FORMAT na MULTINATIONAL4. Dostępna od wersji 1.2.0 rozszerzenia PECL. Używane w: ingres_connect(), ingres_pconnect() i ingres_set_environment(). Zobacz opcje środowiskowe w ingres_set_environment().
-
INGRES_DATE_FINNISH(integer) - Równoważna z ustawieniem zmiennej środowiskowej II_DATE_FORMAT na FINNISH. Dostępna od wersji 1.2.0 rozszerzenia PECL. Używane w: ingres_connect(), ingres_pconnect() i ingres_set_environment(). Zobacz opcje środowiskowe w ingres_set_environment().
-
INGRES_DATE_ISO(integer) - Równoważna z ustawieniem zmiennej środowiskowej II_DATE_FORMAT na ISO. Dostępna od wersji 1.2.0 rozszerzenia PECL. Używane w: ingres_connect(), ingres_pconnect() i ingres_set_environment(). Zobacz opcje środowiskowe w ingres_set_environment().
-
INGRES_DATE_ISO4(integer) - Równoważna z ustawieniem zmiennej środowiskowej II_DATE_FORMAT na ISO4. Dostępna od wersji 1.2.0 rozszerzenia PECL. Używane w: ingres_connect(), ingres_pconnect() i ingres_set_environment(). Zobacz opcje środowiskowe w ingres_set_environment().
-
INGRES_DATE_GERMAN(integer) - Równoważna z ustawieniem zmiennej środowiskowej II_DATE_FORMAT na GERMAN. Dostępna od wersji 1.2.0 rozszerzenia PECL. Używane w: ingres_connect(), ingres_pconnect() i ingres_set_environment(). Zobacz opcje środowiskowe w ingres_set_environment().
-
INGRES_DATE_MDY(integer) - Równoważna z ustawieniem zmiennej środowiskowej II_DATE_FORMAT na MDY. Dostępna od wersji 1.2.0 rozszerzenia PECL. Używane w: ingres_connect(), ingres_pconnect() i ingres_set_environment(). Zobacz opcje środowiskowe w ingres_set_environment().
-
INGRES_DATE_DMY(integer) - Równoważna z ustawieniem zmiennej środowiskowej II_DATE_FORMAT na DMY. Dostępna od wersji 1.2.0 rozszerzenia PECL. Używane w: ingres_connect(), ingres_pconnect() i ingres_set_environment(). Zobacz opcje środowiskowe w ingres_set_environment().
-
INGRES_DATE_YMD(integer) - Równoważna z ustawieniem zmiennej środowiskowej II_DATE_FORMAT na YMD. Dostępna od wersji 1.2.0 rozszerzenia PECL. Używane w: ingres_connect(), ingres_pconnect() i ingres_set_environment(). Zobacz opcje środowiskowe w ingres_set_environment().
-
INGRES_MONEY_LEADING(integer) - Określa symbol waluty umieszczany przed wartością typu money. Równoważna z ustawieniem zmiennej środowiskowej II_MONEY_FORMAT na 'L:'. Dostępna od wersji 1.2.0 rozszerzenia PECL. Używane w: ingres_connect(), ingres_pconnect() i ingres_set_environment(). Zobacz opcje środowiskowe w ingres_set_environment().
-
INGRES_MONEY_TRAILING(integer) - Określa symbol pieniądza umieszczany na końcu wartości typu money. Równoważna z ustawieniem zmiennej środowiskowej II_MONEY_FORMAT na 'T:'. Dostępna od wersji 1.2.0 rozszerzenia PECL. Używane w: ingres_connect(), ingres_pconnect() i ingres_set_environment(). Zobacz opcje środowiskowe w ingres_set_environment().
-
INGRES_STRUCTURE_BTREE(integer) - Określa domyślną strukturę tabeli lub indeksu jako BTREE i może być podawana podczas nawiązywania połączenia jako wartość opcji table_structure lub index_structure. Dostępna od wersji 1.4.0 rozszerzenia PECL. Używane w: ingres_connect() i ingres_pconnect(). Zobacz opcje w ingres_connect().
-
INGRES_STRUCTURE_CBTREE(integer) - Określa domyślną strukturę tabeli lub indeksu jako COMPRESSED BTREE i może być podawana podczas nawiązywania połączenia jako wartość opcji table_structure lub index_structure. Dostępna od wersji 1.4.0 rozszerzenia PECL. Używane w: ingres_connect() i ingres_pconnect(). Zobacz opcje w ingres_connect().
-
INGRES_STRUCTURE_HASH(integer) - Określa domyślną strukturę tabeli lub indeksu jako HASH i może być podawana podczas nawiązywania połączenia jako wartość opcji table_structure lub index_structure. Dostępna od wersji 1.4.0 rozszerzenia PECL. Używane w: ingres_connect() i ingres_pconnect(). Zobacz opcje w ingres_connect().
-
INGRES_STRUCTURE_CHASH(integer) - Określa domyślną strukturę tabeli lub indeksu jako COMPRESSED HASH i może być podawana podczas nawiązywania połączenia jako wartość opcji table_structure lub index_structure. Dostępna od wersji 1.4.0 rozszerzenia PECL. Używane w: ingres_connect() i ingres_pconnect(). Zobacz opcje w ingres_connect().
-
INGRES_STRUCTURE_HEAP(integer) - Określa domyślną strukturę tabeli jako HEAP i może być podawana podczas nawiązywania połączenia jako wartość opcji table_structure. Dostępna od wersji 1.4.0 rozszerzenia PECL. Używane w: ingres_connect() i ingres_pconnect(). Zobacz opcje w ingres_connect().
-
INGRES_STRUCTURE_CHEAP(integer) - Określa domyślną strukturę tabeli jako COMPRESSED HEAP i może być podawana podczas nawiązywania połączenia jako wartość opcji table_structure. Dostępna od wersji 1.4.0 rozszerzenia PECL. Używane w: ingres_connect() i ingres_pconnect(). Zobacz opcje w ingres_connect().
-
INGRES_STRUCTURE_ISAM(integer) - Określa domyślną strukturę tabeli lub indeksu jako ISAM i może być podawana podczas nawiązywania połączenia jako wartość opcji table_structure lub index_structure. Dostępna od wersji 1.4.0 rozszerzenia PECL. Używane w: ingres_connect() i ingres_pconnect(). Zobacz opcje w ingres_connect().
-
INGRES_STRUCTURE_CISAM(integer) - Określa domyślną strukturę tabeli lub indeksu jako COMPRESSED ISAM i może być podawana podczas nawiązywania połączenia jako wartość opcji table_structure lub index_structure. Dostępna od wersji 1.4.0 rozszerzenia PECL. Używane w: ingres_connect() i ingres_pconnect(). Zobacz opcje w ingres_connect().
Przykłady
Spis treści
Podstawowe użycie
Ten nieskomplikowany przykład pojazuje jak połączyć się z bazą Ingres, wykonać zapytanie, wyświetlić wyniki i zamknąć połączenie.
Przykład #1 Przykład połączenia z Ingres
<?php
// Nawiązanie połączenia, wybór bazy danych
$link = ingres_connect('database', 'user', 'password')
or die('Nie można się połączyć: ' . ingres_error($link));
echo 'Połączenie zostało nawiązane pomyślnie';
// Pobieranie wyników z tabeli, która istnieje we wszystkich bazach danych Ingres
$query = 'SELECT * FROM iirelation';
$returncode = ingres_query($link,$query) or die('Zapytanie nie powiodło się: ' .
ingres_error($link));
// Wyświetla wyniki w formacie HTML
// relid - nazwa tabeli
// relowner - właściciel tabeli
echo "<table>\n";
while ($iirelation = ingres_fetch_object($link)) {
echo "\t<tr>\n";
echo "\t\t<td>" . $iirelation->relid . "</td>\n";
echo "\t\t<td>" . $iirelation->relowner . "</td>\n";
echo "\t</tr>\n";
}
echo "</table>\n";
// Zwolnienie bufora wyniku
ingres_free_result($result);
// Potwierdzenie transakcji
ingres_commit($link);
// Zamknięcie połączenia
ingres_close($link);
?>
Funkcje Ingres
ingres_autocommit_state
(PECL ingres >= 2.0.0)
ingres_autocommit_state — Test if the connection is using autocommit
Opis
$link
)ingres_autocommit_state() is called to determine whether the current link has autocommit enabled or not.
Parametry
-
link -
The connection link identifier
Zwracane wartości
Returns TRUE if autocommit is enabled or FALSE when autocommit is
disabled
Zobacz też:
- ingres_autocommit() - Włącza lub wyłącza automatyczne zatwierdzanie
- ingres_query() - Send an SQL query to Ingres
ingres_autocommit
(PHP 4 >= 4.0.2, PHP 5 <= 5.0.5, PECL ingres >= 1.0.0)
ingres_autocommit — Włącza lub wyłącza automatyczne zatwierdzanie
Opis
$identyfikator_połączenia
)ingres_autocommit() jest wywoływana przed otwarciem transakcji (przed pierwszym wywołaniem ingres_query() lub po wywołaniu ingres_rollback() albo ingres_commit()) aby włączyć lub wyłączyć tryb "automatycznego zatwierdzania" na serwerze (gdy skrypt PHP jest uruchamiany, automatyczne zatwierdzanie jest wyłączone).
Gdy automatyczne zatwierdzanie jest włączone, każde zapytanie jest automatycznie zatwierdzane przez serwer, tak jakby była wywoływana ingres_commit() po każdej funkcji ingres_query(). Aby sprawdzić czy automatyczne zatwierdzanie jest włączone należy użyć funkcji ingres_autocommit_state().
Domyślnie Ingres wycofuje każde niezatwierdzone transakcje na koniec zapytania. Należy korzystać z funkcji ingres_commit(), aby zapewnić potwierdzenie zapisu danych w bazie danych Ingres.
Parametry
-
identyfikator_połączenia -
Identyfikator połączenia
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- ingres_autocommit_state() - Test if the connection is using autocommit
- ingres_query() - Send an SQL query to Ingres
- ingres_rollback() - Wycofuje transakcję
- ingres_commit() - Zatwierdza transakcję
ingres_charset
(PECL ingres >= 2.1.0)
ingres_charset — Returns the installation character set
Opis
$link
)ingres_charset() is called to determine the character set being used by the Ingres client, from II_CHARSETxx (where xx is the installation code).
Informacja:
You can override the value returned by using the function putenv(). Changing the value of II_CHARSETxx in a running Ingres installation can cause data corruption.
Parametry
-
link -
The connection link identifier
Zwracane wartości
Returns a string with the value for II_CHARSETxx or returns NULL if the value could not be determined.
Przykłady
Przykład #1 ingres_charset() - Get the installation character set
<?php
$link = ingres_connect($database, $user, $password);
echo ingres_charset($link) . "\n";
ingres_close($link);
?>
Zobacz też:
- ingres_connect() - Open a connection to an Ingres database
- ingres_query() - Send an SQL query to Ingres
ingres_close
(PHP 4 >= 4.0.2, PHP 5 <= 5.0.5, PECL ingres >= 1.0.0)
ingres_close — Zamyka połączenie z serwerem Ingres
Opis
$identyfikator_połączenia
)ingres_close() zamyka połączenie do serwera Ingres skojarzone z określonym indentyfikatorem połączenia.
ingres_close() zazwyczaj nie jest potrzebne, jako że połączenia stałe nie są zamykane, a wszystkie połączenia niestałe są automatycznie zamykane po zakończeniu wykonywania skryptu.
Parametry
-
identyfikator_połączenia -
Identyfikator połączenia
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- ingres_connect() - Open a connection to an Ingres database
- ingres_pconnect() - Open a persistent connection to an Ingres database
ingres_commit
(PHP 4 >= 4.0.2, PHP 5 <= 5.0.5, PECL ingres >= 1.0.0)
ingres_commit — Zatwierdza transakcję
Opis
$identyfikator_połączenia
)ingres_commit() zatwierdza bieżącą otwartą transakcję, utrwalając wszystkie zmiany dokonane w bazie danych.
Bieżąca transakcja jest zamykana. Nowa transakcja może być rozpoczęta poprzez wysłanie zapytania za pomocą ingres_query().
Można ustawić automatyczne zatwierdzanie transakcji przez serwer po każdym wysłanym zapytaniu, przez wywołanie ingres_autocommit() przed otwarciem transakcji.
Domyślnie Ingres wycofuje każde niezatwierdzone transakcje na koniec zapytania. Używaj tej funkcji albo ingres_autocommit(), aby zapewnić potwierdzenie zapisu danych w bazie danych Ingres.
Parametry
-
identyfikator_połączenia -
Identyfikator połączenia
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- ingres_query() - Send an SQL query to Ingres
- ingres_rollback() - Wycofuje transakcję
- ingres_autocommit() - Włącza lub wyłącza automatyczne zatwierdzanie
ingres_connect
(PHP 4 >= 4.0.2, PHP 5 <= 5.0.5, PECL ingres >= 1.0.0)
ingres_connect — Open a connection to an Ingres database
Opis
$database
[, string $username
[, string $password
[, array $options
]]]] )
ingres_connect() opens a connection with the
given Ingres database.
The connection is closed when the script ends or when ingres_close() is called on this link.
Parametry
If some parameters are missing, ingres_connect()
uses the values in php.ini for
ingres.default_database,
ingres.default_user and
ingres.default_password.
-
database -
The database name. Must follow the syntax:
[vnode::]dbname[/svr_class]
-
username -
The Ingres user name
-
password -
The password associated with
username -
options -
ingres_connect() options
Option name Option type Description Example date_century_boundary integer The threshold by which a 2-digit year is determined to be in the current century or in the next century. Equivalent to II_DATE_CENTURY_BOUNDARY. 50 group string Specifies the group ID of the user, equivalent to the "-G" flag payroll role string The role ID of the application. If a role password is required, the parameter value should be specified as "role/password" effective_user string The ingres user account being impersonated, equivalent to the "-u" flag another_user dbms_password string The internal database password for the user connecting to Ingres s3cr3t table_structure string The default structure for new tables. Valid values for table_structure are:
- INGRES_STRUCTURE_BTREE
- INGRES_STRUCTURE_HASH
- INGRES_STRUCTURE_HEAP
- INGRES_STRUCTURE_ISAM
- INGRES_STRUCTURE_CBTREE
- INGRES_STRUCTURE_CISAM
- INGRES_STRUCTURE_CHASH
- INGRES_STRUCTURE_CHEAP
INGRES_STRUCTURE_BTREE index_structure string The default structure for new secondary indexes. Valid values for index_structure are:
- INGRES_STRUCTURE_CBTREE
- INGRES_STRUCTURE_CISAM
- INGRES_STRUCTURE_CHASH
- INGRES_STRUCTURE_BTREE
- INGRES_STRUCTURE_HASH
- INGRES_STRUCTURE_ISAM
INGRES_STRUCTURE_HASH login_local boolean Determines how the connection user ID and password are used when a VNODE is included in the target database string. If set to TRUE, the user ID and password are used to locally access the VNODE, and the VNODE login information is used to establish the DBMS connection. If set to FALSE, the process user ID is used to access the VNODE, and the connection user ID and password are used in place of the VNODE login information to establish the DBMS connection. This parameter is ignored if no VNODE is included in the target database string. The default is FALSE. TRUE timezone string Controls the timezone of the session. If not set it will default to the value defined by II_TIMEZONE_NAME. If II_TIMEZONE_NAME is not defined, NA-PACIFIC (GMT-8 with Daylight Savings) is used. date_format integer Sets the allowable input and output format for Ingres dates. Defaults to the value defined by II_DATE_FORMAT. If II_DATE_FORMAT is not set the default date format is US, e.g. mm/dd/yy. Valid values for date_format are:
- INGRES_DATE_DMY
- INGRES_DATE_FINISH
- INGRES_DATE_GERMAN
- INGRES_DATE_ISO
- INGRES_DATE_ISO4
- INGRES_DATE_MDY
- INGRES_DATE_MULTINATIONAL
- INGRES_DATE_MULTINATIONAL4
- INGRES_DATE_YMD
- INGRES_DATE_US
INGRES_DATE_MULTINATIONAL4 decimal_separator string The character identifier for decimal data "," money_lort integer Leading or trailing currency sign. Valid values for money_lort are:
- INGRES_MONEY_LEADING
- INGRES_MONEY_TRAILING
INGRES_MONEY_TRAILING money_sign string The currency symbol to be used with the MONEY datatype € money_precision integer The precision of the MONEY datatype 3 float4_precision integer Precision of the FLOAT4 datatype 10 float8_precision integer Precision of the FLOAT8 data 10 blob_segment_length integer The amount of data in bytes to fetch at a time when retrieving BLOB or CLOB data, defaults to 4096 bytes when not explicitly set 8192
Zwracane wartości
Returns a Ingres link resource on success lub FALSE w przypadku niepowodzenia
Przykłady
Przykład #1 Open a connection to an Ingres database
<?php
$link = ingres_connect("mydb", "user", "pass")
or die("Could not connect");
echo "Connected successfully";
ingres_close($link);
?>
Zobacz też:
- ingres_pconnect() - Open a persistent connection to an Ingres database
- ingres_close() - Zamyka połączenie z serwerem Ingres
ingres_cursor
(PECL ingres >= 1.1.0)
ingres_cursor — Get a cursor name for a given result resource
Opis
$result
)Returns a string with the active cursor name. If no cursor is active then NULL is returned.
Parametry
-
result -
The query result identifier
Zwracane wartości
Returns a string containing the active cursor name. If no cursor is active then NULL is returned.
Przykłady
Przykład #1 Get cursor name for a query resource
<?php
$link = ingres_connect($database, $user, $password);
$result = ingres_prepare($link, "select * from table");
$cursor_name = ingres_cursor($result);
echo $cursor_name;
?>
Zobacz też:
- ingres_prepare() - Prepare a query for later execution
- ingres_execute() - Execute a prepared query
ingres_errno
(PECL ingres >= 1.1.0)
ingres_errno — Zwraca ostatnio wygenerowany numer błędu Ingres
Opis
$identyfikator_połączenia
] )Zwraca liczbę typu integer zawierającą ostatni numer błędu. Jeśli nie wystąpił żaden błąd, zwracane jest 0.
Jeśli podano identyfikator_połączenia
ingres_errno() zwraca ostatni numer błędu dla
tego połączenia. Jeśli nie podano identyfikatora połączenia ingres_errno()
zwraca numer ostatniego błędu dla domyślnego połączenia.
Ta funkcja, ingres_errno(), powinna być zawsze wywołana po wykonaniu zapytania. Wywołanie innej funkcji przed ingres_errno(), wyzeruje lub zmieni dla niej kod ostatniego błędu Ingres.
Parametry
-
identyfikator_połączenia -
Identyfikator połączenia
Zwracane wartości
Zwraca liczbę typu integer zawierającą ostatni numer błędu. Jeśli nie wystąpił żaden błąd, zwracane jest 0.
Przykłady
Przykład #1 Przykład obsługi ostatnio wygenerowanego kodu błędu Ingres
<?php
$identyfikator_polaczenia = ingres_connect($baza_danych, $uzytkownik, $haslo);
$wynik = ingres_query($identyfikator_polaczenia, "select * from nazwa_tabeli");
$kod_bledu = ingres_errno($identyfikator_polaczenia);
if ( $kod_bledu != 0 ) {
echo "Wystąpił błąd - " . $kod_bledu;
}
?>
Zobacz też:
- ingres_error() - Zwraca znaczący komunikat o ostatnio wygenerowanym błędzie
- ingres_errsqlstate() - Zwraca ostatnio wygenerowany kod błędu SQLSTATE
- ingres_next_error() - Get the next Ingres error
ingres_error
(PECL ingres >= 1.1.0)
ingres_error — Zwraca znaczący komunikat o ostatnio wygenerowanym błędzie
Opis
$identyfikator_połączenia
] )Zwraca łańcuch zawierający informację o ostatnim błędzie, lub NULL jeśli nie wystąpił żaden błąd.
Jeśli podano identyfikator_połączenia jako argument
ingres_error() zwraca informację o błędzie dla tego
połączenia. Jeśli pominięto identyfikator połączenia, ingres_error()
zwraca informację o błędzie dla domyślnego połączenia.
Ta funkcja, ingres_error(), powinna być zawsze wywołana po wykonaniu zapytania. Wywołanie innej funkcji przed ingres_error(), zresetuje lub zmieni dla niej informację o ostatnim błędzie Ingres.
Parametry
-
identyfikator_połączenia -
Identyfikator połączenia
Zwracane wartości
Zwraca łańcuch zawierający informację o ostatnim błędzie, lub NULL jeśli nie wystąpił żaden błąd.
Przykłady
Przykład #1 Przykład obsługi ostatnio wygenerowanego komunikatu o błędzie
<?php
$identyfikator_polaczenia = ingres_connect($baza_danych, $uzytkownik, $haslo);
$wynik = ingres_query("select * from nazwa_tabeli");
$tekst_bledu = ingres_error();
if (!is_null($tekst_bledu)) {
echo "Wystąpił błąd - " . $tekst_bledu;
}
?>
Zobacz też:
- ingres_errno() - Zwraca ostatnio wygenerowany numer błędu Ingres
- ingres_errsqlstate() - Zwraca ostatnio wygenerowany kod błędu SQLSTATE
- ingres_next_error() - Get the next Ingres error
ingres_errsqlstate
(PECL ingres >= 1.1.0)
ingres_errsqlstate — Zwraca ostatnio wygenerowany kod błędu SQLSTATE
Opis
$identyfikator_połączenia
] )Zwraca łańcuch zawierający ostatni kod SQLSTATE, lub NULL jeśli nie wystąpił żaden błąd.
Jeśli podano identyfikator_połączenia
ingres_errsqlstate() zwraca ostatni numer błędu dla
tego połączenia. Jeśli nie podano identyfikatora połączenia
ingres_errsqlstate() zwraca numer ostatniego błędu
dla domyślnego połączenia.
Ta funkcja, ingres_errsqlstate(), powinna być zawsze wywołana po wykonaniu zapytania. Wywołanie innej funkcji przed ingres_errsqlstate(), wyzeruje lub zmieni dla niej kod ostatniego błędu Ingres.
Parametry
-
identyfikator_połączenia -
Identyfikator połączenia
Zwracane wartości
Zwraca łańcuch zawierający ostatni kod SQLSTATE, lub NULL jeśli nie wystąpił żaden błąd.
Przykłady
Przykład #1 Przykład pobrania ostatnio wygenerowanego kodu SQLSTATE
<?php
$identyfikator_polaczenia = ingres_connect($baza_danych, $uzytkownik, $haslo);
$wynik = ingres_query("select * from nazwa_tabeli");
$error_sqlstate = ingres_errsqlstate();
if (!is_null($error_sqlstate)) {
echo "Wystąpił błąd - " . $error_sqlstate;
}
?>
Zobacz też:
- ingres_errno() - Zwraca ostatnio wygenerowany numer błędu Ingres
- ingres_error() - Zwraca znaczący komunikat o ostatnio wygenerowanym błędzie
- ingres_next_error() - Get the next Ingres error
ingres_escape_string
(PECL ingres >= 2.1.0)
ingres_escape_string — Escape special characters for use in a query
Opis
$link
, string $source_string
)ingres_escape_string() is used to escape certain characters within a string before it is sent to the database server.
Parametry
-
link -
The connection link identifier
-
source_string -
The source string to be parsed
Zwracane wartości
Returns a string containing the escaped data.
Przykłady
Przykład #1 Escape special characters for use in a query
<?php
$link = ingres_connect($database, $user, $password);
$last_name = "O'Connor";
$sql = sprintf("select * from user_profile where up_last = '%s'", ingres_escape_string( $link, $last_name));
$result = ingres_query($link, $sql);
while ($user = ingres_fetch_object($result))
{
echo $user->up_first . '<BR/>';
}
ingres_commit($link);
ingres_close($link);
?>
ingres_execute
(PECL ingres >= 1.1.0)
ingres_execute — Execute a prepared query
Opis
$result
[, array $params
[, string $types
]] )Execute a query prepared using ingres_prepare().
Informacja: Related Configurations
See also the ingres.describe, ingres.scrollable and ingres.utf8 directives in Runtime Configuration.
Parametry
-
result -
The result query identifier
-
params -
An array of parameter values to be used with the query
-
types -
A string containing a sequence of types for the parameter values passed. See the types parameter in ingres_query() for the list of type codes.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- ingres_unbuffered_query() - Send an unbuffered SQL query to Ingres
- ingres_fetch_array() - Fetch a row of result into an array
- ingres_fetch_assoc() - Fetch a row of result into an associative array
- ingres_fetch_object() - Fetch a row of result into an object
- ingres_fetch_row() - Fetch a row of result into an enumerated array
- ingres_commit() - Zatwierdza transakcję
- ingres_rollback() - Wycofuje transakcję
- ingres_autocommit() - Włącza lub wyłącza automatyczne zatwierdzanie
- ingres_set_environment() - Set environment features controlling output options
- ingres_errno() - Zwraca ostatnio wygenerowany numer błędu Ingres
- ingres_error() - Zwraca znaczący komunikat o ostatnio wygenerowanym błędzie
ingres_fetch_array
( PHP 5 <= 5.0.5, PECL ingres >= 1.0.0)
ingres_fetch_array — Fetch a row of result into an array
Opis
$result
[, int $result_type
] )This function is an extended version of ingres_fetch_row(). In addition to storing the data in the numeric indices of the result array, it also stores the data in associative indices, using the field names as keys.
If two or more columns of the result have the same field names, the last column will take precedence. To access the another column or columns of the same name, you must use the numeric index of the column or make an alias for the column. For example:
<?php
$result = ingres_query($link, "select ap_place as city, ap_ccode as country from airport where ap_iatacode = 'VLL'");
$result = ingres_fetch_array($result);
$foo = $result["city"];
$bar = $result["country"];
?>
With regard to speed, the function is identical to ingres_fetch_object(), and almost as quick as ingres_fetch_row() (the difference is insignificant).
By default, arrays created by ingres_fetch_array() start from position 1 and not 0 as with other DBMS extensions. The starting position can be adjusted to 0 using the configuration parameter ingres.array_index_start.
Informacja: Related Configurations
See also the ingres.array_index_start, ingres.fetch_buffer_size and ingres.utf8 directives in Runtime Configuration.
Parametry
-
result -
The query result identifier
-
result_type -
The result type. This
result_typecan beINGRES_NUMfor enumerated array,INGRES_ASSOCfor associative array, orINGRES_BOTH(default).
Zwracane wartości
Returns an array that corresponds to the fetched row,
or FALSE if there are no more rows
Przykłady
Przykład #1 Fetch a row of result into an array
<?php
$link = ingres_connect($database, $user, $password);
$result = ingres_query($link,"select * from table");
while ($row = ingres_fetch_array($result)) {
echo $row["user_id"]; // using associative array
echo $row["fullname"];
echo $row[1]; // using enumerated array
echo $row[2];
}
?>
Zobacz też:
- ingres_query() - Send an SQL query to Ingres
- ingres_num_fields() - Pobiera liczbę pól zwracanych przez ostatnie zapytanie
- ingres_field_name() - Zwraca nazwę pola z wyniku zapytania
- ingres_fetch_assoc() - Fetch a row of result into an associative array
- ingres_fetch_object() - Fetch a row of result into an object
- ingres_fetch_row() - Fetch a row of result into an enumerated array
ingres_fetch_assoc
(PECL ingres >= 2.2.2)
ingres_fetch_assoc — Fetch a row of result into an associative array
Opis
$result
)This function is stores the data fetched from a query executed using ingres_query() in an associative array, using the field names as keys.
With regard to speed, the function is identical to ingres_fetch_object(), and almost as quick as ingres_fetch_row() (the difference is insignificant).
By default, arrays created by ingres_fetch_assoc() start from position 1 and not 0 as with other DBMS extensions. The starting position can be adjusted to 0 using the configuration parameter ingres.array_index_start.
Informacja: Related Configurations
See also the ingres.array_index_start, ingres.fetch_buffer_size and ingres.utf8 directives in Runtime Configuration.
Parametry
-
result -
The query result identifier
Zwracane wartości
Returns an associative array that corresponds to the fetched row,
or FALSE if there are no more rows
Przykłady
Przykład #1 Fetch a row into an associative array
<?php
$link = ingres_connect($database, $user, $password);
$result = ingres_query($link,"select * from table");
while ($row = ingres_fetch_assoc($result)) {
echo $row["user_id"]; // using associative array
echo $row["fullname"];
}
?>
Zobacz też:
- ingres_query() - Send an SQL query to Ingres
- ingres_num_fields() - Pobiera liczbę pól zwracanych przez ostatnie zapytanie
- ingres_field_name() - Zwraca nazwę pola z wyniku zapytania
- ingres_fetch_array() - Fetch a row of result into an array
- ingres_fetch_object() - Fetch a row of result into an object
- ingres_fetch_row() - Fetch a row of result into an enumerated array
ingres_fetch_object
(PHP 4 >= 4.0.2, PHP 5 <= 5.0.5, PECL ingres >= 1.0.0)
ingres_fetch_object — Fetch a row of result into an object
Opis
$result
[, int $result_type
] )This function is similar to ingres_fetch_array(), with one difference - an object is returned instead of an array. Indirectly, this means that you can access the data only by the field names and not by their offsets (numbers are illegal property names).
With regard to speed, the function is identical to ingres_fetch_array(), and almost as quick as ingres_fetch_row() (the difference is insignificant).
Informacja: Related Configurations
See also the ingres.fetch_buffer_size and ingres.utf8 directives in Runtime Configuration.
Parametry
-
link -
The query result identifier
-
result_type -
(Optional argument.)
result_typeis a constant and can take the following values:INGRES_ASSOC,INGRES_NUM, andINGRES_BOTH.
Zwracane wartości
Returns an object that corresponds to the fetched row,
or FALSE if there are no more rows
Przykłady
Przykład #1 Fetch a row into an object
<?php
$link = ingres_connect($database, $user, $password);
$result = ingres_query($link, "select * from table");
while ($row = ingres_fetch_object($result)) {
echo $row->user_id;
echo $row->fullname;
}
?>
Zobacz też:
- ingres_query() - Send an SQL query to Ingres
- ingres_num_fields() - Pobiera liczbę pól zwracanych przez ostatnie zapytanie
- ingres_field_name() - Zwraca nazwę pola z wyniku zapytania
- ingres_fetch_array() - Fetch a row of result into an array
- ingres_fetch_assoc() - Fetch a row of result into an associative array
- ingres_fetch_row() - Fetch a row of result into an enumerated array
ingres_fetch_proc_return
(PECL ingres >= 1.4.0)
ingres_fetch_proc_return — Get the return value from a procedure call
Opis
$result
)This function is used to retrieve the return value following the execution of an Ingres database procedure (stored procedure).
Informacja:
If used with a row-producing procedure, this function should be called after all the rows from the procedure have been fetched using ingres_fetch_array(), ingres_fetch_object() or ingres_fetch_row(). This function will eliminate any rows yet to be fetched should there be any left over.
Parametry
-
result -
The result identifier for a query
Zwracane wartości
Returns an integer if there is a return value otherwise it will
return NULL.
Przykłady
Przykład #1 Get the return value from a procedure call
<?php
$link = ingres_connect($database);
if ( ingres_errno() != 0 ) {
$error_text = ingres_error();
die($error_text);
}
$result = ingres_query($link, "execute procedure php_proc (value = 1000)");
if ( ingres_errno() != 0 ) {
$error_text = ingres_error();
die($error_text);
}
echo "return value - " . ingres_fetch_proc_return($result) . "\n";
ingres_close($link);
?>
Zobacz też:
- ingres_query() - Send an SQL query to Ingres
- ingres_fetch_array() - Fetch a row of result into an array
- ingres_fetch_object() - Fetch a row of result into an object
- ingres_fetch_row() - Fetch a row of result into an enumerated array
ingres_fetch_row
(PHP 4 >= 4.0.2, PHP 5 <= 5.0.5, PECL ingres >= 1.0.0)
ingres_fetch_row — Fetch a row of result into an enumerated array
Opis
$result
)
ingres_fetch_row() returns an array that
corresponds to the fetched row, or FALSE if there are no more
rows. Each result column is stored in an array offset, starting
at offset 1.
Subsequent calls to ingres_fetch_row()
return the next row in the result set, or FALSE if there are no
more rows.
By default, arrays created by ingres_fetch_row() start from position 1 and not 0 as with other DBMS extensions. The starting position can be adjusted to 0 using the configuration parameter ingres.array_index_start.
Informacja: Related Configurations
See also the ingres.array_index_start, ingres.fetch_buffer_size and ingres.utf8 directives in Runtime Configuration.
Parametry
-
result -
The query result identifier
Zwracane wartości
Returns an array that corresponds to the fetched row,
or FALSE if there are no more rows
Przykłady
Przykład #1 Fetch a row of result into an enumerated array
<?php
$link = ingres_connect($database, $user, $password);
$result = ingres_query($link, "select * from table");
while ($row = ingres_fetch_row($result)) {
echo $row[1];
echo $row[2];
}
?>
Zobacz też:
- ingres_num_fields() - Pobiera liczbę pól zwracanych przez ostatnie zapytanie
- ingres_query() - Send an SQL query to Ingres
- ingres_fetch_array() - Fetch a row of result into an array
- ingres_fetch_assoc() - Fetch a row of result into an associative array
- ingres_fetch_object() - Fetch a row of result into an object
ingres_field_length
(PHP 4 >= 4.0.2, PHP 5 <= 5.0.5, PECL ingres >= 1.0.0)
ingres_field_length — Get the length of a field
Opis
$result
, int $index
)ingres_field_length() returns the length of a field. This is the number of bytes the server uses to store the field. For detailed information, see the Ingres OpenAPI User Guide, Appendix "Data Types" in the Ingres documentation.
Informacja: Related Configurations
Parametry
-
result -
The query result identifier
-
index -
indexis the column number whose length will be retrieved.The possible values of
indexdepend upon the value of ingres.array_index_start. If ingres.array_index_start is 1 (the default) thenindexmust be between 1 and the value returned by ingres_num_fields(). If ingres.array_index_start is 0 thenindexmust be between 0 and ingres_num_fields() - 1.
Zwracane wartości
Returns the length of a field.
Zobacz też:
- ingres_query() - Send an SQL query to Ingres
- ingres_fetch_array() - Fetch a row of result into an array
- ingres_fetch_assoc() - Fetch a row of result into an associative array
- ingres_fetch_object() - Fetch a row of result into an object
- ingres_fetch_row() - Fetch a row of result into an enumerated array
ingres_field_name
(PHP 4 >= 4.0.2, PHP 5 <= 5.0.5, PECL ingres >= 1.0.0)
ingres_field_name — Zwraca nazwę pola z wyniku zapytania
Opis
$identyfikator_wyniku
, int $indeks
)ingres_field_name() zwraca nazwę danego pola z wyniku zapytania.
Informacja: Konfiguracja powiązana
Zobacz ingres.array_index_start w dziale Konfiguracja wykonawcza
Parametry
-
identyfikator_wyniku -
Identyfikator wyniku
-
indeks -
indeksjest numerem pola, którego zostanie zwrócona jego nazwa.Możliwe wartości
indeksuzależą od wartości ingres.array_index_start. Jeśli ingres.array_index_start wynosi 1 (domyślnie) wówczasindeksmusi być liczbą pomiędzy 1 i wartością zwróconą przez ingres_num_fields(). Jeśli ingres.array_index_start wynosi 0 wówczasindexmusi być liczbą pomiędzy 0 i ingres_num_fields() - 1.
Zwracane wartości
Zwraca nazwę danego pola
z wyniku zapytania lub FALSE w przypadku niepowodzenia
Zobacz też:
- ingres_query() - Send an SQL query to Ingres
- ingres_fetch_array() - Fetch a row of result into an array
- ingres_fetch_assoc() - Fetch a row of result into an associative array
- ingres_fetch_object() - Fetch a row of result into an object
- ingres_fetch_row() - Fetch a row of result into an enumerated array
ingres_field_nullable
(PHP 4 >= 4.0.2, PHP 5 <= 5.0.5, PECL ingres >= 1.0.0)
ingres_field_nullable — Sprawdza czy pole może przyjmować wartość NULL
Opis
$identyfikator_wyniku
, int $indeks
)Sprawdza czy do pola można wprowadzić wartość NULL.
Informacja: Konfiguracja powiązana
Zobacz ingres.array_index_start w dziale Konfiguracja wykonawcza
Parametry
-
identyfikator_wyniku -
Identyfikator połączenia
-
indeks -
indeksjest numerem pola, które zostanie sprawdzone, czy może przyjmować wartość NULL.Możliwe wartości
indeksuzależą od wartości ingres.array_index_start. Jeśli ingres.array_index_start wynosi 1 (domyślnie) wówczasindeksmusi być liczbą pomiędzy 1 i wartością zwróconą przez ingres_num_fields(). Jeśli ingres.array_index_start wynosi 0 wówczasindexmusi być liczbą pomiędzy 0 i ingres_num_fields() - 1.
Zwracane wartości
ingres_field_nullable() zwraca TRUE jeśli
do pola może być wprowadzona wartość NULL, w przeciwnym przypadku zwraca FALSE
Zobacz też:
- ingres_query() - Send an SQL query to Ingres
- ingres_fetch_array() - Fetch a row of result into an array
- ingres_fetch_assoc() - Fetch a row of result into an associative array
- ingres_fetch_object() - Fetch a row of result into an object
- ingres_fetch_row() - Fetch a row of result into an enumerated array
ingres_field_precision
(PHP 4 >= 4.0.2, PHP 5 <= 5.0.5, PECL ingres >= 1.0.0)
ingres_field_precision — Get the precision of a field
Opis
$result
, int $index
)ingres_field_precision() returns the precision of a field. This value is used only for decimal, float, and money SQL data types. For detailed information, see the Ingres OpenAPI User Guide, Appendix "Data Types" in the Ingres documentation.
Informacja: Related Configurations
Parametry
-
result -
The query result identifier
-
index -
indexis the field whose precision will be retrieved.The possible values of
indexdepend upon the value of ingres.array_index_start. If ingres.array_index_start is 1 (the default) thenindexmust be between 1 and the value returned by ingres_num_fields(). If ingres.array_index_start is 0 thenindexmust be between 0 and ingres_num_fields() - 1.
Zwracane wartości
Returns the field precision as an integer
Zobacz też:
- ingres_query() - Send an SQL query to Ingres
- ingres_fetch_array() - Fetch a row of result into an array
- ingres_fetch_assoc() - Fetch a row of result into an associative array
- ingres_fetch_object() - Fetch a row of result into an object
- ingres_fetch_row() - Fetch a row of result into an enumerated array
ingres_field_scale
(PHP 4 >= 4.0.2, PHP 5 <= 5.0.5, PECL ingres >= 1.0.0)
ingres_field_scale — Get the scale of a field
Opis
$result
, int $index
)ingres_field_scale() returns the scale of a field. This value is used only for the decimal SQL data type. For detailed information, see the Ingres OpenAPI User Guide, Appendix "Data Types" in the Ingres documentation.
Informacja: Related Configurations
Parametry
-
result -
The query result identifier
-
index -
indexis the field whose scale will be retrieved.The possible values of
indexdepend upon the value of ingres.array_index_start. If ingres.array_index_start is 1 (the default) thenindexmust be between 1 and the value returned by ingres_num_fields(). If ingres.array_index_start is 0 thenindexmust be between 0 and ingres_num_fields() - 1.
Zwracane wartości
Returns the scale of the field, as an integer
Zobacz też:
- ingres_query() - Send an SQL query to Ingres
- ingres_fetch_array() - Fetch a row of result into an array
- ingres_fetch_assoc() - Fetch a row of result into an associative array
- ingres_fetch_object() - Fetch a row of result into an object
- ingres_fetch_row() - Fetch a row of result into an enumerated array
ingres_field_type
(PHP 4 >= 4.0.2, PHP 5 <= 5.0.5, PECL ingres >= 1.0.0)
ingres_field_type — Get the type of a field in a query result
Opis
$result
, int $index
)Get the type of a field in a query result.
Informacja: Related Configurations
Parametry
-
result -
The query result identifier
-
index -
indexis the field whose type will be retrieved.The possible values of
indexdepend upon the value of ingres.array_index_start. If ingres.array_index_start is 1 (the default) thenindexmust be between 1 and the value returned by ingres_num_fields(). If ingres.array_index_start is 0 thenindexmust be between 0 and ingres_num_fields() - 1.
Zwracane wartości
ingres_field_type() returns the type of a
field in a query result lub FALSE w przypadku niepowodzenia. Examples of
types returned are IIAPI_BYTE_TYPE,
IIAPI_CHA_TYPE, IIAPI_DTE_TYPE,
IIAPI_FLT_TYPE, IIAPI_INT_TYPE,
IIAPI_VCH_TYPE. Some of these types can map to more
than one SQL type depending on the length of the field (see
ingres_field_length()). For example
IIAPI_FLT_TYPE can be a float4 or a float8. For detailed
information, see the Ingres OpenAPI User Guide, Appendix
"Data Types" in the Ingres documentation.
Zobacz też:
- ingres_query() - Send an SQL query to Ingres
- ingres_fetch_array() - Fetch a row of result into an array
- ingres_fetch_assoc() - Fetch a row of result into an associative array
- ingres_fetch_object() - Fetch a row of result into an object
- ingres_fetch_row() - Fetch a row of result into an enumerated array
ingres_free_result
(PECL ingres >= 2.0.0)
ingres_free_result — Free the resources associated with a result identifier
Opis
$result
)
Parametry
-
result -
The query result identifier
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Free a result resource
<?php
$link = ingres_connect($database, $user, $password);
$result = ingres_query($link, "select * from table");
while ($row = ingres_fetch_row($result)) {
echo $row[1];
echo $row[2];
}
ingres_free_result($result);
ingres_close($link)
?>
ingres_next_error
(PECL ingres >= 2.0.0)
ingres_next_error — Get the next Ingres error
Opis
$link
] )
Get the next Ingres error for the last executed query. Each call to
ingres_next_error() can be followed by a call to
ingres_errno(), ingres_error()
or ingres_errsqlstate() to get the respective error
number, error text, or SQL STATE. While
ingres_next_error() returns TRUE, there are more errors
to fetch.
Parametry
-
link -
The connection link identifier
Zwracane wartości
ingres_next_error() returns TRUE if there is another
error to retrieve or FALSE when there are no more errors
Zobacz też:
- ingres_errno() - Zwraca ostatnio wygenerowany numer błędu Ingres
- ingres_error() - Zwraca znaczący komunikat o ostatnio wygenerowanym błędzie
- ingres_errsqlstate() - Zwraca ostatnio wygenerowany kod błędu SQLSTATE
ingres_num_fields
(PHP 4 >= 4.0.2, PHP 5 <= 5.0.5, PECL ingres >= 1.0.0)
ingres_num_fields — Pobiera liczbę pól zwracanych przez ostatnie zapytanie
Opis
$identyfikator_połączenia
)ingres_num_fields() zwraca liczbę pól dla wyniku zapytania, przekazanego przez serwer Ingres po wywołaniu ingres_query()
Parametry
-
identyfikator_połączenia -
Identyfikator połączenia.
Zwracane wartości
Zwraca liczbę pól.
Zobacz też:
- ingres_query() - Send an SQL query to Ingres
- ingres_fetch_array() - Fetch a row of result into an array
- ingres_fetch_assoc() - Fetch a row of result into an associative array
- ingres_fetch_object() - Fetch a row of result into an object
- ingres_fetch_row() - Fetch a row of result into an enumerated array
ingres_num_rows
(PHP 4 >= 4.0.2, PHP 5 <= 5.0.5, PECL ingres >= 1.0.0)
ingres_num_rows — Get the number of rows affected or returned by a query
Opis
$result
)This function primarily is meant to get the number of rows modified in the database. However, it can be used to retrieve the number of rows to fetch for a SELECT statement.
Informacja:
If scrollable cursors are disabled and this function is called before using ingres_fetch_array(), ingres_fetch_object(), or ingres_fetch_row(), the server will delete the result's data and the script will be unable to get them.
Instead, you should retrieve the result's data using one of these fetch functions in a loop until it returns
FALSE, indicating that no more results are available.
Parametry
-
result -
The result identifier for a query
Zwracane wartości
For delete, insert, or update queries, ingres_num_rows() returns the number of rows affected by the query. For other queries, ingres_num_rows() returns the number of rows in the query's result.
Zobacz też:
- ingres_query() - Send an SQL query to Ingres
- ingres_fetch_array() - Fetch a row of result into an array
- ingres_fetch_assoc() - Fetch a row of result into an associative array
- ingres_fetch_object() - Fetch a row of result into an object
- ingres_fetch_row() - Fetch a row of result into an enumerated array
ingres_pconnect
(PHP 4 >= 4.0.2, PHP 5 <= 5.0.5, PECL ingres >= 1.0.0)
ingres_pconnect — Open a persistent connection to an Ingres database
Opis
$database
[, string $username
[, string $password
[, array $options
]]]] )Open a persistent connection to an Ingres database.
There are only two differences between this function and ingres_connect(): First, when connecting, the function will initially try to find a (persistent) link that is already opened with the same parameters. If one is found, an identifier for it will be returned instead of opening a new connection. Second, the connection to the Ingres server will not be closed when the execution of the script ends. Instead, the link will remain open for future use (ingres_close() will not close links established by ingres_pconnect()). This type of link is therefore called "persistent".
Parametry
-
database -
The database name. Must follow the syntax:
[vnode::]dbname[/svr_class]
-
username -
The Ingres user name
-
password -
The password associated with
username -
options -
See ingres_connect() for the list of options that can be passed
Zwracane wartości
Returns an Ingres link resource on success lub FALSE w przypadku niepowodzenia
Zobacz też:
- ingres_connect() - Open a connection to an Ingres database
- ingres_close() - Zamyka połączenie z serwerem Ingres
ingres_prepare
(PECL ingres >= 1.1.0)
ingres_prepare — Prepare a query for later execution
Opis
Prepares a query for execution by ingres_execute().
The query becomes part of the currently open transaction. If there is no open transaction, ingres_query() opens a new transaction. To close the transaction, you can call either ingres_commit() to commit the changes made to the database or ingres_rollback() to cancel these changes. When the script ends, any open transaction is rolled back (by calling ingres_rollback()). You can also use ingres_autocommit() before opening a new transaction to have every SQL query immediately committed.
Informacja: Related Configurations
See also the ingres.describe, ingres.scrollable and ingres.utf8 directives in Runtime Configuration.
Parametry
-
link -
The connection link identifier
-
query -
A valid SQL query (see the Ingres SQL reference guide) in the Ingres documentation. See the query parameter in ingres_query() for a list of SQL statements which cannot be executed using ingres_prepare()
Zwracane wartości
ingres_prepare() returns a query result identifier that is used with ingres_execute() to execute the query. To see if an error occurred, use ingres_errno(), ingres_error(), or ingres_errsqlstate().
Zobacz też:
- ingres_unbuffered_query() - Send an unbuffered SQL query to Ingres
- ingres_fetch_array() - Fetch a row of result into an array
- ingres_fetch_assoc() - Fetch a row of result into an associative array
- ingres_fetch_object() - Fetch a row of result into an object
- ingres_fetch_row() - Fetch a row of result into an enumerated array
- ingres_commit() - Zatwierdza transakcję
- ingres_rollback() - Wycofuje transakcję
- ingres_autocommit() - Włącza lub wyłącza automatyczne zatwierdzanie
- ingres_set_environment() - Set environment features controlling output options
- ingres_errno() - Zwraca ostatnio wygenerowany numer błędu Ingres
- ingres_error() - Zwraca znaczący komunikat o ostatnio wygenerowanym błędzie
ingres_query
(PHP 4 >= 4.0.2, PHP 5 <= 5.0.5, PECL ingres >= 1.0.0)
ingres_query — Send an SQL query to Ingres
Opis
ingres_query() sends the given
query to the Ingres server.
The query becomes part of the currently open transaction. If there is no open transaction, ingres_query() opens a new transaction. To close the transaction, you can call either ingres_commit() to commit the changes made to the database or ingres_rollback() to cancel these changes. When the script ends, any open transaction is rolled back (by calling ingres_rollback()). You can also use ingres_autocommit() before opening a new transaction to have every SQL query immediately committed.
Informacja: Related Configurations
See also the ingres.describe, ingres.scrollable and ingres.utf8 directives in Runtime Configuration
Parametry
-
link -
The connection link identifier.
-
query -
A valid SQL query (see the Ingres SQL reference guide) in the Ingres documentation.
Data inside the query should be properly escaped.
The following types of SQL queries cannot be sent with this function:
- close (see ingres_close())
- commit (see ingres_commit())
- connect (see ingres_connect())
- disconnect (see ingres_close())
- get dbevent
- prepare to commit
- rollback (see ingres_rollback())
- savepoint
- set autocommit (see ingres_autocommit())
- all cursor-related queries are unsupported
-
params -
An array of parameter values to be used with the query
-
types -
A string containing a sequence of types for the parameter values passed. When ingres.describe is enabled, this parameter can be ignored as the driver automatically fetches the expected parameter types from the server.
Type code Ingres type a BOOLEAN b BYTE B LONG BYTE/BLOB c CHAR d DATE/ANSIDATE/TIMESTAMP/TIME f FLOAT i INTEGER L LONG TEXT m MONEY M LONG NVARCHAR n NCHAR N NVARCHAR t TEXT v VARCHAR V LONG VARCHAR
Zwracane wartości
ingres_query() returns a query result identifier on
success else it returns FALSE. To see if an error
occurred use ingres_errno(),
ingres_error() or
ingres_errsqlstate().
Przykłady
Przykład #1 Send a simple select
<?php
$link = ingres_connect("demodb");
$result = ingres_query($link, "select * from user_profile");
while ($row = ingres_fetch_row($result)) {
echo $row[1];
echo $row[2];
}
?>
Przykład #2 Passing query parameters to ingres_query()
<?php
$link = ingres_connect("demodb");
$params[] = "Emma";
$query = "select * from user_profile where up_first = ?";
$result = ingres_query($link, $query, $params);
while ($row = ingres_fetch_row($result)) {
echo $row[1];
echo $row[2];
}
?>
Przykład #3 Inserting a BLOB with parameter types
<?php
$link = ingres_connect("demodb");
//Open a photo
$fh = fopen("photo.jpg","r");
$blob_data = stream_get_contents($fh);
fclose($fh);
//Prepare parameters
$params[] = $blob_data;
$params[] = 1201;
//Define parameter types
$param_types = "Bi";
$query = "update user_profile set up_image = ? where up_id = ?";
$result = ingres_query($link, $query , $params, $param_types);
if (ingres_errno())
{
echo ingres_errno() . "-" . ingres_error() . "\n";
}
ingres_commit($link);
ingres_close($link);
?>
Zobacz też:
- ingres_unbuffered_query() - Send an unbuffered SQL query to Ingres
- ingres_fetch_array() - Fetch a row of result into an array
- ingres_fetch_assoc() - Fetch a row of result into an associative array
- ingres_fetch_object() - Fetch a row of result into an object
- ingres_fetch_row() - Fetch a row of result into an enumerated array
- ingres_commit() - Zatwierdza transakcję
- ingres_rollback() - Wycofuje transakcję
- ingres_autocommit() - Włącza lub wyłącza automatyczne zatwierdzanie
- ingres_set_environment() - Set environment features controlling output options
- ingres_errno() - Zwraca ostatnio wygenerowany numer błędu Ingres
- ingres_error() - Zwraca znaczący komunikat o ostatnio wygenerowanym błędzie
ingres_result_seek
(PECL ingres >= 2.1.0)
ingres_result_seek — Set the row position before fetching data
Opis
$result
, int $position
)This function is used to position the cursor associated with the result resource before issuing a fetch. If ingres.array_index_start is set to 0 then the first row is 0 else it is 1. ingres_result_seek() can be used only with queries that make use of scrollable cursors. It cannot be used with ingres_unbuffered_query().
Informacja: Related Configurations
See also the ingres.scrollable and ingres.array_index_start directives in Runtime Configuration.
Parametry
-
result -
The result identifier for a query
-
position -
The row to position the cursor on. If ingres.array_index_start is set to 0, then the first row is 0, else it is 1
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Position the cursor on the 3rd row
<?php
$result=ingres_query($link, "select * from airport where ap_ccode = 'ES' order by ap_place asc");
/* goto row 3 */
if (!ingres_result_seek($result, 3))
{
echo ingres_errno() . " - " . ingres_error . "\n";
die("i died");
}
else
{
$airport = ingres_fetch_object ($result);
{
echo $airport->ap_iatacode . " - " . $airport->ap_name . "\n";
}
}
ingres_commit($link);
?>
Zobacz też:
- ingres_query() - Send an SQL query to Ingres
- ingres_fetch_array() - Fetch a row of result into an array
- ingres_fetch_assoc() - Fetch a row of result into an associative array
- ingres_fetch_object() - Fetch a row of result into an object
- ingres_fetch_row() - Fetch a row of result into an enumerated array
ingres_rollback
(PHP 4 >= 4.0.2, PHP 5 <= 5.0.5, PECL ingres >= 1.0.0)
ingres_rollback — Wycofuje transakcję
Opis
$identyfikator_połączenia
)ingres_rollback() wycofuje bieżącą, otwartą transakcję, w rzeczywistości anulując wszystkie zmiany zrobione w bazie danych w czasie trwania tej transakcji.
Bieżąca transakcja jest zamykana. Nowa transakcja może być rozpoczęta przez wysłanie zapytania za pomocą ingres_query().
Parametry
-
identyfikator_połączenia -
Identyfikator połączenia.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- ingres_query() - Send an SQL query to Ingres
- ingres_commit() - Zatwierdza transakcję
- ingres_autocommit() - Włącza lub wyłącza automatyczne zatwierdzanie
ingres_set_environment
(PECL ingres >= 1.2.0)
ingres_set_environment — Set environment features controlling output options
Opis
$link
, array $options
)ingres_set_environment() is called to set environmental options that affect the output of certain values from Ingres, such as the timezone, date format, decimal character separator, and float precision.
Parametry
-
link -
The connection link identifier
-
options -
An enumerated array of option name/value pairs. The following table lists the option name and the expected type
Option name Option type Description Example date_century_boundary integer The threshold by which a 2-digit year is determined to be in the current century or in the next century. Equivalent to II_DATE_CENTURY_BOUNDARY 50 timezone string Controls the timezone of the session. If not set, it will default the value defined by II_TIMEZONE_NAME. If II_TIMEZONE_NAME is not defined, NA-PACIFIC (GMT-8 with Daylight Savings) is used. UNITED-KINGDOM date_format integer Sets the allowable input and output format for Ingres dates. Defaults to the value defined by II_DATE_FORMAT. If II_DATE_FORMAT is not set, the default date format is US, for example mm/dd/yy. Valid values for date_format are:
- INGRES_DATE_DMY
- INGRES_DATE_FINISH
- INGRES_DATE_GERMAN
- INGRES_DATE_ISO
- INGRES_DATE_ISO4
- INGRES_DATE_MDY
- INGRES_DATE_MULTINATIONAL
- INGRES_DATE_MULTINATIONAL4
- INGRES_DATE_YMD
- INGRES_DATE_US
INGRES_DATE_ISO4 decimal_separator string The character identifier for decimal data "," money_lort integer Leading or trailing currency sign. Valid values for money_lort are:
- INGRES_MONEY_LEADING
- INGRES_MONEY_TRAILING
INGRES_MONEY_LEADING money_sign string The currency symbol to be used with the MONEY datatype € money_precision integer The precision of the MONEY datatype 2 float4_precision integer Precision of the FLOAT4 datatype 10 float8_precision integer Precision of the FLOAT8 data 10 blob_segment_length integer The amount of data in bytes to fetch at a time when retrieving BLOB or CLOB data. Defaults to 4096 bytes when not set explicitly 8192
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Set date_format to ISO4
<?php
$options = array( "date_format" => INGRES_DATE_ISO4 );
if (ingres_set_environment($link, $options))
{
$result=ingres_query($link,"select date('now') as date");
while ( $object = ingres_fetch_object ($result) ) {
echo $object->date."\n";
}
}
?>
Przykład #2 Set timezone to HONG-KONG
<?php
$options = array( "timezone" => "HONG-KONG");
if (ingres_set_environment($link, $options))
{
$result=ingres_query($link,"select date('now') as date");
while ( $object = ingres_fetch_object ($result) ) {
echo $object->date."\n";
}
}
?>
Zobacz też:
- ingres_connect() - Open a connection to an Ingres database
- ingres_query() - Send an SQL query to Ingres
ingres_unbuffered_query
(No version information available, might only be in SVN)
ingres_unbuffered_query — Send an unbuffered SQL query to Ingres
Opis
$link
, string $query
[, array $params
[, string $types
]] )
ingres_unbuffered_query() sends the given
query to the Ingres server.
The query becomes part of the currently open transaction. If there is no open transaction, ingres_unbuffered_query() opens a new transaction. To close the transaction, you can call either ingres_commit() to commit the changes made to the database or ingres_rollback() to cancel these changes. When the script ends, any open transaction is rolled back (by calling ingres_rollback()). You can also use ingres_autocommit() before opening a new transaction to have every SQL query immediately committed. Ingres allows only a single unbuffered statement to be active at any one time. The extension will close any active unbuffered statements before executing any SQL. In addition you cannot use ingres_result_seek() to position the row before fetching.
Informacja: Related Configurations
See also the ingres.describe and ingres.utf8 directives in Runtime Configuration.
Parametry
-
link -
The connection link identifier
-
query -
A valid SQL query (see the Ingres SQL reference guide) in the Ingres documentation. See the query parameter in ingres_query() for a list of SQL statements that cannot be executed via ingres_unbuffered_query().
Data inside the query should be properly escaped.
-
params -
An array of parameter values to be used with the query
-
types -
A string containing a sequence of types for the parameter values passed. See the types parameter in ingres_query() for the list of type codes.
Zwracane wartości
ingres_unbuffered_query() returns a query result identifier when
there are rows to fetch; else it returns FALSE when there are no rows, as
is the case of an INSERT, UPDATE, or DELETE statement. To see if an error
occurred, use ingres_errno(),
ingres_error(), or
ingres_errsqlstate().
Przykłady
Przykład #1 Issue a simple un-buffered select
<?php
$link = ingres_connect("demodb");
$result = ingres_unbuffered_query($link, "select * from user_profile");
while ($row = ingres_fetch_row($result)) {
echo $row[1];
echo $row[2];
}
?>
Przykład #2 Passing query parameters to ingres_unbuffered_query()
<?php
$link = ingres_connect("demodb");
$params[] = "Emma";
$query = "select * from user_profile where up_first = ?";
$result = ingres_unbuffered_query($link, $query, $params);
while ($row = ingres_fetch_row($result)) {
echo $row[1];
echo $row[2];
}
?>
Przykład #3 Inserting a BLOB with parameter types
<?php
$link = ingres_connect("demodb");
//Open a photo
$fh = fopen("photo.jpg","r");
$blob_data = stream_get_contents($fh);
fclose($fh);
//Prepare parameters
$params[] = $blob_data;
$params[] = 1201;
//Define parameter types
$param_types = "Bi";
$query = "update user_profile set up_image = ? where up_id = ?";
$result = ingres_unbuffered_query($link, $query , $params, $param_types);
if (ingres_errno())
{
echo ingres_errno() . "-" . ingres_error() . "\n";
}
?>
Zobacz też:
- ingres_query() - Send an SQL query to Ingres
- ingres_fetch_array() - Fetch a row of result into an array
- ingres_fetch_assoc() - Fetch a row of result into an associative array
- ingres_fetch_object() - Fetch a row of result into an object
- ingres_fetch_row() - Fetch a row of result into an enumerated array
- ingres_commit() - Zatwierdza transakcję
- ingres_rollback() - Wycofuje transakcję
- ingres_autocommit() - Włącza lub wyłącza automatyczne zatwierdzanie
- ingres_set_environment() - Set environment features controlling output options
- ingres_errno() - Zwraca ostatnio wygenerowany numer błędu Ingres
- ingres_error() - Zwraca znaczący komunikat o ostatnio wygenerowanym błędzie
Spis treści
- ingres_autocommit_state — Test if the connection is using autocommit
- ingres_autocommit — Włącza lub wyłącza automatyczne zatwierdzanie
- ingres_charset — Returns the installation character set
- ingres_close — Zamyka połączenie z serwerem Ingres
- ingres_commit — Zatwierdza transakcję
- ingres_connect — Open a connection to an Ingres database
- ingres_cursor — Get a cursor name for a given result resource
- ingres_errno — Zwraca ostatnio wygenerowany numer błędu Ingres
- ingres_error — Zwraca znaczący komunikat o ostatnio wygenerowanym błędzie
- ingres_errsqlstate — Zwraca ostatnio wygenerowany kod błędu SQLSTATE
- ingres_escape_string — Escape special characters for use in a query
- ingres_execute — Execute a prepared query
- ingres_fetch_array — Fetch a row of result into an array
- ingres_fetch_assoc — Fetch a row of result into an associative array
- ingres_fetch_object — Fetch a row of result into an object
- ingres_fetch_proc_return — Get the return value from a procedure call
- ingres_fetch_row — Fetch a row of result into an enumerated array
- ingres_field_length — Get the length of a field
- ingres_field_name — Zwraca nazwę pola z wyniku zapytania
- ingres_field_nullable — Sprawdza czy pole może przyjmować wartość NULL
- ingres_field_precision — Get the precision of a field
- ingres_field_scale — Get the scale of a field
- ingres_field_type — Get the type of a field in a query result
- ingres_free_result — Free the resources associated with a result identifier
- ingres_next_error — Get the next Ingres error
- ingres_num_fields — Pobiera liczbę pól zwracanych przez ostatnie zapytanie
- ingres_num_rows — Get the number of rows affected or returned by a query
- ingres_pconnect — Open a persistent connection to an Ingres database
- ingres_prepare — Prepare a query for later execution
- ingres_query — Send an SQL query to Ingres
- ingres_result_seek — Set the row position before fetching data
- ingres_rollback — Wycofuje transakcję
- ingres_set_environment — Set environment features controlling output options
- ingres_unbuffered_query — Send an unbuffered SQL query to Ingres
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Przykłady
- Funkcje Ingres
- ingres_autocommit_state — Test if the connection is using autocommit
- ingres_autocommit — Włącza lub wyłącza automatyczne zatwierdzanie
- ingres_charset — Returns the installation character set
- ingres_close — Zamyka połączenie z serwerem Ingres
- ingres_commit — Zatwierdza transakcję
- ingres_connect — Open a connection to an Ingres database
- ingres_cursor — Get a cursor name for a given result resource
- ingres_errno — Zwraca ostatnio wygenerowany numer błędu Ingres
- ingres_error — Zwraca znaczący komunikat o ostatnio wygenerowanym błędzie
- ingres_errsqlstate — Zwraca ostatnio wygenerowany kod błędu SQLSTATE
- ingres_escape_string — Escape special characters for use in a query
- ingres_execute — Execute a prepared query
- ingres_fetch_array — Fetch a row of result into an array
- ingres_fetch_assoc — Fetch a row of result into an associative array
- ingres_fetch_object — Fetch a row of result into an object
- ingres_fetch_proc_return — Get the return value from a procedure call
- ingres_fetch_row — Fetch a row of result into an enumerated array
- ingres_field_length — Get the length of a field
- ingres_field_name — Zwraca nazwę pola z wyniku zapytania
- ingres_field_nullable — Sprawdza czy pole może przyjmować wartość NULL
- ingres_field_precision — Get the precision of a field
- ingres_field_scale — Get the scale of a field
- ingres_field_type — Get the type of a field in a query result
- ingres_free_result — Free the resources associated with a result identifier
- ingres_next_error — Get the next Ingres error
- ingres_num_fields — Pobiera liczbę pól zwracanych przez ostatnie zapytanie
- ingres_num_rows — Get the number of rows affected or returned by a query
- ingres_pconnect — Open a persistent connection to an Ingres database
- ingres_prepare — Prepare a query for later execution
- ingres_query — Send an SQL query to Ingres
- ingres_result_seek — Set the row position before fetching data
- ingres_rollback — Wycofuje transakcję
- ingres_set_environment — Set environment features controlling output options
- ingres_unbuffered_query — Send an unbuffered SQL query to Ingres
MaxDB
Wstęp
The MaxDB PHP extension allows you to access the functionality provided by MaxDB 7.5.0 and above. More information about the MaxDB Database server can be found at » http://www.sdn.sap.com/irj/sdn/maxdb.
The MaxDB PHP extension is compatible to the MySQL mysqli extension. There are only minor differences in the behaviour of some functions due to the differences of the underlying database servers, MaxDB and MySQL.
The main differences to mysqli are in the following functions:
- maxdb_character_set_name() - Returns only ascii or unicode.
- maxdb_get_client_info() - Returns a different version string.
- maxdb_get_client_version() - Returns a different version string.
- maxdb_get_host_info() - Returns localhost or hostname.
- maxdb_get_server_info() - Returns a different version string.
- maxdb_get_server_version() - Returns a different version string.
- maxdb_kill() - Only disconnects the session.
- maxdb_multi_query() - Can not handle multiple SQL statements.
- maxdb_next_result() - Function returns always false.
- maxdb_options() - Supports a different set of options.
- maxdb_report() - Supports a different report mode.
- maxdb_stat() - Returns a different system status string.
- maxdb_stmt_store_result() - Is not necessary for MaxDB.
- maxdb_store_result() - Is not necessary for MaxDB.
Documentation for MaxDB can be found at » http://maxdb.sap.com/documentation/.
Instalacja/Konfiguracja
Spis treści
Wymagania
In order to have these functions available, you must compile PHP with MaxDB support. Additionally, you must have the MaxDB SQLDBC runtime library available to access the MaxDB server.
Documentation for MaxDB SQLDBC can be found at » http://maxdb.sap.com/documentation/.
Download the MaxDB SQLDBC package from » http://www.sdn.sap.com/irj/sdn/maxdb-downloads.
Instalacja
By using the --with-maxdb[=DIR] configuration option you enable PHP to access MaxDB databases. [DIR] points to the directory that contains the installed MaxDB SQLDBC package.
Windows users will need to enable php_maxdb.dll inside of php.ini.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| maxdb.default_host | NULL | PHP_INI_ALL | |
| maxdb.default_db | NULL | PHP_INI_ALL | |
| maxdb.default_user | NULL | PHP_INI_ALL | |
| maxdb.default_pw | NULL | PHP_INI_ALL | |
| maxdb.long_readlen | "200" | PHP_INI_ALL |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
maxdb.default_hoststring -
The default server host to use when connecting to the database server if no other host is specified.
-
maxdb.default_dbstring -
The default server database to use when connecting if no other database is specified.
-
maxdb.default_userstring -
The default user name to use when connecting to the database server if no other name is specified.
-
maxdb.default_pwstring -
The default password to use when connecting to the database server if no other password is specified.
-
maxdb.long_readleninteger -
The default maximum length of bytes that is transferred to the client if long data is retrieved from the MaxDB database server.
Typy zasobów
This extension defines resources.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
The following constants to use with maxdb_options() are defined. For further description of these constants see » http://maxdb.sap.com/documentation/.
| Constant | Description |
|---|---|
| MAXDB_COMPNAME | The component name used to initialise the SQLDBC runtime environment. |
| MAXDB_APPLICATION | The application to be connected to the database. |
| MAXDB_APPVERSION | The version of the application. |
| MAXDB_SQLMODE | The SQL mode. |
| MAXDB_UNICODE | TRUE, if the connection is an unicode (UCS2) client or FALSE, if not. |
| MAXDB_TIMEOUT | The maximum allowed time of inactivity after which the connection to the database is closed by the system. |
| MAXDB_ISOLATIONLEVEL | Specifies whether and how shared locks and exclusive locks are implicitly requested or released. |
| MAXDB_PACKETCOUNT | The number of different request packets used for the connection. |
| MAXDB_STATEMENTCACHESIZE | The number of prepared statements to be cached for the connection for re-use. |
| MAXDB_CURSORPREFIX | The prefix to use for result tables that are automatically named. |
The function maxdb_fetch_array() uses a constant for the different types of result arrays. The following constants are defined:
| Constant | Description |
|---|---|
| MAXDB_ASSOC | Columns are returned into the array having the fieldname as the array index. |
| MAXDB_ASSOC_UPPER | Columns are returned into the array having the upper case fieldname as the array index. |
| MAXDB_ASSOC_LOWER | Columns are returned into the array having the lower case fieldname as the array index. |
| MAXDB_BOTH | Columns are returned into the array having both a numerical index and the fieldname as the array index. |
| MAXDB_NUM | Columns are returned into the array having a numerical index to the fields. This index starts with 0, the first field in the result. |
Przykłady
Spis treści
Basic usage
All examples in the MaxDB PHP documentation use the HOTELDB demo database from MaxDB. More about this database can be found at » http://maxdb.sap.com/doc/7_7/44/d8c25164bb38d0e10000000a1553f7/content.htm.
To use the examples in the MaxDB PHP documentation, you have to load the tutorial data into your database. Then you have to set maxdb.default_db in php.ini to the database that contains the tutorial data.
This simple example shows how to connect, execute a query, print resulting rows and disconnect from a MaxDB database.
Przykład #1 MaxDB extension overview example
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* Performing SQL query */
$query = "SELECT * FROM hotel.city";
$result = maxdb_query($link, $query) or die("Query failed : " . maxdb_error());
/* Printing results in HTML */
echo "<table>\n";
while ($line = maxdb_fetch_array($result, MAXDB_ASSOC)) {
echo " <tr>\n";
foreach ($line as $col_value) {
echo " <td>$col_value</td>\n";
}
echo " </tr>\n";
}
echo "</table>\n";
/* Free resultset */
maxdb_free_result($result);
/* Closing connection */
maxdb_close($link);
?>
The following example shows how to bind variables to a SELECT INTO statement.
Przykład #2 Example for use of SELECT INTO statements
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (!$link) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* Performing SQL query */
$stmt = maxdb_prepare ($link, "SELECT percentage INTO ? FROM hotel.countrylanguage where language = ?");
if (!$stmt) {
printf ("Prepare failed: %s\n", maxdb_error($link));
}
$name = "Mbundu";
maxdb_stmt_bind_param($stmt, 'ds', $percentage, $name);
maxdb_stmt_execute($stmt);
printf ("%f\n", $percentage);
maxdb_stmt_close ($stmt);
?>
The following example shows how to use MaxDB database procedures.
Przykład #3 Example fore using database procedures
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (!$link) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
maxdb_report (MAXDB_REPORT_OFF);
maxdb_query($link,"DROP DBPROC test_proc");
maxdb_report (MAXDB_REPORT_ERROR);
$query = "create dbproc test_proc (INOUT e_text char(72)) AS select * from SYSDBA.DUAL; fetch into :e_text;";
maxdb_query($link, $query);
/* Performing SQL query */
$stmt = maxdb_prepare ($link, "CALL test_proc (?)");
if (!$stmt) {
printf ("Prepare failed: %s\n", maxdb_error($link));
}
maxdb_stmt_bind_param($stmt, 's', $result);
maxdb_stmt_execute($stmt);
printf ("%s\n", $result);
maxdb_stmt_close ($stmt);
?>
MaxDB Funkcje
Klasy predefiniowane
maxdb
Represents a connection between PHP and a MaxDB database.
Konstruktor
-
maxdb - construct a new maxdb object
Metody
-
autocommit - turns on or off auto-commiting database modifications
-
change_user - changes the user of the specified database connection
-
character_set_name - returns the default character set for the database connection
-
close - closes a previously opened connection
-
commit - commits the current transaction
-
connect - opens a new connection to MaxDB database server
-
debug - performs debugging operations
-
dump_debug_info - dumps debug information
-
get_client_info - returns client version
-
get_host_info - returns type of connection used
-
get_server_info - returns version of the MaxDB server
-
get_server_version - returns version of the MaxDB server
-
init - initializes maxdb object
-
info - retrieves information about the most recently executed query
-
kill - asks the server to kill a MaxDB thread
-
multi_query - performs multiple queries
-
more_results - check if more results exist from currently executed multi-query
-
next_result - reads next result from currently executed multi-query
-
options - set options
-
ping - pings a server connection or reconnects if there is no connection
-
prepare - prepares an SQL query
-
query - performs a query
-
real_connect - attempts to open a connection to MaxDB database server
-
escape_string - escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection
-
rollback - rolls back the current transaction
-
select_db - selects the default database
-
ssl_set - sets ssl parameters
-
stat - gets the current system status
-
stmt_init- initializes a statement for use with maxdb_stmt_prepare
-
store_result - transfers a resultset from last query
-
use_result - transfers an unbuffered resultset from last query
-
thread-safe - returns whether thread safety is given or not
Właściwości
-
affected_rows - gets the number of affected rows in a previous MaxDB operation
-
client_info - returns the MaxDB client version as a string
-
client_version - returns the MaxDB client version as an integer
-
errno - returns the error code for the most recent function call
-
error - returns the error string for the most recent function call
-
field_count - returns the number of columns for the most recent query
-
host_info - returns a string representing the type of connection used
-
info - retrieves information about the most recently executed query
-
insert_id - returns the auto generated id used in the last query
-
protocol_version - returns the version of the MaxDB protocol used
-
sqlstate - returns a string containing the SQLSTATE error code for the last error
-
thread_id - returns the thread ID for the current connection
-
warning_count - returns the number of warnings generated during execution of the previous SQL statement
maxdb_stmt
Represents a prepared statement.
Metody
-
bind_param - binds variables to a prepared statement
-
bind_result - binds variables to a prepared statement for result storage
-
close - closes a prepared statement
-
data-seek - seeks to an arbitrary row in a statement result set
-
execute - executes a prepared statement
-
fetch - fetches result from a prepared statement into bound variables
-
free_result - frees stored result memory for the given statement handle
-
result_metadata - retrieves a resultset from a prepared statement for metadata information
-
prepare - prepares an SQL query
-
send_long_data - sends data in chunks
-
close_long_data - end sending long data
-
reset - resets a prepared statement
-
store_result - buffers complete resultset from a prepared statement
Właściwości
-
affected_rows - returns affected rows from last statement execution
-
errno - returns errorcode for last statement function
-
errno - returns errormessage for last statement function
-
param_count - returns number of parameter for a given prepare statement
-
sqlstate - returns a string containing the SQLSTATE error code for the last statement function
maxdb_result
Represents the result set obtained from a query against the database.
Metody
-
close - closes resultset
-
data_seek - moves internal result pointer
-
fetch_field - gets column information from a resultset
-
fetch_fields - gets information for all columns from a resulset
-
fetch_field_direct - gets column information for specified column
-
fetch_array - fetches a result row as an associative array, a numeric array, or both.
-
fetch_assoc - fetches a result row as an associative array
-
fetch_object - fetches a result row as an object
-
fetch_row - gets a result row as an enumerated array
-
close - frees result memory
-
field_seek - set result pointer to a specified field offset
Właściwości
-
current_field - returns offset of current fieldpointer
-
field_count - returns number of fields in resultset
-
lengths - returns an array of columnlengths
-
num_rows - returns number of rows in resultset
maxdb_affected_rows
maxdb::affected_rows
(PECL maxdb >= 1.0)
maxdb_affected_rows -- maxdb::affected_rows — Gets the number of affected rows in a previous MaxDB operation
Opis
Styl proceduralny
$link
)Styl obiektowy
maxdb_affected_rows() returns the number of rows affected by the last
INSERT, UPDATE, or DELETE query associated with the provided link
parameter. If this number cannot be determined, this function will return -1.
Informacja:
For SELECT statements maxdb_affected_rows() works like maxdb_num_rows().
The maxdb_affected_rows() function only works with queries which modify a table. In order to return the number of rows from a SELECT query, use the maxdb_num_rows() function instead.
Zwracane wartości
An integer greater than zero indicates the number of rows affected or retrieved. Zero indicates that no records where updated for an UPDATE statement, no rows matched the WHERE clause in the query or that no query has yet been executed. -1 indicates that the number of rows affected can not be determined.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
maxdb_report (MAXDB_REPORT_OFF);
$maxdb->query("DROP TABLE mycustomer");
maxdb_report (MAXDB_REPORT_ERROR);
/* Insert rows */
$maxdb->query("CREATE TABLE mycustomer AS SELECT * from hotel.customer");
printf("Affected rows (INSERT): %d\n", $maxdb->affected_rows);
$maxdb->query("ALTER TABLE mycustomer ADD Status int default 0");
/* update rows */
$maxdb->query("UPDATE mycustomer SET Status=1 WHERE cno > 50");
printf("Affected rows (UPDATE): %d\n", $maxdb->affected_rows);
/* delete rows */
$maxdb->query("DELETE FROM mycustomer WHERE cno < 50");
printf("Affected rows (DELETE): %d\n", $maxdb->affected_rows);
/* select all rows */
$result = $maxdb->query("SELECT title FROM mycustomer");
printf("Affected rows (SELECT): %d\n", $maxdb->affected_rows);
$result->close();
/* Delete table Language */
$maxdb->query("DROP TABLE mycustomer");
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
if (!$link) {
printf("Can't connect to localhost. Error: %s\n", maxdb_connect_error());
exit();
}
maxdb_report (MAXDB_REPORT_OFF);
maxdb_query($link,"DROP TABLE mycustomer");
maxdb_report (MAXDB_REPORT_ERROR);
/* Insert rows */
maxdb_query($link, "CREATE TABLE mycustomer AS SELECT * from hotel.customer");
printf("Affected rows (INSERT): %d\n", maxdb_affected_rows($link));
maxdb_query($link, "ALTER TABLE mycustomer ADD Status int default 0");
/* update rows */
maxdb_query($link, "UPDATE mycustomer SET Status=1 WHERE cno > 50");
printf("Affected rows (UPDATE): %d\n", maxdb_affected_rows($link));
/* delete rows */
maxdb_query($link, "DELETE FROM mycustomer WHERE cno < 50");
printf("Affected rows (DELETE): %d\n", maxdb_affected_rows($link));
/* select all rows */
$result = maxdb_query($link, "SELECT title FROM mycustomer");
printf("Affected rows (SELECT): %d\n", maxdb_affected_rows($link));
maxdb_free_result($result);
/* Delete table Language */
maxdb_query($link, "DROP TABLE mycustomer");
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Affected rows (INSERT): 15 Affected rows (UPDATE): 15 Affected rows (DELETE): 0 Affected rows (SELECT): 15
Zobacz też:
- maxdb_num_rows() - Gets the number of rows in a result
- maxdb_info() - Retrieves information about the most recently executed query
maxdb_autocommit
maxdb::auto_commit
(PECL maxdb >= 1.0)
maxdb_autocommit -- maxdb::auto_commit — Turns on or off auto-commiting database modifications
Opis
Styl proceduralny
$link
, bool $mode
)Styl obiektowy
$mode
)
maxdb_autocommit() is used to turn on or off auto-commit mode
on queries for the database connection represented by the link
resource.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* turn autocommit on */
$maxdb->autocommit(TRUE);
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
if (!$link) {
printf("Can't connect to localhost. Error: %s\n", maxdb_connect_error());
exit();
}
/* turn autocommit on */
maxdb_autocommit($link, TRUE);
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Zobacz też:
- maxdb_commit() - Commits the current transaction
- maxdb_rollback() - Rolls back current transaction
Opis
Ta funkcja jest aliasem dla: maxdb_stmt_bind_param()
Ten alias jest nie zalecany i istnieje tylko dla zachowania kompatybilności wstecznej. Zaleca się nie używanie tego aliasu, jako że może on zostać usunięty w przyszłości z PHP.
Opis
Ta funkcja jest aliasem dla: maxdb_stmt_bind_result().
Ten alias jest nie zalecany i istnieje tylko dla zachowania kompatybilności wstecznej. Zaleca się nie używanie tego aliasu, jako że może on zostać usunięty w przyszłości z PHP.
maxdb_change_user
maxdb::change_user
(PECL maxdb >= 1.0)
maxdb_change_user -- maxdb::change_user — Changes the user of the specified database connection
Opis
Styl proceduralny
$link
, string $user
, string $password
, string $database
)Styl obiektowy
$user
, string $password
, string $database
)
maxdb_change_user() is used to change the user of the specified
database connection as given by the link parameter and to set the
current database to that specified by the database parameter.
In order to successfully change users a valid username and
password parameters must be provided and that user must have
sufficient permissions to access the desired database. If for any reason authorization
fails, the current user authentication will remain.
Informacja:
Using this command will always cause the current database connection to behave as if was a completely new database connection, regardless of if the operation was completed successfully. This reset includes performing a rollback on any active transactions, closing all temporary tables, and unlocking all locked tables.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Styl obiektowy
<?php
/* connect database test */
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
if ($result = $maxdb->query("SELECT * FROM dual")) {
$row = $result->fetch_row();
printf("Result: %s\n", $row[0]);
$result->free();
}
/* reset all and select a new database */
if (!$maxdb->change_user("DBADMIN", "SECRET", "DEMODB")) {
printf("Database not running\n");
} else {
printf("Database running\n");
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (!$link) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
if ($result = maxdb_query($link, "SELECT * FROM dual")) {
$row = maxdb_fetch_row($result);
printf("Result: %s\n", $row[0]);
maxdb_free_result($result);
}
/* reset all and select a new database */
if (!maxdb_change_user($link, "DBADMIN", "SECRET", "DEMODB")) {
printf("Database not running\n");
} else {
printf("Database running\n");
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Result: a Database running
Zobacz też:
- maxdb_connect() - Open a new connection to the MaxDB server
- maxdb_select_db() - Selects the default database for database queries
maxdb_character_set_name
maxdb::character_set_name
(PECL maxdb >= 1.0)
maxdb_character_set_name -- maxdb::character_set_name — Returns the default character set for the database connection
Opis
Styl proceduralny
$link
)Styl obiektowy
Returns the current character set for the database connection specified by the
link parameter.
Zwracane wartości
The default character set for the current connection, either ascii or unicode.
Przykłady
Przykład #1 Styl obiektowy
<?php
/* Open a connection */
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* Print current character set */
$charset = $maxdb->character_set_name();
printf ("Current character set is %s\n", $charset);
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (!$link) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* Print current character set */
$charset = maxdb_character_set_name($link);
printf ("Current character set is %s\n",$charset);
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Current character set is ascii
Zobacz też:
- maxdb_client_encoding() - Alias dla maxdb_character_set_name
- maxdb_real_escape_string() - Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection
Opis
Ta funkcja jest aliasem dla: maxdb_character_set_name().
Ten alias jest nie zalecany i istnieje tylko dla zachowania kompatybilności wstecznej. Zaleca się nie używanie tego aliasu, jako że może on zostać usunięty w przyszłości z PHP.
maxdb_close_long_data
maxdb->close_long_data
(PECL maxdb >= 1.0)
maxdb_close_long_data -- maxdb->close_long_data — Alias dla maxdb_stmt_close_long_data()
Opis
Ta funkcja jest aliasem dla: maxdb_stmt_close_long_data().
Ten alias jest nie zalecany i istnieje tylko dla zachowania kompatybilności wstecznej. Zaleca się nie używanie tego aliasu, jako że może on zostać usunięty w przyszłości z PHP.
maxdb_close
maxdb::close
(PECL maxdb >= 1.0)
maxdb_close -- maxdb::close — Closes a previously opened database connection
Opis
Styl proceduralny
$link
)Styl obiektowy
The maxdb_close() function closes a previously opened database
connection specified by the link parameter.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- maxdb_connect() - Open a new connection to the MaxDB server
- maxdb_init() - Initializes MaxDB and returns an resource for use with maxdb_real_connect
- maxdb_real_connect() - Opens a connection to a MaxDB server
maxdb_commit
maxdb::commit
(PECL maxdb >= 1.0)
maxdb_commit -- maxdb::commit — Commits the current transaction
Opis
Styl proceduralny
$link
)Styl obiektowy
Commits the current transaction for the database connection specified by the
link parameter.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* set autocommit to off */
$maxdb->autocommit(FALSE);
maxdb_report (MAXDB_REPORT_OFF);
$maxdb->query("DROP TABLE mycustomer");
maxdb_report (MAXDB_REPORT_ERROR);
$maxdb->query("CREATE TABLE mycustomer LIKE hotel.customer");
/* Insert some values */
$maxdb->query("INSERT INTO mycustomer VALUES (3000,'Mrs','Jenny','Porter','10580','1340 N.Ash Street, #3')");
$maxdb->query("INSERT INTO mycustomer VALUES (3100,'Mr','Peter','Brown','48226','1001 34th Str., APT.3')");
/* commit transaction */
$maxdb->commit();
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (!$link) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* set autocommit to off */
maxdb_autocommit($link, FALSE);
maxdb_report (MAXDB_REPORT_OFF);
maxdb_query($link,"DROP TABLE mycustomer");
maxdb_report (MAXDB_REPORT_ERROR);
maxdb_query($link, "CREATE TABLE mycustomer LIKE hotel.customer");
/* Insert some values */
maxdb_query($link, "INSERT INTO mycustomer VALUES (3000,'Mrs','Jenny','Porter','10580','1340 N.Ash Street, #3')");
maxdb_query($link, "INSERT INTO mycustomer VALUES (3100,'Mr','Peter','Brown','48226','1001 34th Str., APT.3')");
/* commit transaction */
maxdb_commit($link);
/* close connection */
maxdb_close($link);
?>
The above examples produces no output.
Zobacz też:
- maxdb_autocommit() - Turns on or off auto-commiting database modifications
- maxdb_rollback() - Rolls back current transaction
maxdb_connect_errno
(PECL maxdb >= 1.0)
maxdb_connect_errno — Returns the error code from last connect call
Opis
The maxdb_connect_errno() function will return the last error code number for last call to maxdb_connect(). If no errors have occured, this function will return zero.
Zwracane wartości
An error code value for the last call to maxdb_connect(), if it failed. zero means no error occurred.
Przykłady
Przykład #1 maxdb_connect_errno sample
<?php
$link = maxdb_connect("localhost", "XXXXXXXX", "YYYYYYYYY");
if (!$link) {
printf("Can't connect to localhost. Errorcode: %d\n", maxdb_connect_errno());
}
?>
Powyższy przykład wyświetli coś podobnego do:
PHP Warning: maxdb_connect(): -4008 POS(1) Unknown user name/password combination [08004] <...> Can't connect to localhost. Errorcode: -4008
Zobacz też:
- maxdb_connect() - Open a new connection to the MaxDB server
- maxdb_connect_error() - Returns a string description of the last connect error
- maxdb_errno() - Returns the error code for the most recent function call
- maxdb_error() - Returns a string description of the last error
- maxdb_sqlstate() - Returns the SQLSTATE error from previous MaxDB operation
maxdb_connect_error
(PECL maxdb >= 1.0)
maxdb_connect_error — Returns a string description of the last connect error
Opis
The maxdb_connect_error() function is identical to the corresponding maxdb_connect_errno() function in every way, except instead of returning an integer error code the maxdb_connect_error() function will return a string representation of the last error to occur for the last maxdb_connect() call. If no error has occured, this function will return an empty string.
Zwracane wartości
A string that describes the error. An empty string if no error occurred.
Przykłady
Przykład #1 maxdb_connect_error sample
<?php
$link = maxdb_connect("localhost", "nonexisting_user", "");
if (!$link) {
printf("Can't connect to localhost. Error: %s\n", maxdb_connect_error());
}
?>
Powyższy przykład wyświetli coś podobnego do:
PHP Warning: maxdb_connect(): -4008 POS(1) Unknown user name/password combination <...> Can't connect to localhost. Error: POS(1) Unknown user name/password combination
Zobacz też:
- maxdb_connect() - Open a new connection to the MaxDB server
- maxdb_connect_errno() - Returns the error code from last connect call
- maxdb_errno() - Returns the error code for the most recent function call
- maxdb_error() - Returns a string description of the last error
- maxdb_sqlstate() - Returns the SQLSTATE error from previous MaxDB operation
maxdb_connect
maxdb::__construct
(PECL maxdb >= 1.0)
maxdb_connect -- maxdb::__construct — Open a new connection to the MaxDB server
Opis
Styl proceduralny
$host
[, string $username
[, string $passwd
[, string $dbname
[, int $port = 0
[, string $socket
]]]]]] )Styl obiektowy
$host
[, string $username
[, string $passwd
[, string $dbname
[, int $port = 0
[, string $socket
]]]]]] )
The maxdb_connect() function attempts to open a connection to the MaxDB Server
running on host which can be either a host name or an IP address. Passing the
string "localhost" to this parameter, the local host is assumed.
If successful, the maxdb_connect()
will return an resource representing the connection to the database lub FALSE w przypadku niepowodzenia.
The username and password parameters specify the
username and password under which to connect to the MaxDB server. If the password is not provided
(the NULL value is passed), the MaxDB server will attempt to authenticate the user against
the maxdb.default_pw in php.ini.
The dbname parameter if provided will specify the default database to be
used when performing queries. If not provied, the entry maxdb.default_db
in php.ini is used.
The port and socket parameters are
ignored for the MaxDB server.
Zwracane wartości
Returns a resource which represents the connection to a MaxDB Server or
FALSE if the connection failed.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
printf("Host information: %s\n", $maxdb->host_info);
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (!$link) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
printf("Host information: %s\n", maxdb_get_host_info($link));
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Host information: localhost
maxdb_data_seek
maxdb_result::data_seek
(PECL maxdb >= 1.0)
maxdb_data_seek -- maxdb_result::data_seek — Adjusts the result pointer to an arbitary row in the result
Opis
Styl proceduralny
$result
, int $offset
)Styl obiektowy
$offset
)
The maxdb_data_seek() function seeks to an arbitrary result pointer
specified by the offset in the result set represented by
result. The offset parameter must be between
zero and the total number of rows minus one (0..maxdb_num_rows() - 1).
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Styl obiektowy
<?php
/* Open a connection */
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT name, state FROM hotel.city ORDER BY name";
if ($result = $maxdb->query( $query)) {
/* seek to row no. 10 */
$result->data_seek(10);
/* fetch row */
$row = $result->fetch_row();
printf ("City: %s State: %s\n", $row[0], $row[1]);
/* free result set*/
$result->close();
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (!$link) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT name, state FROM hotel.city ORDER BY name";
if ($result = maxdb_query($link, $query)) {
/* seek to row no. 400 */
maxdb_data_seek($result, 10);
/* fetch row */
$row = maxdb_fetch_row($result);
printf ("City: %s State: %s\n", $row[0], $row[1]);
/* free result set*/
maxdb_free_result($result);
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
City: Irvine State: CA
Zobacz też:
- maxdb_store_result() - Transfers a result set from the last query
- maxdb_fetch_row() - Get a result row as an enumerated array
- maxdb_num_rows() - Gets the number of rows in a result
maxdb_debug
(PECL maxdb >= 1.0)
maxdb_debug — Performs debugging operations
Opis
$debug
)The maxdb_debug() can be used to trace the SQLDBC communication. The following strings can be used as a parameter to maxdb_debug():
- TRACE SHORT ON|OFF - Enables/disables method call trace.
- TRACE LONG ON|OFF - Enables/disables method argument and detail debug trace.
- TRACE PACKET ON|OFF|<size> - Enables/disables packet trace, limiting the size of the traced object to the specified number of bytes, or 1000 if no size is specified.
- TRACE SQL ON|OFF - Enables/disables high level api trace.
- TRACE TIMESTAMP ON|OFF - Enables/disables a timestamp prefix on each line that is traced.
- TRACE SIZE <size> - Limits the size of the trace file to <size> bytes, at least 8192 bytes are required.
Zwracane wartości
maxdb_debug() doesn't return any value.
Przykłady
Przykład #1 Styl proceduralny
<?php
maxdb_debug("trace packet 200");
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (!$link) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* close connection */
maxdb_close($link);
?>
The above example produces no output.
maxdb_disable_reads_from_master
maxdb::disable_reads_from_master
(PECL maxdb >= 1.0)
maxdb_disable_reads_from_master -- maxdb::disable_reads_from_master — Disable reads from master
Opis
Styl proceduralny
$link
)Styl obiektowy
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
maxdb_disable_rpl_parse
(PECL maxdb >= 1.0)
maxdb_disable_rpl_parse — Disable RPL parse
Opis
$link
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
maxdb_dump_debug_info
(PECL maxdb >= 1.0)
maxdb_dump_debug_info — Dump debugging information into the log
Opis
$link
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
maxdb_embedded_connect
(PECL maxdb >= 1.0)
maxdb_embedded_connect — Open a connection to an embedded MaxDB server
Opis
$dbname
] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
maxdb_enable_reads_from_master
(PECL maxdb >= 1.0)
maxdb_enable_reads_from_master — Enable reads from master
Opis
$link
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
maxdb_enable_rpl_parse
(PECL maxdb >= 1.0)
maxdb_enable_rpl_parse — Enable RPL parse
Opis
$link
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
maxdb_errno
maxdb::errno
(PECL maxdb >= 1.0)
maxdb_errno -- maxdb::errno — Returns the error code for the most recent function call
Opis
Styl proceduralny
$link
)Styl obiektowy
The maxdb_errno() function will return the last error code for
the most recent MaxDB function call that can succeed or fail with respect to the
database link defined by the link parameter. If no errors
have occured, this function will return zero.
Zwracane wartości
An error code value for the last call, if it failed. zero means no error occurred.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
if (!$maxdb->query("SELECT xxx FROM hotel.city")) {
printf("Errorcode: %d\n", $maxdb->errno);
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
if (!maxdb_query($link, "SELECT xxx FROM hotel.city")) {
printf("Errorcode: %d\n", maxdb_errno($link));
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
PHP Warning: maxdb_query(): -4005 POS(8) Unknown column name:XXX [42000] <...> Errorcode: -4005
Zobacz też:
- maxdb_connect_errno() - Returns the error code from last connect call
- maxdb_connect_error() - Returns a string description of the last connect error
- maxdb_error() - Returns a string description of the last error
- maxdb_sqlstate() - Returns the SQLSTATE error from previous MaxDB operation
maxdb_error
maxdb::error
(PECL maxdb >= 1.0)
maxdb_error -- maxdb::error — Returns a string description of the last error
Opis
Styl proceduralny
$link
)Styl obiektowy
The maxdb_error() function is identical to the corresponding
maxdb_errno() function in every way, except instead of returning
an integer error code the maxdb_error() function will return
a string representation of the last error to occur for the database connection
represented by the link parameter. If no error has occured,
this function will return an empty string.
Zwracane wartości
A string that describes the error. An empty string if no error occurred.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
if (!$maxdb->query("SELECT xxx FROM hotel.city")) {
printf("Errormessage: %s\n", $maxdb->error);
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
if (!maxdb_query($link, "SELECT xxx FROM hotel.city")) {
printf("Errormessgae: %s\n", maxdb_error($link));
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
PHP Warning: maxdb_query(): -4005 POS(8) Unknown column name:XXX [42000] Errormessgae: POS(8) Unknown column name:XXX
Zobacz też:
- maxdb_connect_errno() - Returns the error code from last connect call
- maxdb_connect_error() - Returns a string description of the last connect error
- maxdb_errno() - Returns the error code for the most recent function call
- maxdb_sqlstate() - Returns the SQLSTATE error from previous MaxDB operation
Opis
Ta funkcja jest aliasem dla: maxdb_real_escape_string().
Opis
Ta funkcja jest aliasem dla: maxdb_stmt_execute().
Ten alias jest nie zalecany i istnieje tylko dla zachowania kompatybilności wstecznej. Zaleca się nie używanie tego aliasu, jako że może on zostać usunięty w przyszłości z PHP.
maxdb_fetch_array
maxdb_result::fetch_array
(PECL maxdb >= 1.0)
maxdb_fetch_array -- maxdb_result::fetch_array — Fetch a result row as an associative, a numeric array, or both
Opis
Styl proceduralny
Styl obiektowy
Returns an array that corresponds to the fetched row or NULL if there are no more rows for the
resultset represented by the result parameter.
maxdb_fetch_array() is an extended version of the maxdb_fetch_row() function. In addition to storing the data in the numeric indices of the result array, the maxdb_fetch_array() function can also store the data in associative indices, using the field names of the result set as keys.
Informacja: Nazwy pól zwracane przez tą funkcję rozróżniają wielkość znaków.
Informacja: Ta funkcja ustala wartość pól NULL na
NULL.
If two or more columns of the result have the same field names, the last column will take precedence and overwrite the earlier data. In order to access multiple columns with the same name, the numerically indexed version of the row must be used.
The optional second argument resulttype is a constant indicating what
type of array should be produced from the current row data. The possible values for this parameter
are the constants MAXDB_ASSOC, MAXDB_ASSOC_UPPER, MAXDB_ASSOC_LOWER, MAXDB_NUM, or MAXDB_BOTH.
By default the
maxdb_fetch_array() function will assume MAXDB_BOTH, which is a combination of
MAXDB_NUM and MAXDB_ASSOC for this parameter.
By using the MAXDB_ASSOC constant this function will behave identically to the maxdb_fetch_assoc(), while MAXDB_NUM will behave identically to the maxdb_fetch_row() function. The final option MAXDB_BOTH will create a single array with the attributes of both.
By using the MAXDB_ASSOC_UPPER constant, the behaviour of this function is identical to the use of MAXDB_ASSOC except the array index of a column is the fieldname in upper case.
By using the MAXDB_ASSOC_LOWER constant, the behaviour of this function is identical to the use of MAXDB_ASSOC except the array index of a column is the fieldname in lower case.
Zwracane wartości
Returns an array that corresponds to the fetched row or NULL if there are no more rows in resultset.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT name, state FROM hotel.city ORDER by zip";
$result = $maxdb->query($query);
/* numeric array */
$row = $result->fetch_array(MAXDB_NUM);
printf ("%s (%s)\n", $row[0], $row[1]);
/* associative array */
$row = $result->fetch_array(MAXDB_ASSOC);
printf ("%s (%s)\n", $row["NAME"], $row["STATE"]);
/* associative and numeric array */
$row = $result->fetch_array(MAXDB_BOTH);
printf ("%s (%s)\n", $row[0], $row["STATE"]);
/* free result set */
$result->close();
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT name, state FROM hotel.city ORDER by zip";
$result = maxdb_query($link, $query);
/* numeric array */
$row = maxdb_fetch_array($result, MAXDB_NUM);
printf ("%s (%s)\n", $row[0], $row[1]);
/* associative array */
$row = maxdb_fetch_array($result, MAXDB_ASSOC);
printf ("%s (%s)\n", $row["NAME"], $row["STATE"]);
/* associative and numeric array */
$row = maxdb_fetch_array($result, MAXDB_BOTH);
printf ("%s (%s)\n", $row[0], $row["STATE"]);
/* free result set */
maxdb_free_result($result);
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
New York (NY) New York (NY) Long Island (NY)
Zobacz też:
- maxdb_fetch_assoc() - Fetch a result row as an associative array
- maxdb_fetch_row() - Get a result row as an enumerated array
- maxdb_fetch_resource()
maxdb_fetch_assoc
maxdb_result::fetch_assoc
(PECL maxdb >= 1.0)
maxdb_fetch_assoc -- maxdb_result::fetch_assoc — Fetch a result row as an associative array
Opis
Styl proceduralny
$result
)Styl obiektowy
Returns an associative array that corresponds to the fetched row or NULL if there are
no more rows.
The maxdb_fetch_assoc() function is used to return an associative array
representing the next row in the result set for the result represented by the
result parameter, where each key in the array represents the name
of one of the result set's columns.
If two or more columns of the result have the same field names, the last column will take precedence. To access the other column(s) of the same name, you either need to access the result with numeric indices by using maxdb_fetch_row() or add alias names.
Informacja: Nazwy pól zwracane przez tą funkcję rozróżniają wielkość znaków.
Informacja: Ta funkcja ustala wartość pól NULL na
NULL.
Zwracane wartości
Returns an array that corresponds to the fetched row or NULL if there are no more rows in resultset.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT name, state FROM hotel.city ORDER by zip";
if ($result = $maxdb->query($query)) {
/* fetch associative array */
while ($row = $result->fetch_assoc()) {
printf ("%s (%s)\n", $row["NAME"], $row["STATE"]);
}
/* free result set */
$result->close();
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT name, state FROM hotel.city ORDER by zip";
if ($result = maxdb_query($link, $query)) {
/* fetch associative array */
while ($row = maxdb_fetch_assoc($result)) {
printf ("%s (%s)\n", $row["NAME"], $row["STATE"]);
}
/* free result set */
maxdb_free_result($result);
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
New York (NY) New York (NY) Long Island (NY) Albany (NY) Washington (DC) Washington (DC) Washington (DC) Silver Spring (MD) Daytona Beach (FL) Deerfield Beach (FL) Clearwater (FL) Cincinnati (OH) Detroit (MI) Rosemont (IL) Chicago (IL) Chicago (IL) New Orleans (LA) Dallas (TX) Los Angeles (CA) Hollywood (CA) Long Beach (CA) Palm Springs (CA) Irvine (CA) Santa Clara (CA) Portland (OR)
Zobacz też:
- maxdb_fetch_array() - Fetch a result row as an associative, a numeric array, or both
- maxdb_fetch_row() - Get a result row as an enumerated array
- maxdb_fetch_resource()
maxdb_fetch_field_direct
maxdb_result::fetch_field_direct
(PECL maxdb >= 1.0)
maxdb_fetch_field_direct -- maxdb_result::fetch_field_direct — Fetch meta-data for a single field
Opis
Styl proceduralny
Styl obiektowy
maxdb_fetch_field_direct() returns an resource which contains field definition information from specified resultset. The value of fieldnr must be in the range from 0 to number of fields - 1.
Zwracane wartości
Returns an resource which contains field definition information or FALSE if no field information
for specified fieldnr is available.
| Attribute | Description |
|---|---|
| name | The name of the column |
| max_length | The maximum width of the field for the result set. |
| type | The data type used for this field |
| decimals | The number of decimals used (for integer fields) |
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT name, cno from hotel.customer ORDER BY name";
if ($result = $maxdb->query($query)) {
/* Get field information for column 'SurfaceArea' */
$finfo = $result->fetch_field_direct(1);
printf("Name: %s\n", $finfo->name);
printf("Table: %s\n", $finfo->table);
printf("max. Len: %d\n", $finfo->max_length);
printf("Flags: %d\n", $finfo->flags);
printf("Type: %d\n", $finfo->type);
$result->close();
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT name, cno from hotel.customer ORDER BY name";
if ($result = maxdb_query($link, $query)) {
/* Get field information for column 'cno' */
$finfo = maxdb_fetch_field_direct($result, 1);
printf("Name: %s\n", $finfo->name);
printf("Table: %s\n", $finfo->table);
printf("max. Len: %d\n", $finfo->max_length);
printf("Flags: %d\n", $finfo->flags);
printf("Type: %d\n", $finfo->type);
maxdb_free_result($result);
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Name: CNO Table: max. Len: 4 Flags: -1 Type: 0
Zobacz też:
- maxdb_num_fields() - Get the number of fields in a result
- maxdb_fetch_field() - Returns the next field in the result set
- maxdb_fetch_fields() - Returns an array of resources representing the fields in a result set
maxdb_fetch_field
maxdb_result::fetch_field
(PECL maxdb >= 1.0)
maxdb_fetch_field -- maxdb_result::fetch_field — Returns the next field in the result set
Opis
Styl proceduralny
Styl obiektowy
The maxdb_fetch_field() returns the definition of one column
of a result set as an resource. Call this function repeatedly to retrieve
information about all columns in the result set.
maxdb_fetch_field() returns FALSE when no more fields
are left.
Zwracane wartości
Returns an resource which contains field definition information or FALSE if no field information
is available.
| Property | Description |
|---|---|
| name | The name of the column |
| max_length | The maximum width of the field for the result set. |
| type | The data type used for this field |
| decimals | The number of decimals used (for integer fields) |
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT name, cno from hotel.customer ORDER BY cno";
if ($result = $maxdb->query($query)) {
/* Get field information for all columns */
while ($finfo = $result->fetch_field()) {
printf("Name: %s\n", $finfo->name);
printf("Table: %s\n", $finfo->table);
printf("max. Len: %d\n", $finfo->max_length);
printf("Flags: %d\n", $finfo->flags);
printf("Type: %d\n\n", $finfo->type);
}
$result->close();
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT name, cno from hotel.customer ORDER BY cno";
if ($result = maxdb_query($link, $query)) {
/* Get field information for all fields */
while ($finfo = maxdb_fetch_field($result)) {
printf("Name: %s\n", $finfo->name);
printf("Table: %s\n", $finfo->table);
printf("max. Len: %d\n", $finfo->max_length);
printf("Flags: %d\n", $finfo->flags);
printf("Type: %d\n\n", $finfo->type);
}
maxdb_free_result($result);
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Name: NAME Table: max. Len: 10 Flags: -1 Type: 2 Name: CNO Table: max. Len: 4 Flags: -1 Type: 0
Zobacz też:
- maxdb_num_fields() - Get the number of fields in a result
- maxdb_fetch_field_direct() - Fetch meta-data for a single field
- maxdb_fetch_fields() - Returns an array of resources representing the fields in a result set
- maxdb_field_seek() - Set result pointer to a specified field offset
maxdb_fetch_fields
maxdb_result::fetch_fields
(PECL maxdb >= 1.0)
maxdb_fetch_fields -- maxdb_result::fetch_fields — Returns an array of resources representing the fields in a result set
Opis
Styl proceduralny
Styl obiektowy
This function serves an identical purpose to the maxdb_fetch_field() function with the single difference that, instead of returning one resource at a time for each field, the columns are returned as an array of resources.
Zwracane wartości
Returns an array of resources which contains field definition information or FALSE if no field information
is available.
| Property | Description |
|---|---|
| name | The name of the column |
| max_length | The maximum width of the field for the result set. |
| type | The data type used for this field |
| decimals | The number of decimals used (for integer fields) |
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT name, cno from hotel.customer ORDER BY cno";
if ($result = $maxdb->query($query)) {
/* Get field information for all columns */
$finfo = $result->fetch_fields();
foreach ($finfo as $val) {
printf("Name: %s\n", $val->name);
printf("Table: %s\n", $val->table);
printf("max. Len: %d\n", $val->max_length);
printf("Flags: %d\n", $val->flags);
printf("Type: %d\n\n", $val->type);
}
$result->close();
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT name, cno from hotel.customer ORDER BY cno";
if ($result = maxdb_query($link, $query)) {
/* Get field information for all columns */
$finfo = maxdb_fetch_fields($result);
foreach ($finfo as $val) {
printf("Name: %s\n", $val->name);
printf("Table: %s\n", $val->table);
printf("max. Len: %d\n", $val->max_length);
printf("Flags: %d\n", $val->flags);
printf("Type: %d\n\n", $val->type);
}
maxdb_free_result($result);
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Name: NAME Table: max. Len: 10 Flags: -1 Type: 2 Name: CNO Table: max. Len: 4 Flags: -1 Type: 0
Zobacz też:
- maxdb_num_fields() - Get the number of fields in a result
- maxdb_fetch_field() - Returns the next field in the result set
- maxdb_fetch_field_direct() - Fetch meta-data for a single field
maxdb_fetch_lengths
maxdb_result::lengths
(PECL maxdb >= 1.0)
maxdb_fetch_lengths -- maxdb_result::lengths — Returns the lengths of the columns of the current row in the result set
Opis
Styl proceduralny
$result
)Styl obiektowy
The maxdb_fetch_lengths() function returns an array containing the
lengths of every column of the current row within the result set represented by the
result parameter. If successful, a numerically indexed array
representing the lengths of each column is returned lub FALSE w przypadku niepowodzenia.
Zwracane wartości
An array of integers representing the size of each column (not including
any terminating null characters). FALSE if an error occurred.
maxdb_fetch_lengths() is valid only for the current row of the result set.
It returns FALSE if you call it before calling maxdb_fetch_row/array/resource or after retrieving
all rows in the result.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT * from hotel.customer WHERE cno = 3000";
if ($result = $maxdb->query($query)) {
$row = $result->fetch_row();
/* display column lengths */
foreach ($result->lengths as $i => $val) {
printf("Field %2d has Length %2d\n", $i+1, $val);
}
$result->close();
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT * from hotel.customer WHERE cno = 3000";
if ($result = maxdb_query($link, $query)) {
$row = maxdb_fetch_row($result);
/* display column lengths */
foreach (maxdb_fetch_lengths($result) as $i => $val) {
printf("Field %2d has Length %2d\n", $i+1, $val);
}
maxdb_free_result($result);
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Field 1 has Length 4 Field 2 has Length 3 Field 3 has Length 5 Field 4 has Length 6 Field 5 has Length 5 Field 6 has Length 21
maxdb_fetch_object
maxdb_result::fetch_object
(PECL maxdb >= 1.0)
maxdb_fetch_object -- maxdb_result::fetch_object — Returns the current row of a result set as an object
Opis
Styl proceduralny
$result
)Styl obiektowy
The maxdb_fetch_object() will return the current row result set
as an object where the attributes of the object represent the names of the fields found
within the result set. If no more rows exist in the current result set, NULL is returned.
Zwracane wartości
Returns an object that corresponds to the fetched row or NULL if there are no more rows in resultset.
Informacja: Nazwy pól zwracane przez tą funkcję rozróżniają wielkość znaków.
Informacja: Ta funkcja ustala wartość pól NULL na
NULL.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT name, state FROM hotel.city ORDER by zip";
if ($result = $maxdb->query($query)) {
/* fetch object array */
while ($obj = $result->fetch_object()) {
printf ("%s (%s)\n", $obj->NAME, $obj->STATE);
}
/* free result set */
$result->close();
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT name, state FROM hotel.city ORDER by zip";
if ($result = maxdb_query($link, $query)) {
/* fetch object array */
while ($obj = maxdb_fetch_object($result)) {
printf ("%s (%s)\n", $obj->NAME, $obj->STATE);
}
/* free result set */
maxdb_free_result($result);
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
New York (NY) New York (NY) Long Island (NY) Albany (NY) Washington (DC) Washington (DC) Washington (DC) Silver Spring (MD) Daytona Beach (FL) Deerfield Beach (FL) Clearwater (FL) Cincinnati (OH) Detroit (MI) Rosemont (IL) Chicago (IL) Chicago (IL) New Orleans (LA) Dallas (TX) Los Angeles (CA) Hollywood (CA) Long Beach (CA) Palm Springs (CA) Irvine (CA) Santa Clara (CA) Portland (OR)
Zobacz też:
- maxdb_fetch_array() - Fetch a result row as an associative, a numeric array, or both
- maxdb_fetch_assoc() - Fetch a result row as an associative array
- maxdb_fetch_row() - Get a result row as an enumerated array
maxdb_fetch_row
maxdb_result::fetch_row
(PECL maxdb >= 1.0)
maxdb_fetch_row -- maxdb_result::fetch_row — Get a result row as an enumerated array
Opis
Styl proceduralny
Styl obiektowy
Returns an array that corresponds to the fetched row, or NULL if there are no more rows.
maxdb_fetch_row() fetches one row of data from the result set represented by
result and returns it as an enumerated array, where each column is stored
in an array offset starting from 0 (zero). Each subsequent call to the
maxdb_fetch_row() function will return the next row within the result set,
or FALSE if there are no more rows.
Zwracane wartości
maxdb_fetch_row() returns an array that corresponds to the fetched row
or NULL if there are no more rows in result set.
Informacja: Ta funkcja ustala wartość pól NULL na
NULL.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT name, state FROM hotel.city ORDER by zip";
if ($result = $maxdb->query($query)) {
/* fetch enumerated array */
while ($row = $result->fetch_row()) {
printf ("%s (%s)\n", $row[0], $row[1]);
}
/* free result set */
$result->close();
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT name, state FROM hotel.city ORDER by zip";
if ($result = maxdb_query($link, $query)) {
/* fetch enumerated array */
while ($row = maxdb_fetch_row($result)) {
printf ("%s (%s)\n", $row[0], $row[1]);
}
/* free result set */
maxdb_free_result($result);
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
New York (NY) New York (NY) Long Island (NY) Albany (NY) Washington (DC) Washington (DC) Washington (DC) Silver Spring (MD) Daytona Beach (FL) Deerfield Beach (FL) Clearwater (FL) Cincinnati (OH) Detroit (MI) Rosemont (IL) Chicago (IL) Chicago (IL) New Orleans (LA) Dallas (TX) Los Angeles (CA) Hollywood (CA) Long Beach (CA) Palm Springs (CA) Irvine (CA) Santa Clara (CA) Portland (OR)
Zobacz też:
- maxdb_fetch_array() - Fetch a result row as an associative, a numeric array, or both
- maxdb_fetch_assoc() - Fetch a result row as an associative array
- maxdb_fetch_resource()
Opis
Ta funkcja jest aliasem dla: maxdb_stmt_fetch().
Ten alias jest nie zalecany i istnieje tylko dla zachowania kompatybilności wstecznej. Zaleca się nie używanie tego aliasu, jako że może on zostać usunięty w przyszłości z PHP.
maxdb_field_count
maxdb::field_count
(PECL maxdb >= 1.0)
maxdb_field_count -- maxdb::field_count — Returns the number of columns for the most recent query
Opis
Styl proceduralny
$link
)Styl obiektowy
Returns the number of columns for the most recent query on the connection
represented by the link parameter. This function
can be useful when using the maxdb_store_result()
function to determine if the query should have produced a non-empty result
set or not without knowing the nature of the query.
Zwracane wartości
An integer representing the number of fields in a result set.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
maxdb_report (MAXDB_REPORT_OFF);
$maxdb->query("DROP TABLE friends");
maxdb_report (MAXDB_REPORT_ERROR);
$maxdb->query( "CREATE TABLE friends (id int, name varchar(20))");
$maxdb->query( "INSERT INTO friends VALUES (1,'Hartmut')");
$maxdb->query( "INSERT INTO friends VALUES (2, 'Ulf')");
if ($maxdb->field_count()) {
/* this was a select/show or describe query */
$result = $maxdb->store_result();
/* process resultset */
$row = $result->fetch_row();
/* free resultset */
$result->close();
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
maxdb_report (MAXDB_REPORT_OFF);
maxdb_query($link,"DROP TABLE friends");
maxdb_report (MAXDB_REPORT_ERROR);
maxdb_query($link, "CREATE TABLE friends (id int, name varchar(20))");
maxdb_query($link, "INSERT INTO friends VALUES (1,'Hartmut')");
maxdb_query($link, "INSERT INTO friends VALUES (2, 'Ulf')");
if (maxdb_field_count($link)) {
/* this was a select/show or describe query */
$result = maxdb_store_result($link);
/* process resultset */
$row = maxdb_fetch_row($result);
/* free resultset */
maxdb_free_result($result);
}
/* close connection */
maxdb_close($link);
?>
The above example produces no output.
maxdb_field_seek
maxdb_result::field_seek
(PECL maxdb >= 1.0)
maxdb_field_seek -- maxdb_result::field_seek — Set result pointer to a specified field offset
Opis
Styl proceduralny
$result
, int $fieldnr
)Styl obiektowy
$fieldnr
)Sets the field cursor to the given offset. The next call to maxdb_fetch_field() will retrieve the field definition of the column associated with that offset.
Informacja:
To seek to the beginning of a row, pass an offset value of zero.
Zwracane wartości
maxdb_field_seek() returns previuos value of field cursor.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT name, cno from hotel.customer ORDER BY cno";
if ($result = $maxdb->query($query)) {
/* Get field information for 2nd column */
$result->field_seek(1);
$finfo = $result->fetch_field();
printf("Name: %s\n", $finfo->name);
printf("Table: %s\n", $finfo->table);
printf("max. Len: %d\n", $finfo->max_length);
printf("Flags: %d\n", $finfo->flags);
printf("Type: %d\n\n", $finfo->type);
$result->close();
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT name, cno from hotel.customer ORDER BY cno";
if ($result = maxdb_query($link, $query)) {
/* Get field information for 2nd column */
maxdb_field_seek($result, 1);
$finfo = maxdb_fetch_field($result);
printf("Name: %s\n", $finfo->name);
printf("Table: %s\n", $finfo->table);
printf("max. Len: %d\n", $finfo->max_length);
printf("Flags: %d\n", $finfo->flags);
printf("Type: %d\n\n", $finfo->type);
maxdb_free_result($result);
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Name: NAME Table: max. Len: 10 Flags: -1 Type: 2
maxdb_field_tell
maxdb_result::current_field
(PECL maxdb >= 1.0)
maxdb_field_tell -- maxdb_result::current_field — Get current field offset of a result pointer
Opis
Styl proceduralny
$result
)Styl obiektowy
Returns the position of the field cursor used for the last maxdb_fetch_field() call. This value can be used as an argument to maxdb_field_seek().
Zwracane wartości
Returns current offset of field cursor.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT name, cno from hotel.customer ORDER BY cno";
if ($result = $maxdb->query($query)) {
/* Get field information for all columns */
while ($finfo = $result->fetch_field()) {
/* get fieldpointer offset */
$currentfield = $result->current_field;
printf("Column %d:\n", $currentfield);
printf("Name: %s\n", $finfo->name);
printf("Table: %s\n", $finfo->table);
printf("max. Len: %d\n", $finfo->max_length);
printf("Flags: %d\n", $finfo->flags);
printf("Type: %d\n\n", $finfo->type);
}
$result->close();
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT name, cno from hotel.customer ORDER BY cno";
if ($result = maxdb_query($link, $query)) {
/* Get field information for all fields */
while ($finfo = maxdb_fetch_field($result)) {
/* get fieldpointer offset */
$currentfield = maxdb_field_tell($result);
printf("Column %d:\n", $currentfield);
printf("Name: %s\n", $finfo->name);
printf("Table: %s\n", $finfo->table);
printf("max. Len: %d\n", $finfo->max_length);
printf("Flags: %d\n", $finfo->flags);
printf("Type: %d\n\n", $finfo->type);
}
maxdb_free_result($result);
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Column 1: Name: NAME Table: max. Len: 10 Flags: -1 Type: 2 Column 2: Name: CNO Table: max. Len: 4 Flags: -1 Type: 0
Zobacz też:
- maxdb_fetch_field() - Returns the next field in the result set
- maxdb_field_seek() - Set result pointer to a specified field offset
maxdb_free_result
maxdb_result::free
(PECL maxdb >= 1.0)
maxdb_free_result -- maxdb_result::free — Frees the memory associated with a result
Opis
Styl proceduralny
$result
)Styl obiektowy
The maxdb_free_result() function frees the memory
associated with the result represented by the
result parameter, which was allocated by
maxdb_query(), maxdb_store_result()
or maxdb_use_result().
Informacja:
You should always free your result with maxdb_free_result(), when your result resource is not needed anymore.
Zwracane wartości
This function doesn't return any value.
Zobacz też:
- maxdb_query() - Performs a query on the database
- maxdb_stmt_store_result() - Transfers a result set from a prepared statement
- maxdb_store_result() - Transfers a result set from the last query
- maxdb_use_result() - Initiate a result set retrieval
maxdb_get_client_info
(PECL maxdb >= 1.0)
maxdb_get_client_info — Returns the MaxDB client version as a string
Opis
The maxdb_get_client_info() function is used to return a string representing the client version being used in the MaxDB extension.
Zwracane wartości
A string that represents the MaxDB client library version
Przykłady
Przykład #1 maxdb_get_client_info
<?php
/* We don't need a connection to determine
the version of MaxDB client library */
printf("Client library version: %s\n", maxdb_get_client_info());
?>
Powyższy przykład wyświetli coś podobnego do:
Client library version: libSQLDBC <...>
Zobacz też:
- maxdb_get_client_version() - Get MaxDB client info
- maxdb_get_server_info() - Returns the version of the MaxDB server
- maxdb_get_server_version() - Returns the version of the MaxDB server as an integer
maxdb_get_client_version
(PECL maxdb >= 1.0)
maxdb_get_client_version — Get MaxDB client info
Opis
Returns client version number as an integer.
Zwracane wartości
A number that represents the MaxDB client library version in format: main_version*10000 + minor_version *100 + sub_version. For example, 7.5.0 is returned as 70500.
This is useful to quickly determine the version of the client library to know if some capability exists.
Przykłady
Przykład #1 maxdb_get_client_version
<?php
/* We don't need a connection to determine
the version of MaxDB client library */
printf("Client library version: %d\n", maxdb_get_client_version());
?>
Powyższy przykład wyświetli coś podobnego do:
Client library version: 7.<...>
Zobacz też:
- maxdb_get_client_info() - Returns the MaxDB client version as a string
- maxdb_get_server_info() - Returns the version of the MaxDB server
- maxdb_get_server_version() - Returns the version of the MaxDB server as an integer
maxdb_get_host_info
maxdb::get_host_info
(PECL maxdb >= 1.0)
maxdb_get_host_info -- maxdb::get_host_info — Returns a string representing the type of connection used
Opis
Styl proceduralny
$link
)Styl obiektowy
The maxdb_get_host_info() function returns a string
describing the connection represented by the link
parameter is using.
Zwracane wartości
A character string representing the server hostname and the connection type.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* print host information */
printf("Host info: %s\n", $maxdb->host_info);
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* print host information */
printf("Host info: %s\n", maxdb_get_host_info($link));
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Host info: localhost
Opis
Ta funkcja jest aliasem dla: maxdb_stmt_result_metadata().
Ten alias jest nie zalecany i istnieje tylko dla zachowania kompatybilności wstecznej. Zaleca się nie używanie tego aliasu, jako że może on zostać usunięty w przyszłości z PHP.
maxdb_get_proto_info
maxdb::protocol_version
(PECL maxdb >= 1.0)
maxdb_get_proto_info -- maxdb::protocol_version — Returns the version of the MaxDB protocol used
Opis
Styl proceduralny
$link
)Styl obiektowy
Returns an integer representing the MaxDB protocol version used by the
connection represented by the link parameter.
Zwracane wartości
Returns an integer representing the protocol version (constant 10).
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* print protocol version */
printf("Protocol version: %d\n", $maxdb->protocol_version);
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* print protocol version */
printf("Protocol version: %d\n", maxdb_get_proto_info($link));
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Protocol version: 10
maxdb_get_server_info
maxdb::server_info
(PECL maxdb >= 1.0)
maxdb_get_server_info -- maxdb::server_info — Returns the version of the MaxDB server
Opis
Styl proceduralny
$link
)Styl obiektowy
Returns a string representing the version of the MaxDB server that the
MaxDB extension is connected to (represented by the
link parameter).
Zwracane wartości
A character string representing the server version.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* print server version */
printf("Server version: %s\n", $maxdb->server_info);
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* print server version */
printf("Server version: %s\n", maxdb_get_server_info($link));
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Server version: Kernel 7<...>
Zobacz też:
- maxdb_get_client_info() - Returns the MaxDB client version as a string
- maxdb_get_client_version() - Get MaxDB client info
- maxdb_get_server_version() - Returns the version of the MaxDB server as an integer
maxdb_get_server_version
maxdb::server_version
(PECL maxdb >= 1.0)
maxdb_get_server_version -- maxdb::server_version — Returns the version of the MaxDB server as an integer
Opis
Styl proceduralny
$link
)Styl obiektowy
The maxdb_get_server_version() function returns the
version of the server connected to (represented by the
link parameter) as an integer.
The form of this version number is main_version * 10000 + minor_version * 100 + sub_version (i.e. version 7.5.0 is 70500).
Zwracane wartości
An integer representing the server version.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* print server version */
printf("Server version: %d\n", $maxdb->server_version);
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* print server version */
printf("Server version: %d\n", maxdb_get_server_version($link));
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Server version: 7<...>
Zobacz też:
- maxdb_get_client_info() - Returns the MaxDB client version as a string
- maxdb_get_client_version() - Get MaxDB client info
- maxdb_get_server_info() - Returns the version of the MaxDB server
maxdb_info
maxdb::info
(PECL maxdb >= 1.0)
maxdb_info -- maxdb::info — Retrieves information about the most recently executed query
Opis
Styl proceduralny
$link
)Styl obiektowy
The maxdb_info() function returns a string providing information about the last query executed. The nature of this string is provided below:
| Query type | Example result string |
|---|---|
| INSERT INTO...SELECT... | Records: 100 Duplicates: 0 Warnings: 0 |
| INSERT INTO...VALUES (...),(...),(...) | Records: 3 Duplicates: 0 Warnings: 0 |
| LOAD DATA INFILE ... | Records: 1 Deleted: 0 Skipped: 0 Warnings: 0 |
| ALTER TABLE ... | Records: 3 Duplicates: 0 Warnings: 0 |
| UPDATE ... | Rows matched: 40 Changed: 40 Warnings: 0 |
Informacja:
Queries which do not fall into one of the above formats are not supported. In these situations, maxdb_info() will return an empty string.
Zwracane wartości
A character string representing additional information about the most recently executed query.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$maxdb->query("CREATE TABLE temp.t1 LIKE hotel.city");
/* INSERT INTO .. SELECT */
$maxdb->query("INSERT INTO temp.t1 SELECT * FROM hotel.city");
printf("%s\n", $maxdb->info);
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
maxdb_query($link, "CREATE TABLE temp.t1 LIKE hotel.city");
/* INSERT INTO .. SELECT */
maxdb_query($link, "INSERT INTO temp.t1 SELECT * FROM hotel.city");
printf("%s\n", maxdb_info($link));
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Records: 25 Duplicates: 0 Warnings: 0
Zobacz też:
- maxdb_affected_rows() - Gets the number of affected rows in a previous MaxDB operation
- maxdb_warning_count() - Returns the number of warnings from the last query for the given link
- maxdb_num_rows() - Gets the number of rows in a result
maxdb_init
(PECL maxdb >= 1.0)
maxdb_init — Initializes MaxDB and returns an resource for use with maxdb_real_connect
Opis
Allocates or initializes a MaxDB resource suitable for maxdb_options() and maxdb_real_connect().
Informacja:
Any subsequent calls to any maxdb function (except maxdb_options()) will fail until maxdb_real_connect() was called.
Zwracane wartości
Returns an resource.
Zobacz też:
- maxdb_options() - Set options
- maxdb_close() - Closes a previously opened database connection
- maxdb_real_connect() - Opens a connection to a MaxDB server
- maxdb_connect() - Open a new connection to the MaxDB server
maxdb_insert_id
maxdb::insert_id
(PECL maxdb >= 1.0)
maxdb_insert_id -- maxdb::insert_id — Returns the auto generated id used in the last query
Opis
Styl proceduralny
Styl obiektowy
The maxdb_insert_id() function returns the ID generated by a query on a table with a column having the DEFAULT SERIAL attribute. If the last query wasn't an INSERT or UPDATE statement or if the modified table does not have a column with the DEFAULT SERIAL attribute, this function will return zero.
Zwracane wartości
The value of the DEFAULT SERIAL field that was updated by the previous query. Returns zero if there was no previous query on the connection or if the query did not update an DEFAULT_SERIAL value.
Informacja:
If the number is greater than maximal int value, maxdb_insert_id() will return a string.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
maxdb_report (MAXDB_REPORT_OFF);
$maxdb->query("DROP TABLE mycity");
maxdb_report (MAXDB_REPORT_ERROR);
$maxdb->query("CREATE TABLE mycity LIKE hotel.city");
$maxdb->query("ALTER TABLE mycity ADD id FIXED(11) DEFAULT SERIAL");
$query = "INSERT INTO mycity (zip,name,state) VALUES ('12203','Albany' ,'NY')";
$maxdb->query($query);
printf ("New Record has id %d.\n", $maxdb->insert_id);
/* drop table */
$maxdb->query("DROP TABLE mycity");
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
maxdb_report (MAXDB_REPORT_OFF);
maxdb_query($link,"DROP TABLE mycity");
maxdb_report (MAXDB_REPORT_ERROR);
maxdb_query($link, "CREATE TABLE mycity LIKE hotel.city");
maxdb_query($link, "ALTER TABLE mycity ADD id FIXED(11) DEFAULT SERIAL");
$query = "INSERT INTO mycity (zip,name,state) VALUES ('12203','Albany' ,'NY')";
maxdb_query($link, $query);
printf ("New Record has id %d.\n", maxdb_insert_id($link));
/* drop table */
maxdb_query($link, "DROP TABLE mycity");
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
New Record has id 1.
maxdb_kill
maxdb::kill
(PECL maxdb >= 1.0)
maxdb_kill -- maxdb::kill — Disconnects from a MaxDB server
Opis
Styl proceduralny
$link
, int $processid
)Styl obiektowy
$processid
)
This function is used to disconnect from a MaxDB server specified
by the processid parameter.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* determine our thread id */
$thread_id = $maxdb->thread_id;
/* Kill connection */
$maxdb->kill($thread_id);
/* This should produce an error */
if (!$maxdb->query("CREATE TABLE myCity LIKE City")) {
printf("Error: %s\n", $maxdb->error);
exit;
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* determine our thread id */
$thread_id = maxdb_thread_id($link);
/* Kill connection */
maxdb_kill($link, $thread_id);
/* This should produce an error */
if (!maxdb_query($link, "CREATE TABLE myCity LIKE City")) {
printf("Error: %s\n", maxdb_error($link));
exit;
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Error: Session not connected
maxdb_master_query
(PECL maxdb >= 1.0)
maxdb_master_query — Enforce execution of a query on the master in a master/slave setup
Opis
$link
, string $query
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
maxdb_more_results
maxdb::more_results
(PECL maxdb >= 1.0)
maxdb_more_results -- maxdb::more_results — Check if there any more query results from a multi query
Opis
$link
)maxdb_more_results() indicates if one or more result sets are available from a previous call to maxdb_multi_query().
Zwracane wartości
Always FALSE.
Przykłady
See maxdb_multi_query().
Zobacz też:
- maxdb_multi_query() - Performs a query on the database
- maxdb_next_result() - Prepare next result from multi_query
- maxdb_store_result() - Transfers a result set from the last query
- maxdb_use_result() - Initiate a result set retrieval
maxdb_multi_query
maxdb::multi_query
(PECL maxdb >= 1.0)
maxdb_multi_query -- maxdb::multi_query — Performs a query on the database
Opis
Styl proceduralny
$link
, string $query
)Styl obiektowy
$query
)The maxdb_multi_query() works like the function maxdb_query(). Multiple queries are not yet supported.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT * FROM dual";
/* execute multi query */
if ($maxdb->multi_query($query)) {
do {
/* store first result set */
if ($result = $maxdb->store_result()) {
while ($row = $result->fetch_row()) {
printf("%s\n", $row[0]);
}
$result->close();
}
/* print divider */
if ($maxdb->more_results()) {
printf("-----------------\n");
}
} while ($maxdb->next_result());
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT * FROM dual";
/* execute multi query */
if (maxdb_multi_query($link, $query)) {
do {
/* store first result set */
if ($result = maxdb_store_result($link)) {
while ($row = maxdb_fetch_row($result)) {
printf("%s\n", $row[0]);
}
maxdb_free_result($result);
}
/* print divider */
if (maxdb_more_results($link)) {
printf("-----------------\n");
}
} while (maxdb_next_result($link));
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
a
Zobacz też:
- maxdb_use_result() - Initiate a result set retrieval
- maxdb_store_result() - Transfers a result set from the last query
- maxdb_next_result() - Prepare next result from multi_query
- maxdb_more_results() - Check if there any more query results from a multi query
maxdb_next_result
maxdb::next_result
(PECL maxdb >= 1.0)
maxdb_next_result -- maxdb::next_result — Prepare next result from multi_query
Opis
$link
)
Since multiple queries are not yet supported, maxdb_next_result()
returns always FALSE.
Zwracane wartości
Returns FALSE.
Zobacz też:
- maxdb_multi_query() - Performs a query on the database
- maxdb_more_results() - Check if there any more query results from a multi query
- maxdb_store_result() - Transfers a result set from the last query
- maxdb_use_result() - Initiate a result set retrieval
maxdb_num_fields
maxdb_result::field_count
(PECL maxdb >= 1.0)
maxdb_num_fields -- maxdb_result::field_count — Get the number of fields in a result
Opis
Styl proceduralny
$result
)Styl obiektowy
maxdb_num_fields() returns the number of fields from specified result set.
Zwracane wartości
The number of fields from a result set
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
if ($result = $maxdb->query("SELECT * FROM hotel.city ORDER BY zip")) {
/* determine number of fields in result set */
$field_cnt = $result->field_count;
printf("Result set has %d fields.\n", $field_cnt);
/* close result set */
$result->close();
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
if ($result = maxdb_query($link, "SELECT * FROM hotel.city ORDER BY zip")) {
/* determine number of fields in result set */
$field_cnt = maxdb_num_fields($result);
printf("Result set has %d fields.\n", $field_cnt);
/* close result set */
maxdb_free_result($result);
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Result set has 3 fields.
maxdb_num_rows
maxdb::num_rows
(PECL maxdb >= 1.0)
maxdb_num_rows -- maxdb::num_rows — Gets the number of rows in a result
Opis
Styl proceduralny
$result
)Styl obiektowy
Returns the number of rows in the result set.
The use of maxdb_num_rows() depends on whether you use buffered or unbuffered result sets. In case you use unbuffered resultsets maxdb_num_rows() will not correct the correct number of rows until all the rows in the result have been retrieved.
Zwracane wartości
Returns number of rows in the result set.
Informacja:
If the number of rows is greater than maximal int value, the number will be returned as a string.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
if ($result = $maxdb->query("SELECT cno, name FROM hotel.customer ORDER BY name")) {
/* determine number of rows result set */
$row_cnt = $result->num_rows;
printf("Result set has %d rows.\n", $row_cnt);
/* close result set */
$result->close();
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
if ($result = maxdb_query($link, "SELECT cno, name FROM hotel.customer ORDER BY name")) {
/* determine number of rows result set */
$row_cnt = maxdb_num_rows($result);
printf("Result set has %d rows.\n", $row_cnt);
/* close result set */
maxdb_free_result($result);
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Result set has 15 rows.
Zobacz też:
- maxdb_affected_rows() - Gets the number of affected rows in a previous MaxDB operation
- maxdb_store_result() - Transfers a result set from the last query
- maxdb_use_result() - Initiate a result set retrieval
- maxdb_query() - Performs a query on the database
maxdb_options
maxdb::options
(PECL maxdb >= 1.0)
maxdb_options -- maxdb::options — Set options
Opis
Styl proceduralny
Styl obiektowy
maxdb_options() can be used to set extra connect options and affect behavior for a connection.
This function may be called multiple times to set several options.
maxdb_options() should be called after maxdb_init() and before maxdb_real_connect().
The parameter option is the option that you want to set,
the value is the value for the option. For detailed
description of the options see » http://maxdb.sap.com/documentation/
The parameter option can be one of the following values:
| Name | Description |
|---|---|
MAXDB_COMPNAME |
The component name used to initialise the SQLDBC runtime environment. |
MAXDB_APPLICATION |
The application to be connected to the database. |
MAXDB_APPVERSION |
The version of the application. |
MAXDB_SQLMODE |
The SQL mode. |
MAXDB_UNICODE |
TRUE, if the connection is an unicode (UCS2) client or FALSE, if not. |
MAXDB_TIMEOUT |
The maximum allowed time of inactivity after which the connection to the database is closed by the system. |
MAXDB_ISOLATIONLEVEL |
Specifies whether and how shared locks and exclusive locks are implicitly requested or released. |
MAXDB_PACKETCOUNT |
The number of different request packets used for the connection. |
MAXDB_STATEMENTCACHESIZE |
The number of prepared statements to be cached for the connection for re-use. |
MAXDB_CURSORPREFIX |
The prefix to use for result tables that are automatically named. |
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
See maxdb_real_connect().
Zobacz też:
- maxdb_init() - Initializes MaxDB and returns an resource for use with maxdb_real_connect
- maxdb_real_connect() - Opens a connection to a MaxDB server
Opis
Ta funkcja jest aliasem dla: maxdb_stmt_param_count().
Ten alias jest nie zalecany i istnieje tylko dla zachowania kompatybilności wstecznej. Zaleca się nie używanie tego aliasu, jako że może on zostać usunięty w przyszłości z PHP.
maxdb_ping
maxdb::ping
(PECL maxdb >= 1.0)
maxdb_ping -- maxdb::ping — Pings a server connection, or tries to reconnect if the connection has gone down
Opis
Styl proceduralny
$link
)Styl obiektowy
Checks whether the connection to the server is working. If it has gone down, and global option maxdb.reconnect is enabled an automatic reconnection is attempted.
This function can be used by clients that remain idle for a long while, to check whether the server has closed the connection and reconnect if necessary.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* check if server is alive */
if ($maxdb->ping()) {
printf ("Our connection is ok!\n");
} else {
printf ("Error: %s\n", $maxdb->error);
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* check if server is alive */
if (maxdb_ping($link)) {
printf ("Our connection is ok!\n");
} else {
printf ("Error: %s\n", maxdb_error($link));
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Our connection is ok!
maxdb_prepare
maxdb::prepare
(PECL maxdb >= 1.0)
maxdb_prepare -- maxdb::prepare — Prepare an SQL statement for execution
Opis
Styl proceduralny
$link
, string $query
)Styl obiektowy
$query
)maxdb_prepare() prepares the SQL query pointed to by the null-terminated string query, and returns a statement handle to be used for further operations on the statement. The query must consist of a single SQL statement.
Informacja:
You should not add a terminating semicolon or \g to the statement.
The parameter query can include one or more parameter markers
in the SQL statement by embedding question mark (?) characters
at the appropriate positions.
Informacja:
The markers are legal only in certain places in SQL statements. For example, they are allowed in the VALUES() list of an INSERT statement (to specify column values for a row), or in a comparison with a column in a WHERE clause to specify a comparison value.
However, they are not allowed for identifiers (such as table or column names), in the select list that names the columns to be returned by a SELECT statement), or to specify both operands of a binary operator such as the = equal sign. The latter restriction is necessary because it would be impossible to determine the parameter type. In general, parameters are legal only in Data Manipulation Languange (DML) statements, and not in Data Defination Language (DDL) statements.
The parameter markers must be bound to application variables using maxdb_stmt_bind_param() and/or maxdb_stmt_bind_result() before executing the statement or fetching rows.
Zwracane wartości
maxdb_prepare() returns a statement resource or FALSE if an error occured.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$city = "Rosemont";
/* create a prepared statement */
if ($stmt = $maxdb->prepare("SELECT state FROM hotel.city WHERE name=?")) {
/* bind parameters for markers */
$stmt->bind_param("s", $city);
/* execute query */
$stmt->execute();
/* bind result variables */
$stmt->bind_result($district);
/* fetch value */
$stmt->fetch();
printf("%s is in district %s\n", $city, $district);
/* close statement */
$stmt->close();
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$city = "Rosemont";
/* create a prepared statement */
if ($stmt = maxdb_prepare($link, "SELECT state FROM hotel.city WHERE name=?")) {
/* bind parameters for markers */
maxdb_stmt_bind_param($stmt, "s", $city);
/* execute query */
maxdb_stmt_execute($stmt);
/* bind result variables */
maxdb_stmt_bind_result($stmt, $district);
/* fetch value */
maxdb_stmt_fetch($stmt);
printf("%s is in district %s\n", $city, $district);
/* close statement */
maxdb_stmt_close($stmt);
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Rosemont is in district IL
Zobacz też:
- maxdb_stmt_execute() - Executes a prepared Query
- maxdb_stmt_fetch() - Fetch results from a prepared statement into the bound variables
- maxdb_stmt_bind_param() - Binds variables to a prepared statement as parameters
- maxdb_stmt_bind_result() - Binds variables to a prepared statement for result storage
- maxdb_stmt_close() - Closes a prepared statement
maxdb_query
maxdb::query
(PECL maxdb >= 1.0)
maxdb_query -- maxdb::query — Performs a query on the database
Opis
Styl proceduralny
Styl obiektowy
The maxdb_query() function is used to simplify the
act of performing a query against the database represented by the
link parameter.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu. For SELECT, SHOW, DESCRIBE or
EXPLAIN maxdb_query() will return
a result resource.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* Create table doesn't return a resultset */
if ($maxdb->query("CREATE TABLE temp.mycity LIKE hotel.city") === TRUE) {
printf("Table mycity successfully created.\n");
}
/* Select queries return a resultset */
if ($result = $maxdb->query("SELECT name FROM hotel.city")) {
printf("Select returned %d rows.\n", $result->num_rows);
/* free result set */
$result->close();
}
/* If we have to retrieve large amount of data we use MAXDB_USE_RESULT */
if ($result = $maxdb->query("SELECT * FROM hotel.city", MAXDB_USE_RESULT)) {
$result->close();
}
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* Create table doesn't return a resultset */
if (maxdb_query($link, "CREATE TABLE temp.mycity LIKE hotel.city") === TRUE) {
printf("Table mycity successfully created.\n");
}
/* Select queries return a resultset */
if ($result = maxdb_query($link, "SELECT name FROM hotel.city")) {
printf("Select returned %d rows.\n", maxdb_num_rows($result));
/* free result set */
maxdb_free_result($result);
}
/* If we have to retrieve large amount of data we use MAXDB_USE_RESULT */
if ($result = maxdb_query($link, "SELECT * FROM hotel.city", MAXDB_USE_RESULT)) {
maxdb_free_result($result);
}
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Table mycity successfully created. Select returned 25 rows.
Zobacz też:
- maxdb_real_query() - Execute an SQL query
- maxdb_multi_query() - Performs a query on the database
- maxdb_free_result() - Frees the memory associated with a result
maxdb_real_connect
maxdb::real_connect
(PECL maxdb >= 1.0)
maxdb_real_connect -- maxdb::real_connect — Opens a connection to a MaxDB server
Opis
Styl proceduralny
$link
[, string $hostname
[, string $username
[, string $passwd
[, string $dbname
[, int $port = 0
[, string $socket
]]]]]] )Styl obiektowy
$hostname
[, string $username
[, string $passwd
[, string $dbname
[, int $port = 0
[, string $socket
]]]]]] )
maxdb_real_connect() attempts to establish a
connection to a MaxDB database engine running on
hostname.
This function differs from maxdb_connect():
-
maxdb_real_connect() needs a valid resource which has to be created by function maxdb_init()
-
With function maxdb_options() you can set various options for connection.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Styl obiektowy
<?php
/* create a connection object which is not connected */
$maxdb = maxdb_init();
/* set connection options */
$maxdb->options(MAXDB_UNICODE, "FALSE");
$maxdb->options(MAXDB_TIMEOUT, 5);
/* connect to server */
$maxdb->real_connect('localhost', 'MONA', 'RED', 'DEMODB');
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
printf ("Connection: %s\n.", $maxdb->host_info);
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
/* create a connection object which is not connected */
$link = maxdb_init();
/* set connection options */
maxdb_options($link, MAXDB_UNICODE, "FALSE");
maxdb_options($link, MAXDB_TIMEOUT, 5);
/* connect to server */
maxdb_real_connect($link, 'localhost', 'MONA', 'RED', 'DEMODB');
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
printf ("Connection: %s\n.", maxdb_get_host_info($link));
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Connection: localhost <...>
Zobacz też:
- maxdb_connect() - Open a new connection to the MaxDB server
- maxdb_init() - Initializes MaxDB and returns an resource for use with maxdb_real_connect
- maxdb_options() - Set options
- maxdb_ssl_set() - Used for establishing secure connections using SSL
- maxdb_close() - Closes a previously opened database connection
maxdb_real_escape_string
maxdb::real_escape_string
(PECL maxdb >= 1.0)
maxdb_real_escape_string -- maxdb::real_escape_string — Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection
Opis
Styl proceduralny
$link
, string $escapestr
)Styl obiektowy
$escapestr
)This function is used to create a legal SQL string that you can use in an SQL statement. The string escapestr is encoded to an escaped SQL string, taking into account the current character set of the connection.
Characters encoded are ', ".
Zwracane wartości
Returns an escaped string.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$maxdb->query("CREATE TABLE temp.mycity LIKE hotel.city");
$city = "'s Hertogenbosch";
/* this query will fail, cause we didn't escape $city */
if (!$maxdb->query("INSERT into temp.mycity VALUES ('11111','$city','NY')")) {
printf("Error: %s\n", $maxdb->sqlstate);
}
$city = $maxdb->real_escape_string($city);
/* this query with escaped $city will work */
if ($maxdb->query("INSERT into temp.mycity VALUES ('22222','$city','NY')")) {
printf("%d Row inserted.\n", $maxdb->affected_rows);
}
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
maxdb_query($link, "CREATE TABLE temp.mycity LIKE hotel.city");
$city = "'s Hertogenbosch";
/* this query will fail, cause we didn't escape $city */
if (!maxdb_query($link, "INSERT into temp.mycity VALUES ('11111','$city','NY')")) {
printf("Error: %s\n", maxdb_sqlstate($link));
}
$city = maxdb_real_escape_string($link, $city);
/* this query with escaped $city will work */
if (maxdb_query($link, "INSERT into temp.mycity VALUES ('22222','$city','NY')")) {
printf("%d Row inserted.\n", maxdb_affected_rows($link));
}
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Warning: maxdb_query(): -5016 POS(43) Missing delimiter: ) <...> Error: 42000 1 Row inserted.
Zobacz też:
- maxdb_character_set_name() - Returns the default character set for the database connection
maxdb_real_query
maxdb::real_query
(PECL maxdb >= 1.0)
maxdb_real_query -- maxdb::real_query — Execute an SQL query
Opis
Styl proceduralny
$link
, string $query
)Styl obiektowy
$query
)The maxdb_real_query() is functionally identical with the maxdb_query().
Informacja:
In order to determine if a given query should return a result set or not, see maxdb_field_count().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- maxdb_query() - Performs a query on the database
- maxdb_store_result() - Transfers a result set from the last query
- maxdb_use_result() - Initiate a result set retrieval
maxdb_report
(PECL maxdb 1.0)
maxdb_report — Enables or disables internal report functions
Opis
$flags
)Parametry
-
flags -
One of the MAXDB_REPORT_XXX constants.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Styl proceduralny
<?php
/* activate reporting */
maxdb_report(MAXDB_REPORT_ERROR);
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* this query should report an error */
$result = maxdb_query($link,"SELECT Name FROM Nonexistingtable WHERE population > 50000");
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Warning: maxdb_query(): -4004 POS(18) Unknown table name:NONEXISTINGTABLE <...>
maxdb_rollback
maxdb::rollback
(PECL maxdb >= 1.0)
maxdb_rollback -- maxdb::rollback — Rolls back current transaction
Opis
Styl proceduralny
$link
)Styl obiektowy
Rollbacks the current transaction for the database specified by the
link parameter.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* disable autocommit */
$maxdb->autocommit(FALSE);
$maxdb->query("CREATE TABLE temp.mycity LIKE hotel.city");
$maxdb->query("INSERT INTO temp.mycity SELECT * FROM hotel.city");
/* commit insert */
$maxdb->commit();
/* delete all rows */
$maxdb->query("DELETE FROM temp.mycity");
if ($result = $maxdb->query("SELECT COUNT(*) FROM temp.mycity")) {
$row = $result->fetch_row();
printf("%d rows in table mycity.\n", $row[0]);
/* Free result */
$result->close();
}
/* Rollback */
$maxdb->rollback();
if ($result = $maxdb->query("SELECT COUNT(*) FROM temp.mycity")) {
$row = $result->fetch_row();
printf("%d rows in table mycity (after rollback).\n", $row[0]);
/* Free result */
$result->close();
}
/* Drop table myCity */
$maxdb->query("DROP TABLE temp.mycity");
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* disable autocommit */
maxdb_autocommit($link, FALSE);
maxdb_query($link, "CREATE TABLE temp.mycity LIKE hotel.city");
maxdb_query($link, "INSERT INTO temp.mycity SELECT * FROM hotel.city");
/* commit insert */
maxdb_commit($link);
/* delete all rows */
maxdb_query($link, "DELETE FROM temp.mycity");
if ($result = maxdb_query($link, "SELECT COUNT(*) FROM temp.mycity")) {
$row = maxdb_fetch_row($result);
printf("%d rows in table mycity.\n", $row[0]);
/* Free result */
maxdb_free_result($result);
}
/* Rollback */
maxdb_rollback($link);
if ($result = maxdb_query($link, "SELECT COUNT(*) FROM temp.mycity")) {
$row = maxdb_fetch_row($result);
printf("%d rows in table mycity (after rollback).\n", $row[0]);
/* Free result */
maxdb_free_result($result);
}
/* Drop table myCity */
maxdb_query($link, "DROP TABLE temp.mycity");
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
0 rows in table mycity. 25 rows in table mycity (after rollback).
Zobacz też:
- maxdb_commit() - Commits the current transaction
- maxdb_autocommit() - Turns on or off auto-commiting database modifications
maxdb_rpl_parse_enabled
(PECL maxdb >= 1.0)
maxdb_rpl_parse_enabled — Check if RPL parse is enabled
Opis
$link
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
maxdb_rpl_probe
(PECL maxdb >= 1.0)
maxdb_rpl_probe — RPL probe
Opis
$link
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
maxdb_rpl_query_type
maxdb::rpl_query_type
(PECL maxdb >= 1.0)
maxdb_rpl_query_type -- maxdb::rpl_query_type — Returns RPL query type
Opis
Styl proceduralny
$link
)Styl obiektowy
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
maxdb_select_db
maxdb::select_db
(PECL maxdb >= 1.0)
maxdb_select_db -- maxdb::select_db — Selects the default database for database queries
Opis
$link
, string $dbname
)
The maxdb_select_db() function selects the default
database (specified by the dbname parameter) to be
used when performing queries against the database connection
represented by the link parameter.
Informacja:
This function should only be used to change the default database for the connection. You can select the default database with 4th parameter in maxdb_connect().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* return name of current default database */
if ($result = $maxdb->query("SELECT SERVERDB FROM USERS WHERE USERNAME='MONA'")) {
$row = $result->fetch_row();
printf("Default database is %s.\n", $row[0]);
$result->close();
}
/* change db to non existing db */
$maxdb->select_db("XXXXXXXX");
/* return name of current default database */
if ($result = $maxdb->query("SELECT SERVERDB FROM USERS WHERE USERNAME='MONA'")) {
$row = $result->fetch_row();
printf("Default database is %s.\n", $row[0]);
$result->close();
}
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* return name of current default database */
if ($result = maxdb_query($link, "SELECT SERVERDB FROM USERS WHERE USERNAME='MONA'")) {
$row = maxdb_fetch_row($result);
printf("Default database is %s.\n", $row[0]);
maxdb_free_result($result);
}
/* change db to non existing db */
maxdb_select_db($link, "XXXXXXXX");
/* return name of current default database */
if ($result = maxdb_query($link, "SELECT SERVERDB FROM USERS WHERE USERNAME='MONA'")) {
$row = maxdb_fetch_row($result);
printf("Default database is %s.\n", $row[0]);
maxdb_free_result($result);
}
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Default database is <...>. Warning: maxdb_select_db(): -10709 Connection failed (RTE:database not running) <...> Warning: maxdb_query(): -10821 Session not connected [] <...> Warning: maxdb_close(): -10821 Session not connected [] <...>
Zobacz też:
- maxdb_connect() - Open a new connection to the MaxDB server
- maxdb_real_connect() - Opens a connection to a MaxDB server
maxdb_send_long_data
(PECL maxdb >= 1.0)
maxdb_send_long_data — Alias dla maxdb_stmt_send_long_data()
Opis
Ta funkcja jest aliasem dla: maxdb_stmt_send_long_data().
Ten alias jest nie zalecany i istnieje tylko dla zachowania kompatybilności wstecznej. Zaleca się nie używanie tego aliasu, jako że może on zostać usunięty w przyszłości z PHP.
maxdb_send_query
maxdb::send_query
(PECL maxdb >= 1.0)
maxdb_send_query -- maxdb::send_query — Send the query and return
Opis
Styl proceduralny
$link
, string $query
)Styl obiektowy
$query
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
maxdb_server_end
(PECL maxdb >= 1.0)
maxdb_server_end — Shut down the embedded server
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
maxdb_server_init
(PECL maxdb >= 1.0)
maxdb_server_init — Initialize embedded server
Opis
$server
[, array $groups
]] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Opis
Ta funkcja jest aliasem dla: maxdb_options().
maxdb_sqlstate
maxdb::sqlstate
(PECL maxdb >= 1.0)
maxdb_sqlstate -- maxdb::sqlstate — Returns the SQLSTATE error from previous MaxDB operation
Opis
Styl proceduralny
$link
)Styl obiektowy
Returns a string containing the SQLSTATE error code for the last error. The error code consists of five characters. '00000' means no error. The values are specified by ANSI SQL and ODBC.
Informacja:
Note that not all MaxDB errors are yet mapped to SQLSTATE's. The value HY000 (general error) is used for unmapped errors.
Zwracane wartości
Returns a string containing the SQLSTATE error code for the last error. The error code consists of five characters. '00000' means no error.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* Table City already exists, so we should get an error */
if (!$maxdb->query("CREATE TABLE hotel.city (ID INT, Name VARCHAR(30))")) {
printf("Error - SQLSTATE %s.\n", $maxdb->sqlstate);
}
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* Table City already exists, so we should get an error */
if (!maxdb_query($link, "CREATE TABLE hotel.city (ID INT, Name VARCHAR(30))")) {
printf("Error - SQLSTATE %s.\n", maxdb_sqlstate($link));
}
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Warning: maxdb_query(): -6000 POS(20) Duplicate table name:CITY [I6000] <...> Error - SQLSTATE I6000.
Zobacz też:
- maxdb_errno() - Returns the error code for the most recent function call
- maxdb_error() - Returns a string description of the last error
maxdb_ssl_set
maxdb::ssl_set
(PECL maxdb >= 1.0)
maxdb_ssl_set -- maxdb::ssl_set — Used for establishing secure connections using SSL
Opis
Styl proceduralny
$link
, string $key
, string $cert
, string $ca
, string $capath
, string $cipher
)Styl obiektowy
$key
, string $cert
, string $ca
, string $capath
, string $cipher
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
maxdb_stat
maxdb::stat
(PECL maxdb >= 1.0)
maxdb_stat -- maxdb::stat — Gets the current system status
Opis
Styl proceduralny
$link
)Styl obiektowy
maxdb_stat() returns a string containing several information about the MaxDB server running.
Zwracane wartości
A string describing the server status. FALSE if an error occurred.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
printf ("System status: %s\n", $maxdb->stat());
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
printf("System status: %s\n", maxdb_stat($link));
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
System status: Kernel 7<...>
maxdb_stmt_affected_rows
maxdb_stmt::affected_rows
(PECL maxdb >= 1.0)
maxdb_stmt_affected_rows -- maxdb_stmt::affected_rows — Returns the total number of rows changed, deleted, or inserted by the last executed statement
Opis
Styl proceduralny
$stmt
)Styl obiektowy
maxdb_stmt_affected_rows() returns the number of rows affected by INSERT, UPDATE, or DELETE query. If the last query was invalid or the number of rows can not determined, this function will return -1.
Zwracane wartości
An integer greater than zero indicates the number of rows affected or retrieved. Zero indicates that no records where updated for an UPDATE/DELETE statement, no rows matched the WHERE clause in the query or that no query has yet been executed. -1 indicates that the query has returned an error or the number of rows can not determined.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* create temp table */
$maxdb->query("CREATE TABLE temp.mycity LIKE hotel.city");
$query = "INSERT INTO temp.mycity SELECT * FROM hotel.city WHERE state LIKE ?";
/* prepare statement */
if ($stmt = $maxdb->prepare($query)) {
/* Bind variable for placeholder */
$code = 'N%';
$stmt->bind_param("s", $code);
/* execute statement */
$stmt->execute();
printf("rows inserted: %d\n", $stmt->affected_rows);
/* close statement */
$stmt->close();
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* create temp table */
maxdb_query($link, "CREATE TABLE temp.mycity LIKE hotel.city");
$query = "INSERT INTO temp.mycity SELECT * FROM hotel.city WHERE state LIKE ?";
/* prepare statement */
if ($stmt = maxdb_prepare($link, $query)) {
/* Bind variable for placeholder */
$code = 'N%';
maxdb_stmt_bind_param($stmt, "s", $code);
/* execute statement */
maxdb_stmt_execute($stmt);
printf("rows inserted: %d\n", maxdb_stmt_affected_rows($stmt));
/* close statement */
maxdb_stmt_close($stmt);
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
rows inserted: 4
Zobacz też:
- maxdb_stmt_num_rows() - Return the number of rows in statements result set
- maxdb_prepare() - Prepare an SQL statement for execution
maxdb_stmt_bind_param
maxdb_stmt::bind_param
(PECL maxdb >= 1.0)
maxdb_stmt_bind_param -- maxdb_stmt::bind_param — Binds variables to a prepared statement as parameters
Opis
Styl proceduralny
Styl obiektowy
Styl proceduralny (extended syntax):
$stmt
, string $types
, array &$var
)Styl obiektowy (extended syntax):
$types
, array &$var
)
maxdb_stmt_bind_param() is used to bind variables for the
parameter markers in the SQL statement that was passed to
maxdb_prepare().
The string types contains one or more characters which specify
the types for the corresponding bind variables.
The extended syntax of maxdb_stmt_bind_param() allows to give the parameters as an array instead of a variable list of PHP variables to the function. If the array variable has not been used before calling maxdb_stmt_bind_param(), it has to be initialized as an emtpy array. See the examples how to use maxdb_stmt_bind_param() with extended syntax.
Variables for SELECT INTO SQL statements can also be bound using maxdb_stmt_bind_param(). Parameters for database procedures can be bound using maxdb_stmt_bind_param(). See the examples how to use maxdb_stmt_bind_param() in this cases.
If a variable bound as INTO variable to an SQL statement was used before, the content of this variable is overwritten by the data of the SELECT INTO statement. A reference to this variable will be invalid after a call to maxdb_stmt_bind_param().
For INOUT parameters of database procedures the content of the bound INOUT variable is overwritten by the output value of the database procedure. A reference to this variable will be invalid after a call to maxdb_stmt_bind_param().
| Character | Description |
|---|---|
| i | corresponding variable has type integer |
| d | corresponding variable has type double |
| s | corresponding variable has type string |
| b | corresponding variable is a blob and will be sent in packages |
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb('localhost', 'MONA', 'RED', 'DEMODB');
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$maxdb->query ("CREATE TABLE temp.mycity LIKE hotel.city");
$maxdb->query ("INSERT INTO temp.mycity SELECT * FROM hotel.city");
$stmt = $maxdb->prepare("INSERT INTO temp.mycity VALUES (?, ?, ?)");
$stmt->bind_param('sss', $zip, $name, $state);
$zip = '11111';
$name = 'Georgetown';
$state = 'NY';
/* execute prepared statement */
$stmt->execute();
printf("%d Row inserted.\n", $stmt->affected_rows);
/* close statement and connection */
$stmt->close();
/* Clean up table CountryLanguage */
$maxdb->query("DELETE FROM temp.mycity WHERE name='Georgetown'");
printf("%d Row deleted.\n", $maxdb->affected_rows);
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (!$link) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
maxdb_query ($link, "CREATE TABLE temp.mycity LIKE hotel.city");
maxdb_query ($link, "INSERT INTO temp.mycity SELECT * FROM hotel.city");
$stmt = maxdb_prepare($link, "INSERT INTO temp.mycity VALUES (?, ?, ?)");
maxdb_stmt_bind_param($stmt, 'sss', $zip, $name, $state);
$zip = '11111';
$name = 'Georgetown';
$state = 'NY';
/* execute prepared statement */
maxdb_stmt_execute($stmt);
printf("%d Row inserted.\n", maxdb_stmt_affected_rows($stmt));
/* close statement and connection */
maxdb_stmt_close($stmt);
/* Clean up table CountryLanguage */
maxdb_query($link, "DELETE FROM temp.mycity WHERE name='Georgetown'");
printf("%d Row deleted.\n", maxdb_affected_rows($link));
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
1 Row inserted. 1 Row deleted.
Przykład #3 Styl proceduralny (SELECT INTO)
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (!$link) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* Performing SQL query */
$stmt = maxdb_prepare ($link, "SELECT price INTO ? FROM hotel.room where hno = ? and type = ?");
if (!$stmt) {
printf ("Prepare failed: %s\n", maxdb_error($link));
}
$hno = "50";
$rtype = "suite";
maxdb_stmt_bind_param($stmt, 'dss', $price, $hno, $rtype);
maxdb_stmt_execute($stmt);
printf ("%f\n", $price);
maxdb_stmt_close ($stmt);
?>
Powyższy przykład wyświetli coś podobnego do:
21.600000
Przykład #4 Styl proceduralny (DB procedure)
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (!$link) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
maxdb_report (MAXDB_REPORT_OFF);
maxdb_query($link,"DROP DBPROC test_proc");
maxdb_report (MAXDB_REPORT_ERROR);
$query = "create dbproc test_proc (INOUT e_text char(72)) AS select * from SYSDBA.DUAL; fetch into :e_text;";
maxdb_query($link, $query);
/* Performing SQL query */
$stmt = maxdb_prepare ($link, "CALL test_proc (?)");
if (!$stmt) {
printf ("Prepare failed: %s\n", maxdb_error($link));
}
maxdb_stmt_bind_param($stmt, 's', $result);
maxdb_stmt_execute($stmt);
printf ("%s\n", $result);
maxdb_stmt_close ($stmt);
?>
Powyższy przykład wyświetli coś podobnego do:
a
Przykład #5 Styl obiektowy (extended syntax)
<?php
$maxdb = new maxdb('localhost', 'MONA', 'RED', 'DEMODB');
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$maxdb->query ("CREATE TABLE temp.mycity LIKE hotel.city");
$maxdb->query ("INSERT INTO temp.mycity SELECT * FROM hotel.city");
$stmt = $maxdb->prepare("INSERT INTO temp.mycity VALUES (?, ?, ?)");
$arr = array();
$stmt->bind_param('iss', $arr);
$arr[0] = 11111;
$arr[1] = 'Georgetown';
$arr[2] = 'NY';
/* execute prepared statement */
$stmt->execute();
printf("%d Row inserted.\n", maxdb_stmt_affected_rows($stmt));
$arr[0] = 22222;
$arr[1] = 'New Orleans';
$arr[2] = 'LA';
/* execute prepared statement */
$stmt->execute();
printf("%d Row inserted.\n", $stmt->affected_rows);
/* close statement and connection */
$stmt->close();
$result = $maxdb->query("SELECT * from temp.mycity WHERE zip = '11111' OR zip = '22222'");
if ($result) {
while ($row = $result->fetch_row()) {
printf ("%s %s %s\n", $row[0], $row[1], $row[2]);
}
}
/* Clean up table CountryLanguage */
$maxdb->query("DELETE FROM temp.mycity WHERE name='Georgetown'");
$maxdb->query("DELETE FROM temp.mycity WHERE name='New Orleans'");
printf("%d Rows deleted.\n", $maxdb->affected_rows);
/* close connection */
$maxdb->close();
?>
Powyższy przykład wyświetli coś podobnego do:
1 Row inserted. 1 Row inserted. 11111 Georgetown NY 22222 New Orleans LA 2 Rows deleted.
Zobacz też:
- maxdb_stmt_bind_result() - Binds variables to a prepared statement for result storage
- maxdb_stmt_execute() - Executes a prepared Query
- maxdb_stmt_fetch() - Fetch results from a prepared statement into the bound variables
- maxdb_prepare() - Prepare an SQL statement for execution
- maxdb_stmt_send_long_data() - Send data in blocks
- maxdb_stmt_errno() - Returns the error code for the most recent statement call
- maxdb_stmt_error() - Returns a string description for last statement error
maxdb_stmt_bind_result
maxdb_stmt::bind_result
(PECL maxdb >= 1.0)
maxdb_stmt_bind_result -- maxdb_stmt::bind_result — Binds variables to a prepared statement for result storage
Opis
Styl proceduralny
Styl obiektowy
maxdb_stmt_bind_result() is used to associate (bind) columns in the result
set to variables. When maxdb_stmt_fetch() is called to fetch data, the MaxDB
client/server protocol places the data for the bound columns into the specified variables
var1, ....
Informacja:
Note that all columns must be bound prior to calling maxdb_stmt_fetch(). Depending on column types bound variables can silently change to the corresponding PHP type.
A column can be bound or rebound at any time, even after a result set has been partially retrieved. The new binding takes effect the next time maxdb_stmt_fetch() is called.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* prepare statement */
if ($stmt = $maxdb->prepare("SELECT zip, name FROM hotel.city ORDER BY name")) {
$stmt->execute();
/* bind variables to prepared statement */
$stmt->bind_result($col1, $col2);
/* fetch values */
while ($stmt->fetch()) {
printf("%s %s\n", $col1, $col2);
}
/* close statement */
$stmt->close();
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (!$link) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* prepare statement */
if ($stmt = maxdb_prepare($link, "SELECT zip, name FROM hotel.city ORDER BY name")) {
maxdb_stmt_execute($stmt);
/* bind variables to prepared statement */
maxdb_stmt_bind_result($stmt, $col1, $col2);
/* fetch values */
while (maxdb_stmt_fetch($stmt)) {
printf("%s %s\n", $col1, $col2);
}
/* close statement */
maxdb_stmt_close($stmt);
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
12203 Albany 60601 Chicago 60615 Chicago 45211 Cincinnati 33575 Clearwater 75243 Dallas 32018 Daytona Beach 33441 Deerfield Beach 48226 Detroit 90029 Hollywood 92714 Irvine 90804 Long Beach 11788 Long Island 90018 Los Angeles 70112 New Orleans 10019 New York 10580 New York 92262 Palm Springs 97213 Portland 60018 Rosemont 95054 Santa Clara 20903 Silver Spring 20005 Washington 20019 Washington 20037 Washington
Zobacz też:
- maxdb_stmt_bind_param() - Binds variables to a prepared statement as parameters
- maxdb_stmt_execute() - Executes a prepared Query
- maxdb_stmt_fetch() - Fetch results from a prepared statement into the bound variables
- maxdb_prepare() - Prepare an SQL statement for execution
- maxdb_stmt_prepare() - Prepare an SQL statement for execution
- maxdb_stmt_init() - Initializes a statement and returns an resource for use with maxdb_stmt_prepare
- maxdb_stmt_errno() - Returns the error code for the most recent statement call
- maxdb_stmt_error() - Returns a string description for last statement error
maxdb_stmt_close_long_data
maxdb_stmt::close_long_data
(PECL maxdb 1.0)
maxdb_stmt_close_long_data -- maxdb_stmt::close_long_data — Ends a sequence of maxdb_stmt_send_long_data()
Opis
Styl proceduralny
$stmt
, int $param_nr
)Styl obiektowy
This function has to be called after a sequence of maxdb_stmt_send_long_data(), that was started after maxdb_execute().
param_nr indicates which parameter to associate the
end of data with.
Parameters are numbered beginning with 0.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- maxdb_prepare() - Prepare an SQL statement for execution
- maxdb_stmt_bind_param() - Binds variables to a prepared statement as parameters
maxdb_stmt_close
maxdb_stmt::close
(PECL maxdb >= 1.0)
maxdb_stmt_close -- maxdb_stmt::close — Closes a prepared statement
Opis
Styl proceduralny
$stmt
)Styl obiektowy
Closes a prepared statement. maxdb_stmt_close() also deallocates the
statement handle pointed to by stmt.
If the current statement has pending or unread results, this function cancels them so that
the next query can be executed.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
maxdb_stmt_data_seek
maxdb_stmt::data_seek
(PECL maxdb >= 1.0)
maxdb_stmt_data_seek -- maxdb_stmt::data_seek — Seeks to an arbitray row in statement result set
Opis
Styl proceduralny
$statement
, int $offset
)Styl obiektowy
$offset
)
The maxdb_stmt_data_seek() function seeks to an arbitrary result pointer
specified by the offset in the statement result set represented by
statement. The offset parameter must be between
zero and the total number of rows minus one (0..maxdb_stmt_num_rows() - 1).
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Styl obiektowy
<?php
/* Open a connection */
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT name, zip FROM hotel.city ORDER BY name";
if ($stmt = $maxdb->prepare($query)) {
/* execute query */
$stmt->execute();
/* bind result variables */
$stmt->bind_result($name, $code);
/* store result */
$stmt->store_result();
/* seek to row no. 5 */
$stmt->data_seek(5);
/* fetch values */
$stmt->fetch();
printf ("City: %s Zip: %s\n", $name, $code);
/* close statement */
$stmt->close();
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
/* Open a connection */
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT name, zip FROM hotel.city ORDER BY name";
if ($stmt = maxdb_prepare($link, $query)) {
/* execute query */
maxdb_stmt_execute($stmt);
/* bind result variables */
maxdb_stmt_bind_result($stmt, $name, $code);
/* store result */
maxdb_stmt_store_result($stmt);
/* seek to row no. 5 */
maxdb_stmt_data_seek($stmt, 5);
/* fetch values */
maxdb_stmt_fetch($stmt);
printf ("City: %s Zip: %s\n", $name, $code);
/* close statement */
maxdb_stmt_close($stmt);
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
City: Dallas Zip: 75243
maxdb_stmt_errno
maxdb_stmt::errno
(PECL maxdb >= 1.0)
maxdb_stmt_errno -- maxdb_stmt::errno — Returns the error code for the most recent statement call
Opis
Styl proceduralny
$stmt
)Styl obiektowy
For the statement specified by stmt, maxdb_stmt_errno() returns the error code for the most recently invoked statement function that can succeed or fail.
Informacja:
For possible error codes see documentation of SQLDBC: » http://maxdb.sap.com/documentation/.
Zwracane wartości
An error code value. Zero means no error occurred.
Przykłady
Przykład #1 Styl obiektowy
<?php
/* Open a connection */
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$maxdb->query("CREATE TABLE temp.mycity LIKE hotel.city");
$maxdb->query("INSERT INTO temp.mycity SELECT * FROM hotel.city");
$query = "SELECT name, zip FROM temp.mycity ORDER BY name";
if ($stmt = $maxdb->prepare($query)) {
/* drop table */
$maxdb->query("DROP TABLE temp.mycity");
/* execute query */
$stmt->execute();
printf("Error: %d.\n", $stmt->errno);
/* close statement */
$stmt->close();
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
/* Open a connection */
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
maxdb_query($link, "CREATE TABLE temp.mycity LIKE hotel.city");
maxdb_query($link, "INSERT INTO temp.mycity SELECT * FROM hotel.city");
$query = "SELECT name, zip FROM temp.mycity ORDER BY name";
if ($stmt = maxdb_prepare($link, $query)) {
/* drop table */
maxdb_query($link, "DROP TABLE temp.mycity");
/* execute query */
maxdb_stmt_execute($stmt);
printf("Error: %d.\n", maxdb_stmt_errno($stmt));
/* close statement */
maxdb_stmt_close($stmt);
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Warning: maxdb_stmt_execute(): -4004 POS(23) Unknown table name:MYCITY [42000] <...> Error: -4004.
Zobacz też:
- maxdb_stmt_error() - Returns a string description for last statement error
- maxdb_stmt_sqlstate() - Returns SQLSTATE error from previous statement operation
maxdb_stmt_error
maxdb_stmt::error
(PECL maxdb >= 1.0)
maxdb_stmt_error -- maxdb_stmt::error — Returns a string description for last statement error
Opis
Styl proceduralny
$stmt
)Styl obiektowy
For the statement specified by stmt, maxdb_stmt_error() returns a containing the error message for the most recently invoked statement function that can succeed or fail.
Zwracane wartości
A string that describes the error. An empty string if no error occurred.
Przykłady
Przykład #1 Styl obiektowy
<?php
/* Open a connection */
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$maxdb->query("CREATE TABLE temp.mycity LIKE hotel.city");
$maxdb->query("INSERT INTO temp.mycity SELECT * FROM hotel.city");
$query = "SELECT name, zip FROM temp.mycity ORDER BY name";
if ($stmt = $maxdb->prepare($query)) {
/* drop table */
$maxdb->query("DROP TABLE temp.mycity");
/* execute query */
$stmt->execute();
printf("Error: %s.\n", $stmt->error);
/* close statement */
$stmt->close();
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
/* Open a connection */
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
maxdb_query($link, "CREATE TABLE temp.mycity LIKE hotel.city");
maxdb_query($link, "INSERT INTO temp.mycity SELECT * FROM hotel.city");
$query = "SELECT name, zip FROM temp.mycity ORDER BY name";
if ($stmt = maxdb_prepare($link, $query)) {
/* drop table */
maxdb_query($link, "DROP TABLE temp.mycity");
/* execute query */
maxdb_stmt_execute($stmt);
printf("Error: %s.\n", maxdb_stmt_error($stmt));
/* close statement */
maxdb_stmt_close($stmt);
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Warning: maxdb_stmt_execute(): -4004 POS(23) Unknown table name:MYCITY [42000] <...> Error: POS(23) Unknown table name:MYCITY.
Zobacz też:
- maxdb_stmt_errno() - Returns the error code for the most recent statement call
- maxdb_stmt_sqlstate() - Returns SQLSTATE error from previous statement operation
maxdb_stmt_execute
maxdb_stmt::execute
(PECL maxdb >= 1.0)
maxdb_stmt_execute -- maxdb_stmt::execute — Executes a prepared Query
Opis
Styl proceduralny
$stmt
)Styl obiektowy
The maxdb_stmt_execute() function executes a query that has been previously
prepared using the maxdb_prepare() function represented by the
stmt resource. When executed any parameter markers which exist will
automatically be replaced with the appropiate data.
If the statement is UPDATE, DELETE, or INSERT, the total number of affected rows can be determined by using the maxdb_stmt_affected_rows() function. Likewise, if the query yields a result set the maxdb_fetch() function is used.
Informacja:
When using maxdb_stmt_execute(), the maxdb_fetch() function must be used to fetch the data prior to preforming any additional queries.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$maxdb->query("CREATE TABLE temp.mycity LIKE hotel.city");
/* Prepare an insert statement */
$query = "INSERT INTO temp.mycity (zip, name, state) VALUES (?,?,?)";
$stmt = $maxdb->prepare($query);
$stmt->bind_param("sss", $val1, $val2, $val3);
$val1 = '11111';
$val2 = 'Georgetown';
$val3 = 'NY';
/* Execute the statement */
$stmt->execute();
$val1 = '22222';
$val2 = 'Hubbatown';
$val3 = 'CA';
/* Execute the statement */
$stmt->execute();
/* close statement */
$stmt->close();
/* retrieve all rows from myCity */
$query = "SELECT zip, name, state FROM temp.mycity";
if ($result = $maxdb->query($query)) {
while ($row = $result->fetch_row()) {
printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
}
/* free result set */
$result->close();
}
/* remove table */
$maxdb->query("DROP TABLE temp.mycity");
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
maxdb_query($link, "CREATE TABLE temp.mycity LIKE hotel.city");
/* Prepare an insert statement */
$query = "INSERT INTO temp.mycity (zip, name, state) VALUES (?,?,?)";
$stmt = maxdb_prepare($link, $query);
maxdb_stmt_bind_param($stmt, "sss", $val1, $val2, $val3);
$val1 = '11111';
$val2 = 'Georgetown';
$val3 = 'NY';
/* Execute the statement */
maxdb_stmt_execute($stmt);
$val1 = '22222';
$val2 = 'Hubbatown';
$val3 = 'CA';
/* Execute the statement */
maxdb_stmt_execute($stmt);
/* close statement */
maxdb_stmt_close($stmt);
/* retrieve all rows from myCity */
$query = "SELECT zip, name, state FROM temp.mycity";
if ($result = maxdb_query($link, $query)) {
while ($row = maxdb_fetch_row($result)) {
printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
}
/* free result set */
maxdb_free_result($result);
}
/* remove table */
maxdb_query($link, "DROP TABLE temp.mycity");
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
11111 (Georgetown,NY) 22222 (Hubbatown,CA)
Zobacz też:
- maxdb_prepare() - Prepare an SQL statement for execution
- maxdb_stmt_bind_param() - Binds variables to a prepared statement as parameters
maxdb_stmt_fetch
maxdb_stmt::fetch
(PECL maxdb >= 1.0)
maxdb_stmt_fetch -- maxdb_stmt::fetch — Fetch results from a prepared statement into the bound variables
Opis
Styl proceduralny
$stmt
)Styl obiektowy
maxdb_stmt_fetch() returns row data using the variables bound by maxdb_stmt_bind_result().
Informacja:
Note that all columns must be bound by the application before calling maxdb_stmt_fetch().
Zwracane wartości
| Value | Description |
|---|---|
TRUE |
Success. Data has been fetched |
FALSE |
Error occured |
NULL |
No more rows/data exists |
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT zip, name FROM hotel.city ORDER by name";
if ($stmt = $maxdb->prepare($query)) {
/* execute statement */
$stmt->execute();
/* bind result variables */
$stmt->bind_result($name, $code);
/* fetch values */
while ($stmt->fetch()) {
printf ("%s (%s)\n", $name, $code);
}
/* close statement */
$stmt->close();
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT zip, name FROM hotel.city ORDER by name";
if ($stmt = maxdb_prepare($link, $query)) {
/* execute statement */
maxdb_stmt_execute($stmt);
/* bind result variables */
maxdb_stmt_bind_result($stmt, $name, $code);
/* fetch values */
while (maxdb_stmt_fetch($stmt)) {
printf ("%s (%s)\n", $name, $code);
}
/* close statement */
maxdb_stmt_close($stmt);
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
12203 (Albany) 60601 (Chicago) 60615 (Chicago) 45211 (Cincinnati) 33575 (Clearwater) 75243 (Dallas) 32018 (Daytona Beach) 33441 (Deerfield Beach) 48226 (Detroit) 90029 (Hollywood) 92714 (Irvine) 90804 (Long Beach) 11788 (Long Island) 90018 (Los Angeles) 70112 (New Orleans) 10019 (New York) 10580 (New York) 92262 (Palm Springs) 97213 (Portland) 60018 (Rosemont) 95054 (Santa Clara) 20903 (Silver Spring) 20005 (Washington) 20019 (Washington) 20037 (Washington)
Zobacz też:
- maxdb_prepare() - Prepare an SQL statement for execution
- maxdb_stmt_errno() - Returns the error code for the most recent statement call
- maxdb_stmt_error() - Returns a string description for last statement error
- maxdb_stmt_bind_result() - Binds variables to a prepared statement for result storage
maxdb_stmt_free_result
maxdb_stmt::free_result
(PECL maxdb >= 1.0)
maxdb_stmt_free_result -- maxdb_stmt::free_result — Frees stored result memory for the given statement handle
Opis
Styl proceduralny
$stmt
)Styl obiektowy
The maxdb_stmt_free_result() function frees the result memory
associated with the statement represented by the
stmt parameter, which was allocated by
maxdb_stmt_store_result().
Zwracane wartości
This function doesn't return any value.
maxdb_stmt_init
maxdb::stmt_init
(PECL maxdb >= 1.0)
maxdb_stmt_init -- maxdb::stmt_init — Initializes a statement and returns an resource for use with maxdb_stmt_prepare
Opis
Styl proceduralny
$link
)Styl obiektowy
Allocates and initializes a statement resource suitable for maxdb_stmt_prepare().
Informacja:
Any subsequent calls to any maxdb_stmt function will fail until maxdb_stmt_prepare() was called.
Zwracane wartości
Returns an resource.
maxdb_stmt_num_rows
maxdb_stmt::num_rows
(PECL maxdb >= 1.0)
maxdb_stmt_num_rows -- maxdb_stmt::num_rows — Return the number of rows in statements result set
Opis
Styl proceduralny
$stmt
)Styl obiektowy
Returns the number of rows in the result set.
Zwracane wartości
An integer representing the number of rows in result set.
Przykłady
Przykład #1 Styl obiektowy
<?php
/* Open a connection */
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT zip, name FROM hotel.city ORDER BY name";
if ($stmt = $maxdb->prepare($query)) {
/* execute query */
$stmt->execute();
/* store result */
$stmt->store_result();
printf("Number of rows: %d.\n", $stmt->num_rows);
/* close statement */
$stmt->close();
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
/* Open a connection */
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT zip, name FROM hotel.city ORDER BY name";
if ($stmt = maxdb_prepare($link, $query)) {
/* execute query */
maxdb_stmt_execute($stmt);
/* store result */
maxdb_stmt_store_result($stmt);
printf("Number of rows: %d.\n", maxdb_stmt_num_rows($stmt));
/* close statement */
maxdb_stmt_close($stmt);
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Number of rows: 25.
Zobacz też:
- maxdb_stmt_affected_rows() - Returns the total number of rows changed, deleted, or inserted by the last executed statement
- maxdb_prepare() - Prepare an SQL statement for execution
- maxdb_stmt_store_result() - Transfers a result set from a prepared statement
maxdb_stmt_param_count
maxdb_stmt::param_count
(PECL maxdb >= 1.0)
maxdb_stmt_param_count -- maxdb_stmt::param_count — Returns the number of parameter for the given statement
Opis
Styl proceduralny
$stmt
)Styl obiektowy
maxdb_stmt_param_count() returns the number of parameter markers present in the prepared statement.
Zwracane wartości
returns an integer representing the number of parameters.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
if ($stmt = $maxdb->prepare("SELECT name FROM hotel.city WHERE name=? OR state=?")) {
$marker = $stmt->param_count;
printf("Statement has %d markers.\n", $marker);
/* close statement */
$stmt->close();
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
if ($stmt = maxdb_prepare($link, "SELECT name FROM hotel.city WHERE name=? OR state=?")) {
$marker = maxdb_stmt_param_count($stmt);
printf("Statement has %d markers.\n", $marker);
/* close statement */
maxdb_stmt_close($stmt);
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Statement has 2 markers.
maxdb_stmt_prepare
maxdb_stmt::prepare
(PECL maxdb >= 1.0)
maxdb_stmt_prepare -- maxdb_stmt::prepare — Prepare an SQL statement for execution
Opis
Styl proceduralny
$stmt
, string $query
)Styl obiektowy
maxdb_stmt_prepare() prepares the SQL query pointed to by the null-terminated string query. The statement resource has to be allocated by maxdb_stmt_init(). The query must consist of a single SQL statement.
Informacja:
You should not add a terminating semicolon or \g to the statement.
The parameter query can include one or more parameter markers
in the SQL statement by embedding question mark (?) characters
at the appropriate positions.
Informacja:
The markers are legal only in certain places in SQL statements. For example, they are allowed in the VALUES() list of an INSERT statement (to specify column values for a row), or in a comparison with a column in a WHERE clause to specify a comparison value.
However, they are not allowed for identifiers (such as table or column names), in the select list that names the columns to be returned by a SELECT statement), or to specify both operands of a binary operator such as the = equal sign. The latter restriction is necessary because it would be impossible to determine the parameter type. In general, parameters are legal only in Data Manipulation Languange (DML) statements, and not in Data Defination Language (DDL) statements.
The parameter markers must be bound to application variables using maxdb_stmt_bind_param() and/or maxdb_stmt_bind_result() before executing the statement or fetching rows.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$city = "Portland";
/* create a prepared statement */
$stmt = $maxdb->stmt_init();
if ($stmt->prepare("SELECT state FROM hotel.city WHERE name=?")) {
/* bind parameters for markers */
$stmt->bind_param("s", $city);
/* execute query */
$stmt->execute();
/* bind result variables */
$stmt->bind_result($district);
/* fetch value */
$stmt->fetch();
printf("%s is in district %s\n", $city, $district);
/* close statement */
$stmt->close();
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$city = "Portland";
/* create a prepared statement */
$stmt = maxdb_stmt_init($link);
if (maxdb_stmt_prepare($stmt, "SELECT state FROM hotel.city WHERE name=?")) {
/* bind parameters for markers */
maxdb_stmt_bind_param($stmt, "s", $city);
/* execute query */
maxdb_stmt_execute($stmt);
/* bind result variables */
maxdb_stmt_bind_result($stmt, $district);
/* fetch value */
maxdb_stmt_fetch($stmt);
printf("%s is in district %s\n", $city, $district);
/* close statement */
maxdb_stmt_close($stmt);
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Portland is in district OR
Zobacz też:
- maxdb_stmt_init() - Initializes a statement and returns an resource for use with maxdb_stmt_prepare
- maxdb_stmt_execute() - Executes a prepared Query
- maxdb_stmt_fetch() - Fetch results from a prepared statement into the bound variables
- maxdb_stmt_bind_param() - Binds variables to a prepared statement as parameters
- maxdb_stmt_bind_result() - Binds variables to a prepared statement for result storage
- maxdb_stmt_close() - Closes a prepared statement
maxdb_stmt_reset
maxdb_stmt::reset
(PECL maxdb >= 1.0)
maxdb_stmt_reset -- maxdb_stmt::reset — Resets a prepared statement
Opis
Styl proceduralny
$stmt
)Styl obiektowy
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
maxdb_stmt_result_metadata
maxdb_stmt::result_metadata
(PECL maxdb >= 1.0)
maxdb_stmt_result_metadata -- maxdb_stmt::result_metadata — Returns result set metadata from a prepared statement
Opis
Styl proceduralny
$stmt
)Styl obiektowy
If a statement passed to maxdb_prepare() is one that produces a result set, maxdb_stmt_result_metadata() returns the result resource that can be used to process the meta information such as total number of fields and individual field information.
Informacja:
This result set pointer can be passed as an argument to any of the field-based functions that process result set metadata, such as:
The result set structure should be freed when you are done with it, which you can do by passing it to maxdb_free_result()
Informacja:
The result set returned by maxdb_stmt_result_metadata() contains only metadata. It does not contain any row results. The rows are obtained by using the statement handle with maxdb_fetch().
Zwracane wartości
maxdb_stmt_result_metadata() returns a result resource or FALSE if
an error occured.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
$maxdb->query("CREATE TABLE temp.friends (id int, name varchar(20))");
$maxdb->query("INSERT INTO temp.friends VALUES (1,'Hartmut')");
$maxdb->query("INSERT INTO temp.friends VALUES (2, 'Ulf')");
$stmt = $maxdb->prepare("SELECT id, name FROM temp.friends");
$stmt->execute();
/* get resultset for metadata */
$result = $stmt->result_metadata();
/* retrieve field information from metadata result set */
$field = $result->fetch_field();
printf("Fieldname: %s\n", $field->name);
/* close resultset */
$result->close();
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
maxdb_query($link, "CREATE TABLE temp.friends (id int, name varchar(20))");
maxdb_query($link, "INSERT INTO temp.friends VALUES (1,'Hartmut')");
maxdb_query($link, "INSERT INTO temp.friends VALUES (2, 'Ulf')");
$stmt = maxdb_prepare($link, "SELECT id, name FROM temp.friends");
maxdb_stmt_execute($stmt);
/* get resultset for metadata */
$result = maxdb_stmt_result_metadata($stmt);
/* retrieve field information from metadata result set */
$field = maxdb_fetch_field($result);
printf("Fieldname: %s\n", $field->name);
/* close resultset */
maxdb_free_result($result);
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Fieldname: ID
Zobacz też:
- maxdb_prepare() - Prepare an SQL statement for execution
- maxdb_free_result() - Frees the memory associated with a result
maxdb_stmt_send_long_data
maxdb_stmt::send_long_data
(PECL maxdb 1.0)
maxdb_stmt_send_long_data -- maxdb_stmt::send_long_data — Send data in blocks
Opis
Styl proceduralny
$stmt
, int $param_nr
, string $data
)Styl obiektowy
$param_nr
, string $data
)Allows to send parameter data to the server in pieces (or chunks). This function can be called multiple times to send the parts of a character or binary data value for a column, which must be one of the TEXT or BLOB datatypes.
param_nr indicates which parameter to associate the data with.
Parameters are numbered beginning with 0.
data is a string containing data to be sent.
Informacja:
For efficiency reasons, this function should be used after calling maxdb_execute(). In this case, the data is not stored on the client side. The end of the sequence must end with a call to maxdb_stmt_close_long_data().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- maxdb_prepare() - Prepare an SQL statement for execution
- maxdb_stmt_bind_param() - Binds variables to a prepared statement as parameters
maxdb_stmt_sqlstate
(PECL maxdb >= 1.0)
maxdb_stmt_sqlstate — Returns SQLSTATE error from previous statement operation
Opis
$stmt
)Returns a string containing the SQLSTATE error code for the most recently invoked prepared statement function that can succeed or fail. The error code consists of five characters. '00000' means no error. The values are specified by ANSI SQL and ODBC.
Informacja:
Note that not all MaxDB errors are yet mapped to SQLSTATE's. The value HY000 (general error) is used for unmapped errors.
Zwracane wartości
Returns a string containing the SQLSTATE error code for the last error. The error code consists of five characters. '00000' means no error.
Przykłady
Przykład #1 Styl obiektowy
<?php
/* Open a connection */
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$maxdb->query("CREATE TABLE temp.mycity LIKE hotel.city");
$maxdb->query("INSERT INTO temp.mycity SELECT * FROM hotel.city");
$query = "SELECT name, zip FROM temp.mycity ORDER BY name";
if ($stmt = $maxdb->prepare($query)) {
/* drop table */
$maxdb->query("DROP TABLE temp.mycity");
/* execute query */
$stmt->execute();
printf("Error: %s.\n", $stmt->sqlstate);
/* close statement */
$stmt->close();
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
/* Open a connection */
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
maxdb_query($link, "CREATE TABLE temp.mycity LIKE hotel.city");
maxdb_query($link, "INSERT INTO temp.mycity SELECT * FROM hotel.city");
$query = "SELECT name, zip FROM temp.mycity ORDER BY name";
if ($stmt = maxdb_prepare($link, $query)) {
/* drop table */
maxdb_query($link, "DROP TABLE temp.mycity");
/* execute query */
maxdb_stmt_execute($stmt);
printf("Error: %s.\n", maxdb_stmt_sqlstate($stmt));
/* close statement */
maxdb_stmt_close($stmt);
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Warning: maxdb_stmt_execute(): -4004 POS(23) Unknown table name:MYCITY [42000] <...> Error: 42000.
Zobacz też:
- maxdb_stmt_errno() - Returns the error code for the most recent statement call
- maxdb_stmt_error() - Returns a string description for last statement error
maxdb_stmt_store_result
maxdb::store_result
(PECL maxdb >= 1.0)
maxdb_stmt_store_result -- maxdb::store_result — Transfers a result set from a prepared statement
Opis
Styl proceduralny
$stmt
)Styl obiektowy
maxdb_stmt_store_result() has no functionally effect and should not be used for retrieving data from MaxDB server.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Styl obiektowy
<?php
/* Open a connection */
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT name, zip FROM hotel.city ORDER BY name";
if ($stmt = $maxdb->prepare($query)) {
/* execute query */
$stmt->execute();
/* store result */
$stmt->store_result();
printf("Number of rows: %d.\n", $stmt->num_rows);
/* free result */
$stmt->free_result();
/* close statement */
$stmt->close();
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
/* Open a connection */
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT name, zip FROM hotel.city ORDER BY name";
if ($stmt = maxdb_prepare($link, $query)) {
/* execute query */
maxdb_stmt_execute($stmt);
/* store result */
maxdb_stmt_store_result($stmt);
printf("Number of rows: %d.\n", maxdb_stmt_num_rows($stmt));
/* free result */
maxdb_stmt_free_result($stmt);
/* close statement */
maxdb_stmt_close($stmt);
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Number of rows: 25.
Zobacz też:
- maxdb_prepare() - Prepare an SQL statement for execution
- maxdb_stmt_result_metadata() - Returns result set metadata from a prepared statement
- maxdb_fetch() - Alias dla maxdb_stmt_fetch
maxdb_store_result
maxdb::store_result
(PECL maxdb >= 1.0)
maxdb_store_result -- maxdb::store_result — Transfers a result set from the last query
Opis
Styl proceduralny
$link
)Styl obiektowy
This function has no functionally effect.
Zwracane wartości
Returns a result resource or FALSE if an error occurred.
Przykłady
See maxdb_multi_query().
Zobacz też:
- maxdb_real_query() - Execute an SQL query
- maxdb_use_result() - Initiate a result set retrieval
maxdb_thread_id
maxdb::thread_id
(PECL maxdb >= 1.0)
maxdb_thread_id -- maxdb::thread_id — Returns the thread ID for the current connection
Opis
Styl proceduralny
$link
)Styl obiektowy
The maxdb_thread_id() function returns the thread ID for the current connection which can then be killed using the maxdb_kill() function. If the connection is lost and you reconnect with maxdb_ping(), the thread ID will be other. Therefore you should get the thread ID only when you need it.
Informacja:
The thread ID is assigned on a connection-by-connection basis. Hence, if the connection is broken and then re-established a new thread ID will be assigned.
Zwracane wartości
maxdb_thread_id() returns the Thread ID for the current connection.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* determine our thread id */
$thread_id = $maxdb->thread_id;
/* Kill connection */
$maxdb->kill($thread_id);
/* This should produce an error */
if (!$maxdb->query("CREATE TABLE mycity LIKE hotel.city")) {
printf("Error: %s\n", $maxdb->error);
exit;
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* determine our thread id */
$thread_id = maxdb_thread_id($link);
/* Kill connection */
maxdb_kill($link, $thread_id);
/* This should produce an error */
if (!maxdb_query($link, "CREATE TABLE mycity LIKE hotel.city")) {
printf("Error: %s\n", maxdb_error($link));
exit;
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Warning: maxdb_query(): -10821 Session not connected <...> Error: Session not connected
maxdb_thread_safe
(PECL maxdb >= 7.6.06.04)
maxdb_thread_safe — Returns whether thread safety is given or not
Opis
maxdb_thread_safe() indicates whether the client library is compiled as thread-safe.
Zwracane wartości
TRUE if the client library is thread-safe, otherwise FALSE.
maxdb_use_result
maxdb::use_result
(PECL maxdb >= 1.0)
maxdb_use_result -- maxdb::use_result — Initiate a result set retrieval
Opis
Styl proceduralny
$link
)Styl obiektowy
maxdb_use_result() has no effect.
Zwracane wartości
Returns result lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT * FROM DUAL";
/* execute multi query */
if ($maxdb->multi_query($query)) {
do {
/* store first result set */
if ($result = $maxdb->use_result()) {
while ($row = $result->fetch_row()) {
printf("%s\n", $row[0]);
}
$result->close();
}
/* print divider */
if ($maxdb->more_results()) {
printf("-----------------\n");
}
} while ($maxdb->next_result());
}
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$query = "SELECT * FROM DUAL";
/* execute multi query */
if (maxdb_multi_query($link, $query)) {
do {
/* store first result set */
if ($result = maxdb_use_result($link)) {
while ($row = maxdb_fetch_row($result)) {
printf("%s\n", $row[0]);
}
maxdb_free_result($result);
}
/* print divider */
if (maxdb_more_results($link)) {
printf("-----------------\n");
}
} while (maxdb_next_result($link));
}
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
a
Zobacz też:
- maxdb_real_query() - Execute an SQL query
- maxdb_store_result() - Transfers a result set from the last query
maxdb_warning_count
maxdb::warning_count
(PECL maxdb >= 1.0)
maxdb_warning_count -- maxdb::warning_count — Returns the number of warnings from the last query for the given link
Opis
Styl proceduralny
$link
)Styl obiektowy
maxdb_warning_count() returns the number of warnings
from the last query in the connection represented by the
link parameter.
Zwracane wartości
Number of warnings or zero if there are no warnings.
Przykłady
Przykład #1 Styl obiektowy
<?php
$maxdb = new maxdb("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
$maxdb->query("CREATE TABLE temp.mycity LIKE hotel.city");
/* a remarkable city in Wales */
$query = "INSERT INTO temp.mycity (zip, name) VALUES('11111',
'Llanfairpwllgwyngyllgogerychwyrndrobwllllantysiliogogogoch')";
$maxdb->query($query);
printf ("Number of warning: %d\n", $maxdb->warning_count);
/* close connection */
$maxdb->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
maxdb_query($link, "CREATE TABLE temp.mycity LIKE hotel.city");
/* a remarkable long city name in Wales */
$query = "INSERT INTO temp.mycity (zip, name) VALUES('11111',
'Llanfairpwllgwyngyllgogerychwyrndrobwllllantysiliogogogoch')";
maxdb_query($link, $query);
printf ("Number of warning: %d\n", maxdb_warning_count($link));
/* close connection */
maxdb_close($link);
?>
Powyższy przykład wyświetli coś podobnego do:
Warning: maxdb_query(): -8004 POS(62) Constant must be compatible with column type and length <...> Number of warning: 0
Zobacz też:
- maxdb_errno() - Returns the error code for the most recent function call
- maxdb_error() - Returns a string description of the last error
- maxdb_sqlstate() - Returns the SQLSTATE error from previous MaxDB operation
Spis treści
- maxdb_affected_rows — Gets the number of affected rows in a previous MaxDB operation
- maxdb_autocommit — Turns on or off auto-commiting database modifications
- maxdb_bind_param — Alias dla maxdb_stmt_bind_param
- maxdb_bind_result — Alias dla maxdb_stmt_bind_result
- maxdb_change_user — Changes the user of the specified database connection
- maxdb_character_set_name — Returns the default character set for the database connection
- maxdb_client_encoding — Alias dla maxdb_character_set_name
- maxdb_close_long_data — Alias dla maxdb_stmt_close_long_data
- maxdb_close — Closes a previously opened database connection
- maxdb_commit — Commits the current transaction
- maxdb_connect_errno — Returns the error code from last connect call
- maxdb_connect_error — Returns a string description of the last connect error
- maxdb_connect — Open a new connection to the MaxDB server
- maxdb_data_seek — Adjusts the result pointer to an arbitary row in the result
- maxdb_debug — Performs debugging operations
- maxdb_disable_reads_from_master — Disable reads from master
- maxdb_disable_rpl_parse — Disable RPL parse
- maxdb_dump_debug_info — Dump debugging information into the log
- maxdb_embedded_connect — Open a connection to an embedded MaxDB server
- maxdb_enable_reads_from_master — Enable reads from master
- maxdb_enable_rpl_parse — Enable RPL parse
- maxdb_errno — Returns the error code for the most recent function call
- maxdb_error — Returns a string description of the last error
- maxdb_escape_string — Alias dla maxdb_real_escape_string
- maxdb_execute — Alias dla maxdb_stmt_execute
- maxdb_fetch_array — Fetch a result row as an associative, a numeric array, or both
- maxdb_fetch_assoc — Fetch a result row as an associative array
- maxdb_fetch_field_direct — Fetch meta-data for a single field
- maxdb_fetch_field — Returns the next field in the result set
- maxdb_fetch_fields — Returns an array of resources representing the fields in a result set
- maxdb_fetch_lengths — Returns the lengths of the columns of the current row in the result set
- maxdb_fetch_object — Returns the current row of a result set as an object
- maxdb_fetch_row — Get a result row as an enumerated array
- maxdb_fetch — Alias dla maxdb_stmt_fetch
- maxdb_field_count — Returns the number of columns for the most recent query
- maxdb_field_seek — Set result pointer to a specified field offset
- maxdb_field_tell — Get current field offset of a result pointer
- maxdb_free_result — Frees the memory associated with a result
- maxdb_get_client_info — Returns the MaxDB client version as a string
- maxdb_get_client_version — Get MaxDB client info
- maxdb_get_host_info — Returns a string representing the type of connection used
- maxdb_get_metadata — Alias dla maxdb_stmt_result_metadata
- maxdb_get_proto_info — Returns the version of the MaxDB protocol used
- maxdb_get_server_info — Returns the version of the MaxDB server
- maxdb_get_server_version — Returns the version of the MaxDB server as an integer
- maxdb_info — Retrieves information about the most recently executed query
- maxdb_init — Initializes MaxDB and returns an resource for use with maxdb_real_connect
- maxdb_insert_id — Returns the auto generated id used in the last query
- maxdb_kill — Disconnects from a MaxDB server
- maxdb_master_query — Enforce execution of a query on the master in a master/slave setup
- maxdb_more_results — Check if there any more query results from a multi query
- maxdb_multi_query — Performs a query on the database
- maxdb_next_result — Prepare next result from multi_query
- maxdb_num_fields — Get the number of fields in a result
- maxdb_num_rows — Gets the number of rows in a result
- maxdb_options — Set options
- maxdb_param_count — Alias dla maxdb_stmt_param_count
- maxdb_ping — Pings a server connection, or tries to reconnect if the connection has gone down
- maxdb_prepare — Prepare an SQL statement for execution
- maxdb_query — Performs a query on the database
- maxdb_real_connect — Opens a connection to a MaxDB server
- maxdb_real_escape_string — Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection
- maxdb_real_query — Execute an SQL query
- maxdb_report — Enables or disables internal report functions
- maxdb_rollback — Rolls back current transaction
- maxdb_rpl_parse_enabled — Check if RPL parse is enabled
- maxdb_rpl_probe — RPL probe
- maxdb_rpl_query_type — Returns RPL query type
- maxdb_select_db — Selects the default database for database queries
- maxdb_send_long_data — Alias dla maxdb_stmt_send_long_data
- maxdb_send_query — Send the query and return
- maxdb_server_end — Shut down the embedded server
- maxdb_server_init — Initialize embedded server
- maxdb_set_opt — Alias dla maxdb_options
- maxdb_sqlstate — Returns the SQLSTATE error from previous MaxDB operation
- maxdb_ssl_set — Used for establishing secure connections using SSL
- maxdb_stat — Gets the current system status
- maxdb_stmt_affected_rows — Returns the total number of rows changed, deleted, or inserted by the last executed statement
- maxdb_stmt_bind_param — Binds variables to a prepared statement as parameters
- maxdb_stmt_bind_result — Binds variables to a prepared statement for result storage
- maxdb_stmt_close_long_data — Ends a sequence of maxdb_stmt_send_long_data
- maxdb_stmt_close — Closes a prepared statement
- maxdb_stmt_data_seek — Seeks to an arbitray row in statement result set
- maxdb_stmt_errno — Returns the error code for the most recent statement call
- maxdb_stmt_error — Returns a string description for last statement error
- maxdb_stmt_execute — Executes a prepared Query
- maxdb_stmt_fetch — Fetch results from a prepared statement into the bound variables
- maxdb_stmt_free_result — Frees stored result memory for the given statement handle
- maxdb_stmt_init — Initializes a statement and returns an resource for use with maxdb_stmt_prepare
- maxdb_stmt_num_rows — Return the number of rows in statements result set
- maxdb_stmt_param_count — Returns the number of parameter for the given statement
- maxdb_stmt_prepare — Prepare an SQL statement for execution
- maxdb_stmt_reset — Resets a prepared statement
- maxdb_stmt_result_metadata — Returns result set metadata from a prepared statement
- maxdb_stmt_send_long_data — Send data in blocks
- maxdb_stmt_sqlstate — Returns SQLSTATE error from previous statement operation
- maxdb_stmt_store_result — Transfers a result set from a prepared statement
- maxdb_store_result — Transfers a result set from the last query
- maxdb_thread_id — Returns the thread ID for the current connection
- maxdb_thread_safe — Returns whether thread safety is given or not
- maxdb_use_result — Initiate a result set retrieval
- maxdb_warning_count — Returns the number of warnings from the last query for the given link
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Przykłady
- MaxDB Funkcje
- maxdb_affected_rows — Gets the number of affected rows in a previous MaxDB operation
- maxdb_autocommit — Turns on or off auto-commiting database modifications
- maxdb_bind_param — Alias dla maxdb_stmt_bind_param
- maxdb_bind_result — Alias dla maxdb_stmt_bind_result
- maxdb_change_user — Changes the user of the specified database connection
- maxdb_character_set_name — Returns the default character set for the database connection
- maxdb_client_encoding — Alias dla maxdb_character_set_name
- maxdb_close_long_data — Alias dla maxdb_stmt_close_long_data
- maxdb_close — Closes a previously opened database connection
- maxdb_commit — Commits the current transaction
- maxdb_connect_errno — Returns the error code from last connect call
- maxdb_connect_error — Returns a string description of the last connect error
- maxdb_connect — Open a new connection to the MaxDB server
- maxdb_data_seek — Adjusts the result pointer to an arbitary row in the result
- maxdb_debug — Performs debugging operations
- maxdb_disable_reads_from_master — Disable reads from master
- maxdb_disable_rpl_parse — Disable RPL parse
- maxdb_dump_debug_info — Dump debugging information into the log
- maxdb_embedded_connect — Open a connection to an embedded MaxDB server
- maxdb_enable_reads_from_master — Enable reads from master
- maxdb_enable_rpl_parse — Enable RPL parse
- maxdb_errno — Returns the error code for the most recent function call
- maxdb_error — Returns a string description of the last error
- maxdb_escape_string — Alias dla maxdb_real_escape_string
- maxdb_execute — Alias dla maxdb_stmt_execute
- maxdb_fetch_array — Fetch a result row as an associative, a numeric array, or both
- maxdb_fetch_assoc — Fetch a result row as an associative array
- maxdb_fetch_field_direct — Fetch meta-data for a single field
- maxdb_fetch_field — Returns the next field in the result set
- maxdb_fetch_fields — Returns an array of resources representing the fields in a result set
- maxdb_fetch_lengths — Returns the lengths of the columns of the current row in the result set
- maxdb_fetch_object — Returns the current row of a result set as an object
- maxdb_fetch_row — Get a result row as an enumerated array
- maxdb_fetch — Alias dla maxdb_stmt_fetch
- maxdb_field_count — Returns the number of columns for the most recent query
- maxdb_field_seek — Set result pointer to a specified field offset
- maxdb_field_tell — Get current field offset of a result pointer
- maxdb_free_result — Frees the memory associated with a result
- maxdb_get_client_info — Returns the MaxDB client version as a string
- maxdb_get_client_version — Get MaxDB client info
- maxdb_get_host_info — Returns a string representing the type of connection used
- maxdb_get_metadata — Alias dla maxdb_stmt_result_metadata
- maxdb_get_proto_info — Returns the version of the MaxDB protocol used
- maxdb_get_server_info — Returns the version of the MaxDB server
- maxdb_get_server_version — Returns the version of the MaxDB server as an integer
- maxdb_info — Retrieves information about the most recently executed query
- maxdb_init — Initializes MaxDB and returns an resource for use with maxdb_real_connect
- maxdb_insert_id — Returns the auto generated id used in the last query
- maxdb_kill — Disconnects from a MaxDB server
- maxdb_master_query — Enforce execution of a query on the master in a master/slave setup
- maxdb_more_results — Check if there any more query results from a multi query
- maxdb_multi_query — Performs a query on the database
- maxdb_next_result — Prepare next result from multi_query
- maxdb_num_fields — Get the number of fields in a result
- maxdb_num_rows — Gets the number of rows in a result
- maxdb_options — Set options
- maxdb_param_count — Alias dla maxdb_stmt_param_count
- maxdb_ping — Pings a server connection, or tries to reconnect if the connection has gone down
- maxdb_prepare — Prepare an SQL statement for execution
- maxdb_query — Performs a query on the database
- maxdb_real_connect — Opens a connection to a MaxDB server
- maxdb_real_escape_string — Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection
- maxdb_real_query — Execute an SQL query
- maxdb_report — Enables or disables internal report functions
- maxdb_rollback — Rolls back current transaction
- maxdb_rpl_parse_enabled — Check if RPL parse is enabled
- maxdb_rpl_probe — RPL probe
- maxdb_rpl_query_type — Returns RPL query type
- maxdb_select_db — Selects the default database for database queries
- maxdb_send_long_data — Alias dla maxdb_stmt_send_long_data
- maxdb_send_query — Send the query and return
- maxdb_server_end — Shut down the embedded server
- maxdb_server_init — Initialize embedded server
- maxdb_set_opt — Alias dla maxdb_options
- maxdb_sqlstate — Returns the SQLSTATE error from previous MaxDB operation
- maxdb_ssl_set — Used for establishing secure connections using SSL
- maxdb_stat — Gets the current system status
- maxdb_stmt_affected_rows — Returns the total number of rows changed, deleted, or inserted by the last executed statement
- maxdb_stmt_bind_param — Binds variables to a prepared statement as parameters
- maxdb_stmt_bind_result — Binds variables to a prepared statement for result storage
- maxdb_stmt_close_long_data — Ends a sequence of maxdb_stmt_send_long_data
- maxdb_stmt_close — Closes a prepared statement
- maxdb_stmt_data_seek — Seeks to an arbitray row in statement result set
- maxdb_stmt_errno — Returns the error code for the most recent statement call
- maxdb_stmt_error — Returns a string description for last statement error
- maxdb_stmt_execute — Executes a prepared Query
- maxdb_stmt_fetch — Fetch results from a prepared statement into the bound variables
- maxdb_stmt_free_result — Frees stored result memory for the given statement handle
- maxdb_stmt_init — Initializes a statement and returns an resource for use with maxdb_stmt_prepare
- maxdb_stmt_num_rows — Return the number of rows in statements result set
- maxdb_stmt_param_count — Returns the number of parameter for the given statement
- maxdb_stmt_prepare — Prepare an SQL statement for execution
- maxdb_stmt_reset — Resets a prepared statement
- maxdb_stmt_result_metadata — Returns result set metadata from a prepared statement
- maxdb_stmt_send_long_data — Send data in blocks
- maxdb_stmt_sqlstate — Returns SQLSTATE error from previous statement operation
- maxdb_stmt_store_result — Transfers a result set from a prepared statement
- maxdb_store_result — Transfers a result set from the last query
- maxdb_thread_id — Returns the thread ID for the current connection
- maxdb_thread_safe — Returns whether thread safety is given or not
- maxdb_use_result — Initiate a result set retrieval
- maxdb_warning_count — Returns the number of warnings from the last query for the given link
MongoDB Native Driver
Manual
Spis treści
- Instalacja
- Tutorial
- SQL to Mongo Mapping Chart
- Connecting
- Writes
- Querying
- Updates
- php.ini Options
- Security
- Troubleshooting
- Running the Driver's Tests
This manual goes into some detail about how to use MongoDB, but it mostly covers using the PHP driver. For information about how to design a schema, what terms means, and setting up the database server, check out the » MongoDB documentation.
Instalacja
The MongoDB PHP driver should work on nearly any system: Windows, Mac OS X, Unix, and Linux; little- and big-endian machines; 32- and 64-bit machines; PHP 5.1, 5.2, and 5.3.
To rozszerzenie » PECL nie jest dołączane do PHP. This page gives more specific information on installing on different systems and troubleshooting issues users have run into.
Installing on *NIX
Run:
$ sudo pecl install mongo
If you are using CentOS or Redhat, Csoke Arpad created » RPMs for these distributions.
Add the following line to your php.ini file:
extension=mongo.so
If pecl runs out of memory while installing, make sure memory_limit in php.ini is set to at least 32MB.
Manual Installation
For driver developers and people interested in the latest bugfixes, you can compile the driver from the latest source code on » Github. Go to Github and click the "download" button. Then run:
$ tar zxvf mongodb-mongodb-php-driver-<commit_id>.tar.gz $ cd mongodb-mongodb-php-driver-<commit_id> $ phpize $ ./configure $ sudo make install
Make the following changes to php.ini:
-
Make sure the extension_dir variable is pointing to the location of mongo.so. The build will display where it is installing the PHP driver with output that looks something like:
Make sure that it is the same as the PHP extension directory by runnning:Installing '/usr/lib/php/extensions/no-debug-zts-20060613/mongo.so'If it's not, change the extension_dir in php.ini or move mongo.so.$ php -i | grep extension_dir extension_dir => /usr/lib/php/extensions/no-debug-zts-20060613 => /usr/lib/php/extensions/no-debug-zts-20060613 -
To load the extension on PHP startup, add a line:
extension=mongo.so
OS X
If your system is unable to find autoconf, you'll need to install Xcode (available on your installation DVD or as a free download from the Apple website).
If you are using XAMPP, you may be able to compile the driver with the following command:
sudo /Applications/XAMPP/xamppfiles/bin/pecl install mongo
If you are using MAMP (or XAMPP and the above command does not work), precompiled binaries are available from » Github (download the latest one with "osx" in the name that matches your version of PHP). Extract mongo.so from the archive and add it to MAMP or XAMPP's extension directory. Add
extension=mongo.so
Gentoo
Gentoo has a package for the PHP driver called dev-php5/mongo, which can be installed with:
$ sudo emerge -va dev-php5/mongo
If you use PECL, you may get an error that libtool is the wrong version. Compiling from source you'll need to run aclocal and autoconf.
$ phpize && aclocal && autoconf && ./configure && make && make install
Red Hat
This includes Fedora and CentOS.
The default Apache settings on these systems do not let requests make network connections, meaning that the driver will get "Permission denied" errors when it tries to connect to the database. If you run into this, try running:
$ /usr/sbin/setsebool -P httpd_can_network_connect 1
Installing on Windows
Precompiled binaries for each release are available from » Github for a variety of combinations of versions, thread safety, and VC libraries. Unzip the archive and put php_mongo.dll in your PHP extension directory ("ext" by default).
The latest (non-release) code is compiled into Windows binaries on every commit. The zip consists of a .zip with php_mongo.dll and a version.txt. Please keep the version.txt around so that if you have a question or problem, you can give the developers the exact version you're using. (The number is long and nonsensical, but it will make sense to the developers!)
To get the latest bug fixes (and possibly bugs), download the binary corresponding to the PHP you have installed:
Add the following line to your php.ini file:
extension=php_mongo.dll
Third-Party Installation Instructions
A number of people have created excellent tutorials on installing the PHP driver.
-
» PHP 5.3.1 with Xdebug, MongoDB and Lithium on Ubuntu 9.10 / Apache 2.2
An excellent video that takes you step-by-step through installing Apache, PHP, Xdebug, MongoDB, and Lithium by Jon Adams.
-
» Installing MongoDB and the PHP driver on Ubuntu 9.04
Spanish article by Javier Aranda (» English translation).
-
» OS X: Installing MongoDB and the PHP Mongo Driver
By Matt Butcher.
Tutorial
Introduction
This is the 10gen-supported PHP driver for MongoDB.
Here's a quick code sample that connects, inserts documents, queries for documents, iterates through query results, and disconnects from MongoDB. There are more details on each step in the tutorial below.
<?php
// connect
$m = new Mongo();
// select a database
$db = $m->comedy;
// select a collection (analogous to a relational database's table)
$collection = $db->cartoons;
// add a record
$obj = array( "title" => "Calvin and Hobbes", "author" => "Bill Watterson" );
$collection->insert($obj);
// add another record, with a different "shape"
$obj = array( "title" => "XKCD", "online" => true );
$collection->insert($obj);
// find everything in the collection
$cursor = $collection->find();
// iterate through the results
foreach ($cursor as $obj) {
echo $obj["title"] . "\n";
}
?>
This would output:
Calvin and Hobbes XKCD
Making a Connection
To connect to the database server, use one of the following:
<?php
$connection = new Mongo(); // connects to localhost:27017
$connection = new Mongo( "example.com" ); // connect to a remote host (default port: 27017)
$connection = new Mongo( "example.com:65432" ); // connect to a remote host at a given port
?>
You do not have to explicitly disconnect from the database. When $connection goes out of scope, the connection will be closed automatically and any database resources it was using will be freed.
See Also
The chapter on connecting covers different types of connections.
The API documentation on the Mongo class and Mongo::__construct() give a comprehensive look at all possible options with a number of examples.
Getting a Database
To select a database, use:
<?php
$db = $connection->dbname;
?>
The database does not need to be created in advance, you can create new databases by selecting them.
Be careful of typos! You can inadvertently create a new database, which can cause confusing errors:
<?php
$db = $connection->mybiglongdbname;
// do some stuff
$db = $connection->mybiglongdbanme;
// now connected to a different database!
?>
See Also
The API documentation on the MongoDB class contains more information about database objects.
Getting A Collection
Getting a collection has the same syntax as getting a database:
<?php
$db = $connection->baz;
$collection = $db->foobar;
// or, more succinctly
$collection = $connection->baz->foobar;
?>
A collection is analogous to a table (if you are familiar with relational databases).
See Also
The API documentation on the MongoCollection class contains more information about collection objects.
Inserting a Document
Associative arrays are the basic object that can be saved to a collection in the database. A somewhat random "document" might be:
<?php
$doc = array( "name" => "MongoDB",
"type" => "database",
"count" => 1,
"info" => (object)array( "x" => 203, "y" => 102),
"versions" => array("0.9.7", "0.9.8", "0.9.9")
);
?>
Note that you can have nested arrays and objects.
To insert this document, use MongoCollection::insert():
<?php
$collection->insert( $doc );
?>
See Also
The API documentation on MongoCollection::insert() contains more information about inserting data.
Finding Documents using MongoCollection::findOne()
To show that the document we inserted in the previous step is there, we can do a simple MongoCollection::findOne() operation to get a single document from the collection. This method is useful when there only is one document matching the query or you are only interested in one result.
<?php
$obj = $collection->findOne();
var_dump( $obj );
?>
This should print:
array(6) {
["_id"]=>
object(MongoId)#8 (1) {
["$id"]=>
string(24) "4e2995576803fab768000000"
}
["name"]=>
string(7) "MongoDB"
["type"]=>
string(8) "database"
["count"]=>
int(1)
["info"]=>
array(2) {
["x"]=>
int(203)
["y"]=>
int(102)
}
["versions"]=>
array(3) {
[0]=>
string(5) "0.9.7"
[1]=>
string(5) "0.9.8"
[2]=>
string(5) "0.9.9"
}
}
Note that there is an _id field that has been added automatically to your document. _id is the "primary key" field. If your document does not specify one, the driver will add one automatically.
If you specify your own _id field, it must be unique to the collection. See the example here:
<?php
$db->foo->insert(array("_id" => 1), array("safe" => true));
// this will throw an exception
$db->foo->insert(array("_id" => 1), array("safe" => true));
// this is fine, as it is a different collection
$db->bar->insert(array("_id" => 1), array("safe" => true));
?>
Note that these inserts pass a second array: array("safe" => true). This second field specifies options for the insert. By default, the driver does not wait for a database response for writes, so the driver would not catch the the _id. As we specify that this is a "safe" write, the driver will wait for a database response and see that the write did not go through. In general, all writes should use the "safe" option (it is omitted in previous examples for simplicity).
See Also
MongoCollection::findOne() for more information about finding data.
MongoId goes into more detail on unique ids.
The writes section covers safe writes in more depth, as do the writing functions such as MongoCollection::insert(), MongoCollection::update(), and MongoCollection::remove().
Adding Multiple Documents
In order to do more interesting things with queries, let's add multiple simple documents to the collection. These documents will just be of the form array( "i" => value ); and we can do this fairly efficiently in a loop:
<?php
for($i=0; $i<100; $i++) {
$collection->insert( array( "i" => $i ) );
}
?>
Notice that we can insert arrays with different key sets into the same collection. This aspect is what we mean when we say that MongoDB is "schema-free".
Counting Documents in A Collection
Now that we've inserted 101 documents (the 100 we did in the loop, plus the first one), we can check to see if we have them all using the MongoCollection::count() method.
<?php
echo $collection->count();
?>
Using a Cursor to Get All of the Documents
In order to get all the documents in the collection, we will use MongoCollection::find(). The find() method returns a MongoCursor object which allows us to iterate over the set of documents that matched our query. So to query all of the documents and print them out:
<?php
$cursor = $collection->find();
foreach ($cursor as $id => $value) {
echo "$id: ";
var_dump( $value );
}
?>
See Also
The API documentation on MongoCollection::find() contains more information about finding data.
Setting Criteria for a Query
We can create a query to pass to the MongoCollection::find() method to get a subset of the documents in our collection. For example, if we wanted to find the document for which the value of the "i" field is 71, we would do the following:
<?php
$query = array( "i" => 71 );
$cursor = $collection->find( $query );
while( $cursor->hasNext() ) {
var_dump( $cursor->getNext() );
}
?>
and it should just print just one document:
array(2) {
["_id"]=>
object(MongoId)#6 (0) {
}
["i"]=>
int(71)
["_ns"]=>
"testCollection"
}
Getting A Set of Documents With a Query
We can use the query to get a set of documents from our collection. For example, if we wanted to get all documents where "i" > 50, we could write:
<?php
$query = array( "i" => array( '$gt' => 50 ) ); //note the single quotes around '$gt'
$cursor = $coll->find( $query );
while( $cursor->hasNext() ) {
var_dump( $cursor->getNext() );
}
?>
which should print the documents where i > 50. We could also get a range, say 20 < i <= 30:
<?php
$query = array( "i" => array( "\$gt" => 20, "\$lte" => 30 ) );
$cursor = $coll->find( $query );
while( $cursor->hasNext() ) {
var_dump( $cursor->getNext() );
}
?>
Remember to always escape the $-symbol or use single quotes. Otherwise PHP will interpret it to be the variable $gt.
Creating An Index
MongoDB supports indexes, and they are very easy to add on a collection. To create an index, you specify the field name and direction: ascending (1) or descending (-1). The following creates an ascending index on the "i" field:
<?php
$coll->ensureIndex( array( "i" => 1 ) ); // create index on "i"
$coll->ensureIndex( array( "i" => -1, "j" => 1 ) ); // index on "i" descending, "j" ascending
?>
Indexing is critical for good read performance as your data grows. If you are not familiar with indexing, check out the MongoCollection::ensureIndex() documentation and the core » MongoDB indexing documentation.
SQL to Mongo Mapping Chart
This is a PHP-specific version of the » SQL to Mongo mapping chart in the main docs.
| SQL Statement | Mongo Query Language Statement |
|---|---|
| CREATE TABLE USERS (a Number, b Number) | Implicit or use MongoDB::createCollection(). |
| INSERT INTO USERS VALUES(1,1) | $db->users->insert(array("a" => 1, "b" => 1)); |
| SELECT a,b FROM users | $db->users->find(array(), array("a" => 1, "b" => 1)); |
| SELECT * FROM users WHERE age=33 | $db->users->find(array("age" => 33)); |
| SELECT a,b FROM users WHERE age=33 | $db->users->find(array("age" => 33), array("a" => 1, "b" => 1)); |
| SELECT a,b FROM users WHERE age=33 ORDER BY name | $db->users->find(array("age" => 33), array("a" => 1, "b" => 1))->sort(array("name" => 1)); |
| SELECT * FROM users WHERE age>33 | $db->users->find(array("age" => array('$gt' => 33))); |
| SELECT * FROM users WHERE age<33 | $db->users->find(array("age" => array('$lt' => 33))); |
| SELECT * FROM users WHERE name LIKE "%Joe%" | $db->users->find(array("name" => new MongoRegex("/Joe/"))); |
| SELECT * FROM users WHERE name LIKE "Joe%" | $db->users->find(array("name" => new MongoRegex("/^Joe/"))); |
| SELECT * FROM users WHERE age>33 AND age<=40 | $db->users->find(array("age" => array('$gt' => 33, '$lte' => 40))); |
| SELECT * FROM users ORDER BY name DESC | $db->users->find()->sort(array("name" => -1)); |
| CREATE INDEX myindexname ON users(name) | $db->users->ensureIndex(array("name" => 1)); |
| CREATE INDEX myindexname ON users(name,ts DESC) | $db->users->ensureIndex(array("name" => 1, "ts" => -1)); |
| SELECT * FROM users WHERE a=1 and b='q' | $db->users->find(array("a" => 1, "b" => "q")); |
| SELECT * FROM users LIMIT 10 SKIP 20 | $db->users->find()->limit(10)->skip(20); |
| SELECT * FROM users WHERE a=1 or b=2 | $db->users->find(array('$or' => array(array("a" => 1), array("b" => 2)))); |
| SELECT * FROM users LIMIT 1 | $db->users->find()->limit(1); |
| EXPLAIN SELECT * FROM users WHERE z=3 | $db->users->find(array("z" => 3))->explain() |
| SELECT DISTINCT last_name FROM users | $db->command(array("distinct" => "users", "key" => "last_name")); |
| SELECT COUNT(*y) FROM users | $db->users->count(); |
| SELECT COUNT(*y) FROM users where AGE > 30 | $db->users->find(array("age" => array('$gt' => 30)))->count(); |
| SELECT COUNT(AGE) from users | $db->users->find(array("age" => array('$exists' => true)))->count(); |
| UPDATE users SET a=1 WHERE b='q' | $db->users->update(array("b" => "q"), array('$set' => array("a" => 1))); |
| UPDATE users SET a=a+2 WHERE b='q' | $db->users->update(array("b" => "q"), array('$inc' => array("a" => 2))); |
| DELETE FROM users WHERE z="abc" | $db->users->remove(array("z" => "abc")); |
Connecting
Connecting to MongoDB can be as easy as new Mongo, but there are many additional options and configurations. The Mongo::__construct() page covers all of the API options, but this page gives some more details and advice for practical use cases.
Logging In on Connection
If MongoDB is started with the --auth or --keyFile options, you must log in before you can do any operations with the driver. You can log in on connection by supplying the username and password in the connection URI:
<?php
$m = new Mongo("mongodb://${username}:${password}@localhost");
?>
If your connection is dropped, the driver will automatically attempt to reconnect and reauthenticate you.
You can also authenticate on a per-database level with MongoDB::authenticate():
<?php
$m = new Mongo();
$db = $m->admin;
$db->authenticate($username, $password);
?>
There is a major disadvantage to this method: if the connection is dropped and then reconnects, the new connection will not be authenticated. If you use the URI format, the PHP driver will automatically authenticate the user whenever a new connection is made.
To authenticate with a different database, specify the database name after the hosts. This example will log the user into the "blog" database:
<?php
$m = new Mongo("mongodb://${username}:${password}@localhost/blog");
?>
Replica Sets
To connect to a replica set, specify one or more members of the set and use the replicaSet option.
<?php
$m = new Mongo("mongodb://localhost:27017", array("replicaSet" => "myReplSetName"));
?>
Version 1.0.9+ of the driver is required to connect to a replica set (earlier versions of the driver will not autodetect the master or reconnect correctly).
The PHP driver will query the database server(s) listed to figure out who is master. So long as it can connect to at least one host listed and find a master, the connection will succeed. If it cannot make a connection to any servers listed or cannot find a master, a MongoConnectionException will be thrown.
If the master becomes unavailable, the slaves will not promote a new master for a few seconds. During that time, this connection will not be able to perform any database operations (connections to slaves will still be able to perform reads). Thus, if you attempt to do any sort of read or write on this connection, it will throw an exception.
Once a master is elected, attempting to perform a read or write will allow the driver to detect the new master. The driver will make this its primary database connection and continue operating normally.
For more information on replica sets, see the » core documentation.
Domain Socket Support
If you are running MongoDB locally and have version 1.0.9 or better of the driver, you can connect to the database via file. MongoDB automatically opens a socket file on startup: /tmp/mongodb-<port>.sock.
To connect to the socket file, specify the path in your MongoDB connection string:
<?php
$m = new Mongo("mongodb:///tmp/mongo-27017.sock");
?>
If you would like to use authentication on connection (as described above) with a socket file, you must specify a port of 0 so that the connection string parser knows where the end of the connection string is.
<?php
$m = new Mongo("mongodb://username:password@/tmp/mongo-27017.sock:0/foo");
?>
Connection Pooling (version 1.2.0+)
Creating connections is one of the most heavyweight things that the driver does. It can take hundreds of milliseconds to set up a connection correctly, even on a fast network. Thus, the driver tries to minimize the number of new connections created by reusing connections from a pool.
When a user creates a new instance of Mongo, all necessary connections will be taken from their pools (replica sets may require multple connections, one for each member of the set). When the Mongo instance goes out of scope, the connections will be returned to the pool. When the PHP process exits, all connections in the pools will be closed.
"Why do I have so many open connections?"
Connection pools can generate a large number of connections. This is expected and, using a little arithmetic, you can figure out how many connections to expect. There are three factors in the total number of connections:
-
connections_per_pool
Each connection pool will create, by default, an unlimited number of connections. One might assume that this is a problem: if it can create an unlimited number of connections, couldn't it create thousands and the server would run out of file descriptors? In practice, this is unlikely, as unused connections are returned to the pool to be used later, so future connections will use the same connection instead of creating a new one. Unless you create thousands of connections at once without letting any go out of scope, the number of connections open should stay at a reasonable number.
You can see how many connections you have in a pool using the MongoPool::info() function. Add up the "in use" and "in pool" fields for a given server. That is the total number of connections for that pool.
-
pools_per_process
Each MongoDB server address you're connecting to gets its own connection pool. For example, if your local hostname is "example.net", connecting to "example.net:27017", "localhost:27017", and "/tmp/mongodb-27017.sock" will create three connection pools. You can see how many connection pools you have open using MongoPool::info().
-
processes
Each PHP process has a separate set of pools. PHP-FPM and Apache generally create between 6 and a couple dozen PHP worker children. Check your settings to see what the max number of PHP processes is that can be spawned.
If you are using PHP-FPM, estimating the number of connections can be tricky because it will spawn more PHP-FPM workers under heavy load. To be on the safe side, look at the max_children parameter or add up spare_servers+start_servers (choose whichever number is higher). That's how many PHP processes (and, thus sets of pools) you should plan for.
The three variables above can be multiplied together to give the max number of connections expected: connections_per_pool*pools_per_process*processes. Note that connections_per_pool can be different for different pools, so connections_per_pool should be the max.
For example, suppose we're getting 30 connections per pool, 10 pools per PHP process, and 128 PHP processes. Then we can expect 38400 connections from this machine. Thus, we should set this machine's file descriptor limit to be high enough to handle all of these connections or it may run out of file descriptors.
See MongoPool for more information on connection pooling.
Persistent Connections
Informacja:
This section is not relevant for 1.2.0+. In 1.2.0+, connections are always persistent and managed automatically by the driver. See MongoPool for more information on pooling.
Creating new connection to the database is very slow. To minimize the number of connections that you need to make, you can use persistent connections. A persistent connection is saved by PHP, so you can use the same connection for multiple requests.
For example, this simple program connects to the database 1000 times:
<?php
for ($i=0; $i<1000; $i++) {
$m = new Mongo();
}
?>
It takes approximately 18 seconds to execute. If we change it to use a persistent connection:
<?php
for ($i=0; $i<1000; $i++) {
$m = new Mongo("localhost:27017", array("persist" => "x"));
}
?>
...it takes less than .02 seconds to execute, as it only makes one database connection.
Persistent connections need an identifier string (which is "x" in the above example) to uniquely identify them. For a persistent connection to be used, the hostname, port, persist string, and username and password (if given) must match an existing persistent connection. Otherwise, a new connection will be created with this identifying information.
Persistent connections are highly recommended and should always be used in production unless there is a compelling reason not to. Most of the reasons that they are not recommended for relational databases are irrelevant to MongoDB.
Writes
Safe Operations
By default, the driver does not wait for a database response to writes (inserts, updates, and deletes). This means that writes can be performed extremely quickly, but you don't know whether or not they actually succeeded. Writes can fail for a number of reasons: if there are network problems, if a database server goes down, or if the write was simply invalid (e.g., writing to a system collection).
To get a response from the database, use the safe option, available for all types of writes. This option will make sure that the database has the write before returning success. If the write failed, it will throw a MongoCursorException() with an explanation of the failure.
While developing, you should always use safe writes (to protect against inadvertent mistakes, such as duplicate key errors and similar). In production, unsafe writes can be used for "unimportant" data. Unimportant data varies on application, but it's generally automatically (instead of user generated) data, such as click tracking or GPS locations, where you can get thousands of records per second.
To safely perform writes without incurring too large a performance penalty, it is recommended that you do a safe write at the end of a series of writes. For example:
<?php
$collection->insert($someDoc);
$collection->update($criteria, $newObj);
$collection->insert($somethingElse);
$collection->remove($something, array("safe" => true));
?>
Then, if the last write throws an exception, you know that there's a problem with your database.
There are a few other options available to ensure the safety of writes. You can specify "fsync" => true to force the database to fsync all writes up to this point to disk (by default, MongoDB fsyncs writes once per minute).
The safest way of doing a write is to use replication and specify the number of servers that must have this write before returning success. (You should always use replication in production, see the Connecting section for more information on replica sets.)
<?php
$collection->insert($someDoc, array("safe" => 3));
?>
If you specify "safe" => N, the MongoDB server will make sure that at least N servers have a copy of the write before returning success. So, if N is 3, the master and two slaves must have the write.
Updating Nested Objects
Suppose we wish to change the name of a comment's author in this document:
{
"_id" : ObjectId("4b06c282edb87a281e09dad9"),
"content" : "this is a blog post.",
"comments" :
[
{
"author" : "Mike",
"comment" : "I think that blah blah blah...",
},
{
"author" : "John",
"comment" : "I disagree."
}
]
}
<?php
$blog->update($criteria, array('$set' => array("comments.1" => array("author" => "Jim"))));
?>
The Positional Operator
The positional operator $ is useful for updating objects that are in arrays. In the example above, for instance, suppose that we did not know the index of the comment that we needed to change, merely that we needed to change "John" to "Jim". We can use $ to do so.
<?php
$blog->update(
array("comments.author" => "John"),
array('$set' => array('comments.$.author' => "Jim")));
?>
Querying
Distributing queries to slaves
Informacja: 1.1.0+
If you are using a » replica set and version 1.1.0 or above of the driver, the driver can automatically route reads to slaves. This behavior does not exist in earlier versions of the driver and cannot be used with "normal" master-slave.
By default, the driver will send all queries to the master. If you set the "slaveOkay" option, the driver will send all queries to a non-primary server, if possible. The "slaveOkay" option can be set at every "level": connection, database, collection, and cursor. Each class inherits the "slaveOkay" setting from the class above it, so if you do:
<?php
$db->setSlaveOkay(true);
$c = $db->myCollection;
$cursor = $c->find();
?>
then the query will be executed against a slave (the collection inherited "slaveOkay" from the database and the cursor inherited it from the collection).
How slaves are chosen
Each instance of Mongo chooses its own slave using the available slave with the lowest ping time. So, if we had a PHP client in Europe and one in Australia and we had one secondary in each of these data centers, we could do:
<?php
// P is the primary
// on the Australian client
$m1 = new Mongo("mongodb://P", array("replicaSet" => true));
$m1->foo->bar->find()->slaveOkay()->getNext();
echo "m1's slave is ".$m1->getSlave()."\n";
// on the European client
$m2 = new Mongo("mongodb://P", array("replicaSet" => true));
$m2->foo->bar->find()->slaveOkay()->getNext();
echo "m2's slave is ".$m2->getSlave()."\n";
?>
we'd probably end up with something like:
m1's slave is: australianHost
m2's slave is: europeanHost
Note that we have to do a query before a slave is chosen: slaves are chosen
lazily by the driver. Mongo::getSlave() will return
NULL until a slave is used.
You can see what the driver thinks is the current status of the set members by running Mongo::getHosts().
If no non-primary server is readable, the driver will send reads to the primary (even if "slaveOkay" is set). A server is considered readable if its state is 2 (SECONDARY) and its health is 1. You can check this with Mongo::getHosts().
If you enjoy twiddling knobs that you probably shouldn't mess with, you can request the driver to use a different slave by calling Mongo::switchSlave(). This may choose a new slave (if one is available) and shouldn't be used unless you know what you're doing.
Random notes
Writes are always sent to the primary. Database commands, even read-only commands, are also always sent to the primary.
The health and state of a slave is checked every 5 seconds or when the next operation occurs after 5 seconds. It will also recheck the configuration when the driver has a problem reaching a server.
Note that a non-primary server may be behind the primary in operations, so your application must be okay with getting out-of-date data (or you must use w for all writes).
Querying by _id
Every object inserted is automatically assigned a unique _id field, which is often a useful field to use in queries.
Suppose that we wish to find the document we just inserted. Inserting adds and _id field to the document, so we can query by that:
<?php
$person = array("name" => "joe");
$people->insert($person);
// now $joe has an _id field
$joe = $people->findOne(array("_id" => $person['_id']));
?>
Unless the user has specified otherwise, the _id field is a MongoId. The most common mistake is attepting to use a string to match a MongoId. Keep in mind that these are two different datatypes, and will not match each other in the same way that the string "array()" is not the same as an empty array. For example:
<?php
$person = array("name" => "joe");
$people->insert($person);
// convert the _id to a string
$pid = $person['_id'] . "";
// FAILS - $pid is a string, not a MongoId
$joe = $people->findOne(array("_id" => $pid));
?>
Arrays
Arrays are special in a couple ways. First, there are two types that MongoDB uses: "normal" arrays and associative arrays. Associative arrays can have any mix of key types and values. "Normal" arrays are defined as arrays with ascending numeric indexes starting at 0 and increasing by one for each element. These are, typically, just your usual PHP array.
For instance, if you want to save a list of awards in a document, you could say:
<?php
$collection->save(array("awards" => array("gold", "silver", "bronze")));
?>
Queries can reach into arrays to search for elements. Suppose that we wish to find all documents with an array element of a given value. For example, documents with a "gold" award, such as:
{ "_id" : ObjectId("4b06c282edb87a281e09dad9"), "awards" : ["gold", "silver", "bronze"]}
This can be done with a simple query, ignoring the fact that "awards" is an array:
<?php
$cursor = $collection->find(array("awards" => "gold"));
?>
Suppose we are querying for a more complex object, if each element of the array were an object itself, such as:
{
"_id" : ObjectId("4b06c282edb87a281e09dad9"),
"awards" :
[
{
"first place" : "gold"
},
{
"second place" : "silver"
},
{
"third place" : "bronze"
}
]
}
Still ignoring that this is an array, we can use dot notation to query the subobject:
<?php
$cursor = $collection->find(array("awards.first place" => "gold"));
?>
Notice that it doesn't matter that there is a space in the field name (although it may be best not to use spaces, just to make things more readable).
You can also use an array to query for a number of possible values. For instance, if we were looking for documents "gold" or "copper", we could do:
<?php
$cursor = $collection->find(array("awards" => array('$in' => array("gold", "copper"))));
?>
Updates
Updates can be one of the most complicated operation available with MongoDB. They combine a query with an action, modifying documents that match the criteria. They are also extremely powerful, allowing you to change documents quickly and replace them altogether. They are done in-place (when possible) with little overhead.
Modifying vs. replacing documents
There are two types of updates you can use: modifying updates and replacing updates. Modifying updates contain $-operators and change fields in a document: they might increment counters, push new elements onto an array, or change the type of a field.
For example, a modifying update could add a new field to a document.
<?php
/** suppose documents look like:
* {"username" : "...", "password" : "...", "email" : "..."}
*/
$coll->update(array("username" => "joe"), array('$set' => array("twitter" => "@joe4153")));
/** now the document will look like:
* {"username" : "joe", "password" : "...", "email" : "...", "twitter" : "@joe4153"}
*/
?>
Replacing updates replace the entire matching document with a new document. They are generally not as efficient as using $-modifiers, but can be very usefully for complex operations or updates that can't be expressed in terms of $-operators.
For example, a replacing update can completely change the structure of a document.
<?php
/** suppose documents look like:
* {"username" : "...", "password" : "...", "email" : "..."}
*/
$coll->update(array("username" => "joe"), array("userId" => 12345, "info" => array(
"name" => "joe", "twitter" => "@joe4153", "email" => "..."), "likes" => array()));
/** now the document will look like:
* {
* "userId" : 12345,
* "info" : {
* "name" : "joe",
* "twitter" : "@joe4153",
* "email" : "..."
* },
* "likes" : []
* }
*/
?>
Updating Nested Objects
Suppose we wish to change the name of a comment's author in this document:
{
"_id" : ObjectId("4b06c282edb87a281e09dad9"),
"content" : "this is a blog post.",
"comments" :
[
{
"author" : "Mike",
"comment" : "I think that blah blah blah...",
},
{
"author" : "John",
"comment" : "I disagree."
}
]
}
<?php
$blog->update($criteria, array('$set' => array("comments.1" => array("author" => "Jim"))));
?>
The Positional Operator
The positional operator $ is useful for updating objects that are in arrays. In the example above, for instance, suppose that we did not know the index of the comment that we needed to change, merely that we needed to change "John" to "Jim". We can use $ to do so.
<?php
$blog->update(
array("comments.author" => "John"),
array('$set' => array('comments.$.author' => "Jim")));
?>
php.ini Options
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian |
|---|---|---|
| mongo.native_long | false* | PHP_INI_ALL |
| mongo.long_as_object | false | PHP_INI_ALL |
| mongo.default_host | "localhost" | PHP_INI_ALL |
| mongo.default_port | 27017 | PHP_INI_ALL |
| mongo.auto_reconnect | true | PHP_INI_SYSTEM |
| mongo.allow_persistent | true | PHP_INI_SYSTEM |
| mongo.chunk_size | 262144 | PHP_INI_SYSTEM |
| mongo.cmd | "$" | PHP_INI_ALL |
| mongo.utf8 | "1" | PHP_INI_ALL |
| mongo.allow_empty_keys | false | PHP_INI_ALL |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
mongo.native-longint -
The default behavior for this will be changed to
TRUEin 2.0.0, so make sure to set this variable to the value you want (probablyTRUE) so that the driver's behavior doesn't suddenly change when you upgrade.On 64-bit platforms, the mongo.native_long setting allows for 64-bit integers to be stored in MongoDB. If it is not set, only 32-bits of the integer will be saved. The MongoDB data type that is used in this case is the BSON LONG, instead of the BSON INT that is used if this setting is turned off.
The setting also changes the way how BSON LONGs behave when they are read back from MongoDB. Without mongo.native_long enabled, the driver would convert every BSON LONG to a PHP double which can result in a loss of precision.
On 32-bit platforms, the mongo.native_log setting changes nothing for storing integers in MongoDB: the integer is stored as a BSON INT as before. However, when the setting is enabled and a BSON LONG is read from MongoDB a MongoCursorException is thrown alerting you that the data could not be read back without losing precision.
On 32-bit systems especially, it is recommended that you combine this with enabling mongo.long_as_object.
-
mongo.long_as_objectstring -
Return a BSON_LONG as an instance of MongoInt64 (instead of a primitive type).
-
mongo.default_hoststring -
Default hostname when nothing is passed to the constructor.
-
mongo.default_portstring -
The default TCP port number to use when connecting to the database server if no other port is specified. The database's default is 27017.
-
mongo.auto_reconnectbool -
Whether to reconnect to the database if the connection is lost.
-
mongo.allow_persistentbool -
If persistent connections are allowed.
-
mongo.chunk_sizeint -
The number of bytes-per-chunk. Used in divvying up GridFS files. This number must be at least 100 less than 4 megabytes (max: 4194204) and it is recommended that it be less than that.
-
mongo.cmdstring -
A character to be used in place of $ in modifiers and comparisons.
As it is easy to forget to escape the "$", you can also choose your own special character to use instead of '$'. Choose a character that will not occur in your key names, e.g. ":":
mongo.cmd = ":"
Then, to do a comparison, for example:
<?php
$query = array( "i" => array( ":gt" => 20, ":lte" => 30 ) );
?>You can also change it in your code using ini_set("mongo.cmd", ":"). Of course, you can also just use single quotes or backslash-escape the $.
-
mongo.utf8int -
If an exception should be thrown for non-UTF8 strings. Until version 1.0.4, the PHP driver would ignore non-UTF8 strings, even though you're not supposed to insert them. As of 1.0.4, the driver throws a MongoException. To ease the transition for applications that insert non-UTF8 strings, you can turn this option off to emulate the old, non-exception-throwning behavior. This option will be eliminated and exceptions always thrown for non-UTF8 strings starting with version 1.1.0.
-
mongo.allow_empty_keysint -
Added in version 1.0.11.
If empty strings ("") should be allowed as key names. By default, the driver will throw an exception if you attempt to pass the empty string as a key to the database. It is extremely easy to do this inavertently by using double quotes with $-operators, so it is recommended that you leave this setting as default. However, if you need to save keys that are empty strings, you can set this option to true and the driver will allow you to pass empty strings to the database.
Security
Request Injection Attacks
If you are passing $_GET parameters to your queries, make sure that they are cast to strings first. Users can insert associative arrays in GET requests, which could then become unwanted $-queries.
A fairly innocuous example: suppose you are looking up a user's information with the request http://www.example.com?username=bob. Your application does the query $collection->find(array("username" => $_GET['username'])).
Someone could subvert this by getting http://www.example.com?username[$ne]=foo, which PHP will magically turn into an associative array, turning your query into $collection->find(array("username" => array('$ne' => "foo"))), which will return all users not named "foo" (all of your users, probably).
This is a fairly easy attack to defend against: make sure $_GET's parameters are the type you expect before you send them to the database (cast them to strings, in this case).
Note that this type of attack can be used with any databases interation that locates a document, including updates, upserts, find-and-modifies, and removes.
Thanks to » Phil for pointing this out.
See » the main documentation for more information about SQL-injection-like issues with MongoDB.
Script Injection Attacks
If you are using JavaScript, make sure that any variables that cross the PHP- to-JavaScript boundry are passed in the scope field of MongoCode, not interpolated into the JavaScript string. This can come up when using MongoDB::execute(), $where clauses, MapReduces, group-bys, and any other time you may pass JavaScript into the database.
Informacja:
MapReduce ignore the scope field of MongoCode, but there is a scope option on the command that can be used instead.
For example, suppose we have some JavaScript to greet a user in the database logs. We could do:
<?php
// don't do this!
$username = $_POST['username'];
$db->execute("print('Hello, $username!');");
?>
However, what if a malicious user passes in some JavaScript?
<?php
// don't do this!
// $username is set to "'); db.users.drop(); print('"
$db->execute("print('Hello, $username!');");
?>
Now MongoDB executes the JavaScript string "print('Hello, '); db.users.drop(); print('!');". This attack is easy to avoid: use scope to pass variables from PHP to JavaScript:
<?php
$scope = array("user" => $username);
$db->execute(new MongoCode("print('Hello, '+user+'!');", $scope));
?>
This adds a variable user to the JavaScript scope. Now if someone tries to send malicious code, MongoDB will harmlessly print Hello, '); db.dropDatabase(); print('!.
Using scope helps prevent malicious input from being executed by the database. However, you must make sure that your code does not turn around and execute the input anyway! For example, never use the JavaScript eval function on user input:
<?php
// don't do this!
// $jsShellInput is "db.users.drop();"
$scope = array("input" => $jsShellInput);
$db->execute(new MongoCode("eval(input);", $scope));
?>
Always use scope and never allow the database to execute user input as code.
Troubleshooting
If you're having trouble, there are lots of resources you can turn to.
-
IRC
The official MongoDB IRC room is irc.freenode.net/#mongodb. This is the fastest way to get help... if there are people around.
-
Mailing List
» MongoDB's mailing list is a good (and usually very fast) way to get answers to questions.
-
Bug Tracker
Found a bug? Want a feature? Have a question? File it in the » PHP driver's bug tracker.
You can turn on (very) verbose debugging output by compiling the driver with the debugging flag.
$ ./configure CFLAGS=-DDEBUG
DEBUG turns on all debugging. You can also turn on specific debug flags. In the latest code, these flags are:
-
DEBUG_CONN
Debugging connections.
Running the Driver's Tests
The PECL package does not come with the tests, but they are available at » Github. There are two types of tests: the PHPUnit tests and the C tests.
PHPUnit Tests
To run the tests, you must download the driver from Github (the tests are in the tests/ directory). You'll also need » PHPUnit to run the tests. PHPUnit can be installed via PEAR (although you should look at the installation instructions, it requires a couple of prerequisites).
Some tests expect warnings or errors, so you must set error_reporting in php.ini to E_STRICT | E_ALL for these tests to pass. If you do not, you will get some failures that say the test was expecting a warning or error.
To run the tests, make sure that there is a MongoDB server running locally on port 27017. Before reporting errors, please try running the tests against the latest development version of MongoDB: often there are tests for features that aren't yet in the stable release.
The test suite uses the "phpunit" database. If you are using a database called "phpunit" in your application, make sure point MongoDB at a different data directory before running the tests.
Make sure you're in the main directory of the driver source you downloaded from Github. Run:
$ phpunit tests/MongoSuite.php
C Tests
The C tests mostly check internal functions that are not exposed through PHP. If you'd like to run these tests, you'll need to compile PHP with the --enable-embed flag. Then switch to the tests directory and run make. This will create a binary called unit. Run unit to execute the tests. These tests do no require a database to be running.
If a test passes, it will print a ".". If a test fails, it will assert and stop the tests. Please report any asserts.
If make cannot find your PHP embedded library (libphp5.so) or header files, you may have to specify the PHP_PATH variable.
Run make clean to remove all testing objects.
If you run these tests with valgrind, you should get no invalid memory access errors and the "no leaks are possible" message at the end.
Reporting Errors
Please report any failures or errors in the » bugtracker. There may be skipped tests, these are normal and can be ignored.
New tests are always welcome! Please feel free to contribute new tests of any type testing any functionality.
Core Classes
Spis treści
The core classes are the most important part of the driver.
The Mongo class
(No version information available, might only be in SVN)
Wstęp
A connection between PHP and MongoDB.
This class is used to create and manage connections. A typical use is:
<?php
$m = new Mongo(); // connect
$db = $m->foo; // get the database named "foo"
?>
See Mongo::__construct() and the section on connecting for more information about creating connections.
Krótki opis klasy
FALSE
;NULL
;NULL
;$server = "mongodb://localhost:27017"
[, array $options = array("connect" => TRUE)
]] )Stałe predefiniowane
Mongo Constants
-
Mongo::VERSION - PHP driver version. May be suffixed with "+" or "-" if it is in-between versions.
-
Mongo::DEFAULT_HOST"localhost" - Host to connect to if no host is given.
-
Mongo::DEFAULT_PORT27017 - Port to connect to if no port is given.
Fields
- status
-
If this is a persistent connection, if the connection was created for
this object or is being reused. If this is not a persistent connection,
this field should be
NULL.
Zobacz też:
MongoDB core docs on » connecting.
Mongo::close
(PECL mongo >=0.9.0)
Mongo::close — Closes this connection
Opis
This method does not need to be called, except in unusual circumstances. The driver will cleanly close the database connection when this Mongo instance goes out of scope.
If objects do not go out of scope between requests, you may wish to call this method at the end of your program to keep old connections from hanging around. However, it is probably more efficient use a persistent connection, which will automatically create a connection if needed and use it for as many requests as possible.
If you are connected to a replica set, close() will only close the connection to the primary.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns if the connection was successfully closed.
Mongo::connect
(PECL mongo >=0.9.0)
Mongo::connect — Connects to a database server
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
If the connection was successful.
Błędy/Wyjątki
Throws MongoConnectionException if it fails to connect to the database.
Mongo::connectUtil
(PECL mongo >=0.9.0)
Mongo::connectUtil — Connects with a database server
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
If the connection was successful.
Błędy/Wyjątki
Throws MongoConnectionException if it fails to connect to the databases.
Mongo::__construct
(PECL mongo >=0.9.0)
Mongo::__construct — Creates a new database connection object
Opis
$server = "mongodb://localhost:27017"
[, array $options = array("connect" => TRUE)
]] )If no parameters are passed, this connects to "localhost:27017" (or whatever was specified in php.ini for mongo.default_host and mongo.default_port).
server should have the form:
mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db
The connection string always starts with mongodb://, to indicate it is a connection string in this form.
If username and password are specified, the constructor will attempt to authenticate the connection with the database before returning. Username and password are optional and must be followed by an @, if specified.
At least one host must be given (port optional, always defaulting to 27017) and as many hosts as desired may be connected to. Host names are comma-separated and the constructor will return successfully if it connected to at least one host. If it could not connect to any of the hosts, it will throw a MongoConnectionException.
Finally, if you specified a username and password, you may specify a database to authenticate with. If db is not specified, "admin" will be used.
Parametry
-
server -
The server name.
-
options -
An array of options for the connection. Currently available options include:
-
"connect"
If the constructor should connect before returning. Default is
TRUE. -
"timeout"
For how long the driver should try to connect to the database (in milliseconds).
-
"replicaSet"
The name of the replica set to connect to. If this is given, the master will be determined by using the ismaster database command on the seeds, so the driver may end up connecting to a server that was not even listed. See the replica set example below for details.
-
"username"
The username can be specified here, instead of including it in the host list. This is especially useful if a username has a ":" in it. This overrides a username set in the host list.
-
"password"
The password can be specified here, instead of including it in the host list. This is especially useful if a password has a "@" in it. This overrides a password set in the host list.
-
"db"
The database to authenticate against can be specified here, instead of including it in the host list. This overrides a database given in the host list.
-
Zwracane wartości
Returns a new database connection object.
Błędy/Wyjątki
Throws MongoConnectionException if it tries and fails to connect to the database for all hostnames given. It will also throw a MongoConnnectionException if an invalid username or password is given. See MongoConnectionException documentation for common exceptions and their causes.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 1.2.0 |
Removed the persist option, as all connections are now persistent. It can still be used, but it doesn't affect anything.
The "replicaSet" parameter now takes a string, not a boolean (although boolean is still accepted). |
| 1.0.2 |
Changed constructor to take an array of options. Pre-1.0.2, the
constructor took the following parameters:
|
| 1.0.9 | Added the replicaSet option. |
| 1.2.0 | Added the username and password options. |
Przykłady
Przykład #1 Mongo::__construct() replica set example
This example shows how to connect the driver to a replica set. It assumes that there is a set of three servers: sf1.example.com, sf2.example.com, and ny1.example.com. The master could be any one of these servers.
<?php
// pass a comma-separated list of server names to the constructor
$m1 = new Mongo("mongodb://sf2.example.com,ny1.example.com", array("replicaSet" => "myReplSet"));
// you only need to pass a single seed, the driver will derive the full list and
// find the master from this seed
$m2 = new Mongo("mongodb://ny1.example.com", array("replicaSet" => "myReplSet"));
?>
If the current master fails, the driver will figure out which secondary server became the new master and automatically start using that connection. Automatic failover will not work correctly if replicaSet is not specified.
At least one seed in the seed list must be up for the driver to connect to the replica set.
If you include seeds from two separate replica sets, behavior is undefined.
See the » core documentation on replica sets for more information.
Przykład #2 Connecting to a domain socket
In version 1.0.9+, you can use a UNIX domain socket to connect to an instance of MongoDB running locally. This should be slightly faster than using a network connection.
In version 1.5.0, the MongoDB server automatically opens a socket at /tmp/mongodb-<port>.sock. You can connect to this by specifying the path in your connection string:
<?php
// MongoDB server running locally on port 20000
$m = new Mongo("mongodb:///tmp/mongodb-20000.sock");
?>
You can combine this with any other connections you'd like:
<?php
// try to connect to the domain socket, fall back to localhost connection
$m = new MongoDB("mongodb:///tmp/mongodb-27017.sock,localhost:27017");
?>
Przykład #3 Mongo::__construct() authentication example
A user must exist in the admin database before attempting to use authentication. You can create one with the Mongo shell by running:
> use admin
switched to db admin
> db.addUser("testUser", "testPass");
{
"_id" : ObjectId("4b21272fd9ab21611d19095c"),
"user" : "testUser",
"pwd" : "03b9b27e0abf1865e2f6fcbd9845dd59"
}
>
After creating a user with, in this case, username "testUser" and password "testPass", you can create an authenticated connection:
<?php
$m = new Mongo("mongodb://testUser:testPass@localhost");
?>
Mongo::dropDB
(PECL mongo >=0.9.0)
Mongo::dropDB — Drops a database [deprecated]
Parametry
-
db -
The database to drop. Can be a MongoDB object or the name of the database.
Zwracane wartości
Returns the database response.
Mongo::__get
(PECL mongo >=1.0.2)
Mongo::__get — Gets a database
Opis
This is the cleanest way of getting a database. If the database name has any special characters, Mongo::selectDB() will need to be used. However, in most cases, this should be sufficient.
<?php
$mongo = new Mongo();
// the following two lines are equivalent
$db = $mongo->selectDB("foo");
$db = $mongo->foo;
?>
Parametry
-
dbname -
The database name.
Zwracane wartości
Returns a new db object.
Błędy/Wyjątki
Throws a generic exception if the database name is invalid.
Mongo::getHosts
(PECL mongo >=1.1.0)
Mongo::getHosts — Updates status for all hosts associated with this
Opis
This method can only be used with a connection to a replica set. It returns the status of all of the hosts in the set.
See the query section of this manual for information on distributing reads to slaves.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns an array of information about the hosts in the set. Includes each host's hostname, its health (1 is healthy), its state (1 is primary, 2 is secondary, 0 is anything else), the amount of time it took to ping the server, and when the last ping occurred. For example, on a three-member replica set, it might look something like:
array(2) {
["A:27017"]=>
array(4) {
["health"]=>
int(1)
["state"]=>
int(2)
["ping"]=>
int(369)
["lastPing"]=>
int(1309470644)
}
["B:27017"]=>
array(4) {
["health"]=>
int(1)
["state"]=>
int(1)
["ping"]=>
int(139)
["lastPing"]=>
int(1309470644)
}
["C:27017"]=>
array(4) {
["health"]=>
int(1)
["state"]=>
int(2)
["ping"]=>
int(1012)
["lastPing"]=>
int(1309470644)
}
}
In the example above, B and C are secondaries (state 2). B is likely to be selected for queries if slaveOkay is set, as it has a lower ping time (and thus is likely closer or handling less load) than C.
Mongo::getPoolSize
(No version information available, might only be in SVN)
Mongo::getPoolSize — Get pool size for connection pools
Opis
This feature has been DEPRECATED as of version 1.2.3. Relying on this feature is highly discouraged. Please use MongoPool::getSize() instead.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the current pool size.
Przykłady
Przykład #1 Changing pool size
This returns the default pool size, sets a new pool size, then prints the new pool size and the pool debugging information. Note that changing the pool size only affects new connection pools, it does not change old ones.
<?php
$connection = new Mongo("host1");
// pool size is -1
echo "pool size is: ".Mongo::getPoolSize()."\n";
echo "setting pool size to 200\n";
Mongo::setPoolSize(200);
// pool size is 200
echo "pool size is: ".Mongo::getPoolSize()."\n";
$conn2 = new Mongo("host2");
// remaining for host1 is -2
// remaining for host2 is 199
var_dump(Mongo::poolDebug());
?>
Zobacz też:
- Mongo::setPoolSize() - Set the size for future connection pools.
- Mongo::poolDebug() - Returns information about all connection pools.
- The connection documentation.
Mongo::getSlave
(PECL mongo >=1.1.0)
Mongo::getSlave — Returns the address being used by this for slaveOkay reads
Opis
This finds the address of the slave currently being used for reads. It is a read-only method: it does not change anything about the internal state of the object.
When you create a connection to the database, the driver will not immediately
decide on a slave to use. Thus, after you connect, this function will return
NULL even if there are slaves available. When you first do a query with
slaveOkay set, at that point the driver will choose a slave for this
connection. At that point, this function will return the chosen slave.
See the query section of this manual for information on distributing reads to slaves.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
The address of the slave this connection is using for reads.
This returns NULL if this is not connected to a replica set or not yet
initialized.
Mongo::getSlaveOkay
(PECL mongo >=1.1.0)
Mongo::getSlaveOkay — Get slaveOkay setting for this connection
Opis
See the query section of this manual for information on distributing reads to slaves.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the value of slaveOkay for this instance.
Mongo::listDBs
(PECL mongo >=1.0.4)
Mongo::listDBs — Lists all of the databases available.
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns an associative array containing three fields. The first field is databases, which in turn contains an array. Each element of the array is an associative array corresponding to a database, giving the database's name, size, and if it's empty. The other two fields are totalSize (in bytes) and ok, which is 1 if this method ran successfully.
Przykłady
Przykład #1 Mongo::listDBs() example
Example demonstrating how to use listDBs and the returned data structure.
<?php
$mongo = new Mongo();
$dbs = $mongo->listDBs();
print_r($dbs);
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[databases] => Array
(
[0] => Array
(
[name] => doctrine
[sizeOnDisk] => 218103808
[empty] =>
)
)
[totalSize] => 218103808
[ok] => 1
)
Mongo::poolDebug
(No version information available, might only be in SVN)
Mongo::poolDebug — Returns information about all connection pools.
Opis
This feature has been DEPRECATED as of version 1.2.3. Relying on this feature is highly discouraged. Please use MongoPool::info() instead.
Returns an array of information about all connection pools.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Each connection pool has an identifier, which starts with the host. For each pool, this function shows the following fields:
-
in use -
The number of connections currently being used by Mongo instances.
-
in pool -
The number of connections currently in the pool (not being used).
-
remaining -
The number of connections that could be created by this pool. For example, suppose a pool had 5 connections remaining and 3 connections in the pool. We could create 8 new instances of Mongo before we exhausted this pool (assuming no instances of Mongo went out of scope, returning their connections to the pool).
A negative number means that this pool will spawn unlimited connections.
Before a pool is created, you can change the max number of connections by calling Mongo::setPoolSize(). Once a pool is showing up in the output of this function, its size cannot be changed.
-
timeout -
The socket timeout for connections in this pool. This is how long connections in this pool will attempt to connect to a server before giving up.
Mongo::selectCollection
(PECL mongo >=0.9.0)
Mongo::selectCollection — Gets a database collection
Opis
Parametry
-
db -
The database name.
-
collection -
The collection name.
Zwracane wartości
Returns a new collection object.
Błędy/Wyjątki
Throws InvalidArgumentException if the database or collection name is invalid.
Przykłady
Przykład #1 Mongo::selectCollection() example
<?php
$m = new Mongo();
$c1 = $m->selectCollection("foo", "bar.baz");
// which is equivalent to
$c2 = $m->selectDB("foo")->selectCollection("bar.baz");
// $c1 and $c2 now represent the same collection
?>
Mongo::selectDB
(PECL mongo >=0.9.0)
Mongo::selectDB — Gets a database
Opis
Parametry
-
name -
The database name.
Zwracane wartości
Returns a new db object.
Błędy/Wyjątki
Throws InvalidArgumentException if the database name is invalid.
Mongo::setPoolSize
(No version information available, might only be in SVN)
Mongo::setPoolSize — Set the size for future connection pools.
Opis
$size
)This feature has been DEPRECATED as of version 1.2.3. Relying on this feature is highly discouraged. Please use MongoPool::setSize() instead.
Sets the max number of connections new pools will be able to create.
Parametry
-
size -
The max number of connections future pools will be able to create. Negative numbers mean that the pool will spawn an infinite number of connections.
Zwracane wartości
Returns the former value of pool size.
Przykłady
Przykład #1 Mongo::setPoolSize() example
If you set the pool size to n and then create n connections, attempting to create an n+1st connection will throw a MongoConnectionException.
<?php
// only allow one connection to a server
Mongo::setPoolSize(1);
// creates one connection to localhost:27017
$m1 = new Mongo();
// attempt to create a second connection to localhost:27017
// only one connection is allowed, so this will throw an exception
$m2 = new Mongo();
?>
Powyższy przykład wyświetli coś podobnego do:
Fatal error: Uncaught exception 'MongoConnectionException' with message 'no more connections in pool' in /path/to/php/script.php:10
Stack trace:
#0 /path/to/php/script.php(10): Mongo->__construct()
#1 {main}
thrown in /path/to/php/script.php on line 10
Zobacz też:
- Mongo::getPoolSize() - Get pool size for connection pools
- Mongo::poolDebug() - Returns information about all connection pools.
- The connection documentation.
Mongo::setSlaveOkay
(PECL mongo >=1.1.0)
Mongo::setSlaveOkay — Change slaveOkay setting for this connection
Opis
$ok = true
] )See the query section of this manual for information on distributing reads to slaves.
Parametry
-
ok -
If reads should be sent to secondary members of a replica set for all possible queries using this Mongo instance.
Zwracane wartości
Returns the former value of slaveOkay for this instance.
Mongo::switchSlave
(PECL mongo >=1.1.0)
Mongo::switchSlave — Choose a new slave for slaveOkay reads
Opis
This choses a random slave for a connection to read from. It is called automatically by the driver and should not need to be used. It calls Mongo::getHosts() (to refresh the status of hosts) and Mongo::getSlave() (to get the return value).
See the query section of this manual for information on distributing reads to slaves.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
The address of the slave this connection is using for reads. This may be the same as the previous address as addresses are randomly chosen. It may return only one address if only one secondary (or only the primary) is available.
For example, if we had a three member replica set with a primary, secondary, and arbiter this method would always return the address of the secondary. If the secondary became unavailable, this method would always return the address of the primary. If the primary also became unavailable, this method would throw an exception, as an arbiter cannot handle reads.
Błędy/Wyjątki
Throws a MongoException (error code 15) if it is called on a non-replica-set connection. It will also throw MongoExceptions if it cannot find anyone (primary or secondary) to read from (error code 16).
Mongo::__toString
(PECL mongo >=0.9.0)
Mongo::__toString — String representation of this connection
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns hostname and port for this connection.
Spis treści
- Mongo::close — Closes this connection
- Mongo::connect — Connects to a database server
- Mongo::connectUtil — Connects with a database server
- Mongo::__construct — Creates a new database connection object
- Mongo::dropDB — Drops a database [deprecated]
- Mongo::__get — Gets a database
- Mongo::getHosts — Updates status for all hosts associated with this
- Mongo::getPoolSize — Get pool size for connection pools
- Mongo::getSlave — Returns the address being used by this for slaveOkay reads
- Mongo::getSlaveOkay — Get slaveOkay setting for this connection
- Mongo::listDBs — Lists all of the databases available.
- Mongo::poolDebug — Returns information about all connection pools.
- Mongo::selectCollection — Gets a database collection
- Mongo::selectDB — Gets a database
- Mongo::setPoolSize — Set the size for future connection pools.
- Mongo::setSlaveOkay — Change slaveOkay setting for this connection
- Mongo::switchSlave — Choose a new slave for slaveOkay reads
- Mongo::__toString — String representation of this connection
The MongoDB class
(No version information available, might only be in SVN)
Wstęp
Instances of this class are used to interact with a database. To get a database:
<?php
$m = new Mongo(); // connect
$db = $m->selectDB("example");
?>
A few unusual, but valid, database names: "null", "[x,y]", "3", "\"", "/".
Unlike collection names, database names may contain "$".
Krótki opis klasy
$name
[, bool $capped = FALSE
[, int $size = 0
[, int $max = 0
]]] )$preserve_cloned_files = FALSE
[, bool $backup_original_files = FALSE
]] )Stałe predefiniowane
MongoDB Log Levels
-
MongoDB::PROFILING_OFF0 - Profiling is off.
-
MongoDB::PROFILING_SLOW1 - Profiling is on for slow operations (>100 ms).
-
MongoDB::PROFILING_ON2 - Profiling is on for all operations.
Fields
-
w
1 -
The number of servers to replicate a change to before returning success. Inherited by instances of MongoCollection derived from this. w functionality is only available in version 1.5.1+ of the MongoDB server and 1.0.8+ of the driver.
w is used whenever you perform a "safe" operation (MongoCollection::insert(), MongoCollection::update(), MongoCollection::remove(), MongoCollection::save(), and MongoCollection::ensureIndex() all support safe options). With the default value (1), a safe operation will return once the database server has the operation. If the server goes down before the operation has been replicated to a slave, it is possible to lose the operation forever. Thus, you can specify w to be higher than one and guarantee that at least one slave has the operation before it is considered successful.
For example, if w is 2, the main server and one slave must have a record of the operation or the driver will throw a MongoCursorException. It is tempting to set w to the total number of slaves + master, but then if one slave is down the op will fail and an exception will be thrown, so usually w=2 is safest (master+1 slave).
-
wtimeout
10000 -
The number of milliseconds to wait for MongoDB::$w replications to take place. Inherited by instances of MongoCollection derived from this. w functionality is only available in version 1.5.1+ of the MongoDB server and 1.0.8+ of the driver.
Unless wtimeout is set, the server waits forever for replicating to w servers to finish. The driver defaults to waiting for 10 seconds, you can change this value to alter its behavior.
Zobacz też:
MongoDB core docs on » databases.
MongoDB::authenticate
(PECL mongo >=1.0.1)
MongoDB::authenticate — Log in to this database
Opis
$username
, string $password
)This method causes its connection to be authenticated. If authentication is enabled for the database server (it's not, by default), you need to log in before the database will allow you to do anything.
In general, you should use the authenticate built into Mongo::__construct() in preference to this method. If you authenticate on connection and the connection drops and reconnects during your session, you'll be reauthenticated. If you manually authenticated using this method and the connection drops, you'll have to call this method again once you're reconnected.
This method is identical to running:
<?php
$salted = "${username}:mongo:${password}";
$hash = md5($salted);
$nonce = $db->command(array("getnonce" => 1));
$saltedHash = md5($nonce["nonce"]."${username}${hash}");
$result = $db->command(array("authenticate" => 1,
"user" => $username,
"nonce" => $nonce["nonce"],
"key" => $saltedHash
));
?>
Once a connection has been authenticated, it can only be un-authenticated by using the "logout" database command:
<?php
$db->command(array("logout" => 1));
?>
Parametry
-
username -
The username.
-
password -
The password (in plaintext).
Zwracane wartości
Returns database response. If the login was successful, it will return
<?php
array("ok" => 1);
?>
<?php
array("ok" => 0, "errmsg" => "auth fails");
?>
Zobacz też:
MongoDB core docs on » authenticate.
MongoDB::command
(PECL mongo >=0.9.2)
MongoDB::command — Execute a database command
Opis
$command
[, array $options = array()
] )Almost everything that is not a CRUD operation can be done with a database command. Need to know the database version? There's a command for that. Need to do aggregation? There's a command for that. Need to turn up logging? You get the idea.
This method is identical to:
<?php
public function command($data) {
return $this->selectCollection('$cmd')->findOne($data);
}
?>
Parametry
-
command -
The query to send.
-
options -
This parameter is an associative array of the form array("optionname" => <boolean>, ...). Currently supported options are:
-
"timeout"
Integer, defaults to Mongo::$timeout. If "safe" is set, this sets how long (in milliseconds) for the client to wait for a database response. If the database does not respond within the timeout period, a MongoCursorTimeoutException will be thrown.
-
Rejestr zmian
| Wersja | Opis |
|---|---|
| 1.2.0 | Added options parameter with a single option: timeout. |
Zwracane wartości
Returns database response.
Przykłady
Przykład #1 MongoDB::command() "distinct" example
Finding all of the distinct values for a key.
<?php
$people = $db->people;
$people->insert(array("name" => "Joe", "age" => 4));
$people->insert(array("name" => "Sally", "age" => 22));
$people->insert(array("name" => "Dave", "age" => 22));
$people->insert(array("name" => "Molly", "age" => 87));
$ages = $db->command(array("distinct" => "people", "key" => "age"));
foreach ($ages['values'] as $age) {
echo "$age\n";
}
?>
Powyższy przykład wyświetli coś podobnego do:
4
22
87
Przykład #2 MongoDB::command() "distinct" example
Finding all of the distinct values for a key, where the value is larger than or equal to 18.
<?php
$people = $db->people;
$people->insert(array("name" => "Joe", "age" => 4));
$people->insert(array("name" => "Sally", "age" => 22));
$people->insert(array("name" => "Dave", "age" => 22));
$people->insert(array("name" => "Molly", "age" => 87));
$ages = $db->command(
array(
"distinct" => "people",
"key" => "age",
"query" => array("age" => array('$gte' => 18))
)
);
foreach ($ages['values'] as $age) {
echo "$age\n";
}
?>
Powyższy przykład wyświetli coś podobnego do:
22
87
Przykład #3 MongoDB::command() MapReduce example
Get all users with at least on "sale" event, and how many times each of these users has had a sale.
<?php
// sample event document
$events->insert(array("user_id" => $id,
"type" => $type,
"time" => new MongoDate(),
"desc" => $description));
// construct map and reduce functions
$map = new MongoCode("function() { emit(this.user_id,1); }");
$reduce = new MongoCode("function(k, vals) { ".
"var sum = 0;".
"for (var i in vals) {".
"sum += vals[i];".
"}".
"return sum; }");
$sales = $db->command(array(
"mapreduce" => "events",
"map" => $map,
"reduce" => $reduce,
"query" => array("type" => "sale"),
"out" => array("merge" => "eventCounts")));
$users = $db->selectCollection($sales['result'])->find();
foreach ($users as $user) {
echo "{$user['_id']} had {$user['value']} sale(s).\n";
}
?>
Powyższy przykład wyświetli coś podobnego do:
User 47cc67093475061e3d9536d2 had 3 sale(s).
User 49902cde5162504500b45c2c had 14 sale(s).
User 4af467e4fd543cce7b0ea8e2 had 1 sale(s).
Informacja: Using MongoCode
This example uses MongoCode, which can also take a scope argument. However, at the moment, MongoDB does not support using scopes in MapReduce. If you would like to use client-side variables in the MapReduce functions, you can add them to the global scope by using the optional scope field with the database command. See the » MapReduce documentation for more information.
Informacja: The out argument
Before 1.8.0, the out argument was optional. If you did not use it, MapReduce results would be written to a temporary collection, which would be deleted when your connection was closed. In 1.8.0+, the out argument is required. See the » MapReduce documentation for more information.
If you are going to be using MapReduce, Prajwal Tuladhar created an API for Mongo PHP users which provides a nicer interface than the bare command. You can download it from » Github and there is a » blog post on how to use it.
Zobacz też:
MongoDB core docs on » database commands and on individual commands: » findAndModify, » getLastError, and » repair (dozens more exist, there are merely a few examples).
MongoDB::__construct
(PECL mongo >=0.9.0)
MongoDB::__construct — Creates a new database
Opis
This method is not meant to be called directly. The preferred way to create an instance of MongoDB is through Mongo::__get() or Mongo::selectDB().
If you're ignoring the previous paragraph and want to call it directly you can do so:
<?php
$m = new Mongo();
$db = new MongoDB($m, 'mydbname');
?>
But don't. Isn't this much nicer:
<?php
$m = new Mongo();
$db = $m->mydbname;
// or, if the name contains weird characters:
$db = $m->selectDB('my,db:name');
?>
Zwracane wartości
Returns the database.
Błędy/Wyjątki
Throws default exception if the database name is invalid.
MongoDB::createCollection
(PECL mongo >=0.9.0)
MongoDB::createCollection — Creates a collection
Opis
$name
[, bool $capped = FALSE
[, int $size = 0
[, int $max = 0
]]] )This method is used to create capped collections and other collections requiring special options. It is identical to running:
<?php
$collection = $db->command(array("create" => $name, "size" => $size, "capped" => $capped, "max" => $max));
?>
Parametry
-
name -
The name of the collection.
-
capped -
If the collection should be a fixed size.
-
size -
If the collection is fixed size, its size in bytes.
-
max -
If the collection is fixed size, the maximum number of elements to store in the collection.
Zwracane wartości
Returns a collection object representing the new collection.
Przykłady
Przykład #1 MongoDB::createCollection() capped collection example
A capped collection is a special type of collection that has either a fixed or a fixed number of elements. Once the collection is "full," the oldest elements will be removed when new elements are added. Capped collections can be very useful for applications like logging, where you may want to reserve a certain amount of space for logs and not worry about them getting too big.
This example creates a very tiny log collection that will keep a maximum of 10 documents.
<?php
$log = $db->createCollection("logger", true, 10*1024, 10);
for ($i = 0; $i < 100; $i++) {
$log->insert(array("level" => WARN, "msg" => "sample log message #$i", "ts" => new MongoDate()));
}
$msgs = $log->find();
foreach ($msgs as $msg) {
echo $msg['msg']."\n";
}
?>
Powyższy przykład wyświetli coś podobnego do:
sample log message #90
sample log message #91
sample log message #92
sample log message #93
sample log message #94
sample log message #95
sample log message #96
sample log message #97
sample log message #98
sample log message #99
MongoDB::createDBRef
(PECL mongo >=0.9.0)
MongoDB::createDBRef — Creates a database reference
Opis
This method is a flexible interface for creating database refrences (see MongoDBRef).
Parametry
-
collection -
The collection to which the database reference will point.
-
a -
Object or _id to which to create a reference. If an object or associative array is given, this will create a reference using the _id field.
Zwracane wartości
Returns a database reference array.
Przykłady
Przykład #1 MongoDB::createDBRef() example
Example demonstrating how to programatically create a DB reference array from a document.
<?php
$articles = $db->articles;
$article = array(
'title' => 'Test article',
'description' => 'Test article description'
);
$articles->insert($article);
$ref = $db->createDBRef('articles', $article);
print_r($article);
print_r($ref);
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[title] => Test article
[description] => Test article description
[_id] => MongoId Object
(
)
)
Array
(
[$ref] => articles
[$id] => MongoId Object
(
)
)
Now the $ref can be stored on another document and retrieved later with MongoDB::getDBRef() or MongoCollection::getDBRef().
Przykład #2 MongoDB::createDBRef() example
Example demonstrating how to programatically create a DB reference from just an id.
<?php
$id = new MongoId('47cc67093475061e3d9536d2');
$ref = $db->createDBRef('articles', $id);
?>
MongoDB::drop
(PECL mongo >=0.9.0)
MongoDB::drop — Drops this database
Opis
This drops the database currently being used.
This is identical to running:
<?php
public function drop() {
$this->command(array("dropDatabase" => 1));
}
?>
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the database response.
Przykłady
Przykład #1 MongoDB::drop() example
This example demonstrates how to drop a mongo database and the response to expect.
<?php
$db = $mongo->foo;
$response = $db->drop();
print_r($response);
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[dropped] => foo.$cmd
[ok] => 1
)
MongoDB::dropCollection
(PECL mongo >=0.9.0)
MongoDB::dropCollection — Drops a collection [deprecated]
Opis
Deprecated
Use MongoCollection::drop() instead.
This function leaks memory in version 1.0.7 and earlier!
Parametry
-
coll -
MongoCollection or name of collection to drop.
Zwracane wartości
Returns the database response.
MongoDB::execute
(PECL mongo >=0.9.3)
MongoDB::execute — Runs JavaScript code on the database server.
Opis
The Mongo database server runs a JavaScript engine. This method allows you to run arbitary JavaScript on the database. This can be useful if you want touch a number of collections lightly, or process some results on the database side to reduce the amount that has to be sent to the client.
Running JavaScript in the database takes a write lock, meaning it blocks other operations. Make sure you consider this before running a long script.
This is a wrapper for a database command. This method is basically:
<?php
public function execute($code, $args) {
return $this->command(array('$eval' => $code, args => $args));
}
?>
MongoDB implies a return statement if you have a single statement on a single line. This can cause some unintuitive behavior. For example, this returns "foo":
<?php
$db->execute('"foo";');
?>
However, these return NULL:
<?php
$db->execute('"bar"; "foo";'); // more than one statement
$db->execute('db.foo.count(
);'); // more than one line
?>
To avoid surprising behavior, it is best not to depend on MongoDB to decide what to return, but to explicitly state a return value. In the examples above, we can change them to:
<?php
$db->execute('"bar"; return "foo";');
$db->execute('return db.foo.count(
);');
?>
Now the first statement will return "foo" and the second statement will return a count of the "foo" collection.
Zwracane wartości
Returns the result of the evaluation.
Przykłady
Przykład #1 Simple MongoDB::execute() example
<?php
$response = $db->execute("function() { return 'Hello, world!'; }");
echo $response['retval'];
?>
Powyższy przykład wyświetli coś podobnego do:
Hello, world!
Przykład #2 Parameter MongoDB::execute() example
The optional array of parameters will be passed to the JavaScript function.
<?php
$response = $db->execute("function(greeting, name) { return greeting+', '+name+'!'; }", array("Good bye", "Joe"));
echo $response['retval'];
?>
Powyższy przykład wyświetli coś podobnego do:
Good bye, Joe!
Przykład #3 Scope example
If a MongoCode object is used instead of a string for the first parameter, a scope can be passed in which the JavaScript will be executed.
<?php
$func =
"function(greeting, name) { ".
"return greeting+', '+name+', says '+greeter;".
"}";
$scope = array("greeter" => "Fred");
$code = new MongoCode($func, $scope);
$response = $db->execute($code, array("Goodbye", "Joe"));
echo $response['retval'];
?>
Powyższy przykład wyświetli coś podobnego do:
Goodbye, Joe, says Fred
MongoDB::forceError
(PECL mongo >=0.9.5)
MongoDB::forceError — Creates a database error
Opis
This method is not very useful for normal MongoDB use. It forces a database error to occur. This means that MongoDB::lastError() will return a generic database error after running this command.
This command is identical to running:
<?php
public function forceError() {
return $this->command(array('forceerror' => 1));
}
?>
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the database response.
MongoDB::__get
(PECL mongo >=1.0.2)
MongoDB::__get — Gets a collection
Opis
This is the easiest way of getting a collection from a database object. If a collection name contains strange characters, you may have to use MongoDB::selectCollection() instead.
<?php
$mongo = new Mongo();
// the following two lines are equivalent
$collection = $mongo->selectDB("foo")->selectCollection("bar");
$collection = $mongo->foo->bar;
?>
Parametry
-
name -
The name of the collection.
Zwracane wartości
Returns the collection.
MongoDB::getDBRef
(PECL mongo >=0.9.0)
MongoDB::getDBRef — Fetches the document pointed to by a database reference
Opis
$ref
)Parametry
-
ref -
A database reference.
Zwracane wartości
Returns the document pointed to by the reference.
Przykłady
Przykład #1 MongoDB::getDBRef() example
Example demonstrating how to get a database reference and what the expected input is.
<?php
$ref = array(
'$ref' => 'profiles',
'$id' => '47cc67093475061e3d9536d2'
);
$profile = $db->getDBRef($ref);
?>
See MongoDB::createDBRef() for more information about how to programatically create DB references.
MongoDB::getGridFS
(PECL mongo >=0.9.0)
MongoDB::getGridFS — Fetches toolkit for dealing with files stored in this database
Opis
Parametry
-
prefix -
The prefix for the files and chunks collections.
Zwracane wartości
Returns a new gridfs object for this database.
Przykłady
Przykład #1 MongoDB::getGridFS() example
This example demonstrates how get a MongoGridFS instance.
<?php
$db = $mongo->my_db;
$prefix = 'files';
$collection = $db->getGridFS($prefix);
?>
Read more about the MongoGridFS to learn how to store files with MongoDB.
MongoDB::getProfilingLevel
(PECL mongo >=0.9.0)
MongoDB::getProfilingLevel — Gets this database's profiling level
Opis
This returns the current database profiling level.
The database profiler tracks query execution times. If you turn it on (say, using MongoDB::setProfilingLevel() or the shell), you can see how many queries took longer than a given number of milliseconds or the timing for all queries.
Note that profiling slows down queries, so it is better to use in development or testing than in a time-sensitive application.
This function is equivalent to running:
<?php
public function getProfilingLevel() {
return $this->command(array('profile' => -1));
}
?>
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the profiling level.
Zobacz też:
MongoDB core docs on » profiling and MongoDB::setProfilingLevel() - Sets this database's profiling level.
MongoDB::getSlaveOkay
(PECL mongo >=1.1.0)
MongoDB::getSlaveOkay — Get slaveOkay setting for this database
Opis
See the query section of this manual for information on distributing reads to slaves.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the value of slaveOkay for this instance.
MongoDB::lastError
(PECL mongo >=0.9.5)
MongoDB::lastError — Check if there was an error on the most recent db operation performed
Opis
This method is equivalent to:
<?php
public function lastError() {
return $this->command(array('getlasterror' => 1));
}
?>
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the error, if there was one.
Przykłady
Przykład #1 MongoDB::lastError() NULL error example
<?php
$db->resetError();
var_dump($db->lastError());
?>
Powyższy przykład wyświetli coś podobnego do:
array(3) {
["err"]=>
NULL
["n"]=>
int(0)
["ok"]=>
float(1)
}
Przykład #2 MongoDB::lastError() duplicate key example
<?php
$c = $db->selectCollection("foo");
// insert two documents with the same _id
$c->insert(array("_id" => 1));
$c->insert(array("_id" => 1));
var_dump($db->lastError());
?>
Powyższy przykład wyświetli coś podobnego do:
array(3) {
["err"]=>
string(64) "E11000 duplicate key errorindex: foo.foo.$_id_ dup key: { : 1 }"
["n"]=>
int(0)
["ok"]=>
float(1)
}
MongoDB::listCollections
(PECL mongo >=0.9.0)
MongoDB::listCollections — Get a list of collections in this database
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns a list of MongoCollections.
Przykłady
Przykład #1 MongoDB::listCollections() example
The following example demonstrates dropping each collection in a database.
<?php
$m = new Mongo();
$db = $m->selectDB("sample");
$list = $db->listCollections();
foreach ($list as $collection) {
echo "removing $collection... ";
$collection->drop();
echo "gone\n";
}
?>
Powyższy przykład wyświetli coś podobnego do:
removing sample.blog.posts... gone removing sample.critical.docs... gone removing sample.taxes... gone ...
MongoDB::prevError
(PECL mongo >=0.9.5)
MongoDB::prevError — Checks for the last error thrown during a database operation
Opis
MongoDB::lastError() is usually preferred to this. This method returns the last database error that occurred and how many operations ago it occurred. It is mostly deprecated.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the error and the number of operations ago it occurred.
MongoDB::repair
(PECL mongo >=0.9.0)
MongoDB::repair — Repairs and compacts this database
Opis
$preserve_cloned_files = FALSE
[, bool $backup_original_files = FALSE
]] )This creates a fresh copy of all database data. It will remove any corrupt data and compact and large stretches of free space it finds. This is a very slow operation on a large database.
This is usually run from the shell or the command line, not the driver.
It is equivalent to the function:
<?php
public function repair() {
return $this->command(array('repairDatabase' => 1));
}
?>
Parametry
-
preserve_cloned_files -
If cloned files should be kept if the repair fails.
-
backup_original_files -
If original files should be backed up.
Zwracane wartości
Returns db response.
Zobacz też:
MongoDB core docs on » repair.
Przykłady
Przykład #1 MongoDB::repair() example
This example demonstrates how to repare and compact a database.
<?php
$db = $mongo->foo;
$response = $db->repair();
print_r($response);
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[ok] => 1
)
MongoDB::resetError
(PECL mongo >=0.9.5)
MongoDB::resetError — Clears any flagged errors on the database
Opis
This method is not used in normal operations. It resets the database error tracker (which can be incremented with MongoDB::forceError(), also not normally used).
It is equivalent to running:
<?php
public function resetError() {
return $this->command(array('reseterror' => 1));
}
?>
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the database response.
MongoDB::selectCollection
(PECL mongo >=0.9.0)
MongoDB::selectCollection — Gets a collection
Opis
Parametry
-
name -
The name of the collection.
Zwracane wartości
Returns the collection.
MongoDB::setProfilingLevel
(PECL mongo >=0.9.0)
MongoDB::setProfilingLevel — Sets this database's profiling level
Opis
$level
)This changes the current database profiling level.
This function is equivalent to running:
<?php
public function setProfilingLevel($level) {
return $this->command(array('profile' => $level));
}
?>
The options for level are 0 (off), 1 (queries > 100ms), and 2 (all queries). If you would like to profile queries that take longer than another time period, use the database command and pass it a second option, the number of milliseconds. For example, to profile all queries that take longer than one second, run:
<?php
$result = $this->command(array('profile' => 1, 'slowms' => 1000));
?>
Profiled queries will appear in the system.profile collection of this database.
Parametry
-
level -
Profiling level.
Zwracane wartości
Returns the previous profiling level.
MongoDB::setSlaveOkay
(PECL mongo >=1.1.0)
MongoDB::setSlaveOkay — Change slaveOkay setting for this database
Opis
$ok = true
] )See the query section of this manual for information on distributing reads to slaves.
Parametry
-
ok -
If reads should be sent to secondary members of a replica set for all possible queries using this MongoDB instance.
Zwracane wartości
Returns the former value of slaveOkay for this instance.
MongoDB::__toString
(PECL mongo >=0.9.0)
MongoDB::__toString — The name of this database
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns this database's name.
Spis treści
- MongoDB::authenticate — Log in to this database
- MongoDB::command — Execute a database command
- MongoDB::__construct — Creates a new database
- MongoDB::createCollection — Creates a collection
- MongoDB::createDBRef — Creates a database reference
- MongoDB::drop — Drops this database
- MongoDB::dropCollection — Drops a collection [deprecated]
- MongoDB::execute — Runs JavaScript code on the database server.
- MongoDB::forceError — Creates a database error
- MongoDB::__get — Gets a collection
- MongoDB::getDBRef — Fetches the document pointed to by a database reference
- MongoDB::getGridFS — Fetches toolkit for dealing with files stored in this database
- MongoDB::getProfilingLevel — Gets this database's profiling level
- MongoDB::getSlaveOkay — Get slaveOkay setting for this database
- MongoDB::lastError — Check if there was an error on the most recent db operation performed
- MongoDB::listCollections — Get a list of collections in this database
- MongoDB::prevError — Checks for the last error thrown during a database operation
- MongoDB::repair — Repairs and compacts this database
- MongoDB::resetError — Clears any flagged errors on the database
- MongoDB::selectCollection — Gets a collection
- MongoDB::setProfilingLevel — Sets this database's profiling level
- MongoDB::setSlaveOkay — Change slaveOkay setting for this database
- MongoDB::__toString — The name of this database
The MongoCollection class
(No version information available, might only be in SVN)
Wstęp
Representations a database collection.
Collection names can use any character in the ASCII set. Some valid collection names are "", "...", "my collection", and "*&#@".
User-defined collection names cannot contain the $ symbol. There are certain system collections which use a $ in their names (e.g., local.oplog.$main), but it is a reserved character. If you attempt to create and use a collection with a $ in the name, MongoDB will assert.
Krótki opis klasy
Stałe predefiniowane
-
MongoCollection::ASCENDING1 - Ascending direction for sorts and index creation.
-
MongoCollection::DESCENDING-1 - Descending direction for sorts and index creation.
Fields
- db
-
The "parent" database for this collection.
- w
-
The number of servers to replicate a change to before returning success. Value is inherited from the parent database. The MongoDB class has a more detailed description of how w works.
- wtimeout
-
The number of milliseconds to wait for $this->w replications to take place. Value is inherited from the parent database. The MongoDB class has a more detailed description of how wtimeout works.
Zobacz też:
MongoDB core docs on » collections.
MongoCollection::batchInsert
(PECL mongo >=0.9.0)
MongoCollection::batchInsert — Inserts multiple documents into this collection
Opis
Parametry
-
a -
An array of arrays.
-
options -
Options for the inserts.
-
"safe"
Can be a boolean or integer, defaults to
FALSE. IfFALSE, the program continues executing without waiting for a database response. IfTRUE, the program will wait for the database response and throw a MongoCursorException if the insert did not succeed.If safe is an integer, will replicate the insert to that many machines before returning success (or throw an exception if the replication times out, see wtimeout). This overrides the w variable set on the collection.
-
"fsync"
Boolean, defaults to
FALSE. Forces the insert to be synced to disk before returning success. IfTRUE, a safe insert is implied and will override setting safe toFALSE. -
"continueOnError"
Boolean, defaults to
FALSE. If set, the database will not stop processing a bulk insert if one fails (eg due to duplicate IDs). This makes bulk insert behave similarly to a series of single inserts, except that calling MongoDB::lastError() will have an error set if any insert fails, not just the last one. If multiple errors occur, only the most recent will be reported by MongoDB::lastError().
-
Zwracane wartości
If "safe" is set, returns an associative array with the status of the inserts
("ok") and any error that may have occured ("err"). Otherwise, returns
TRUE if the batch insert was successfully sent, FALSE otherwise.
Błędy/Wyjątki
Throws MongoCursorException if the "safe" option is set and the insert fails.
Throws MongoCursorTimeoutException if the "safe" option is set to a value greater than one and the database cannot replicate the operation in MongoCollection::$wtimeout milliseconds.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 1.0.5 | Added "options" parameter. |
| 1.0.9 | Added ability to pass integers to "safe" options (only accepted booleans before) and added "fsync" option. |
| 1.2.7 | The continueOnError flag has been added. |
Przykłady
Przykład #1 MongoCollection::batchInsert() example
Batch insertion is a quick way to add many elements to the database at once
<?php
$users = array();
for ($i = 0; $i<100; $i++) {
$users[] = array('username' => 'user'.$i, 'i' => $i);
}
$mongo = new Mongo();
$collection = $mongo->my_db->users;
$collection->drop();
$collection->batchInsert($users);
foreach ($users as $user) {
echo $user['_id']."\n"; // populated with instanceof MongoId
}
$users = $collection->find()->sort(array('i' => 1));
foreach ($users as $user) {
var_dump($user['username']);
}
?>
Powyższy przykład wyświetli coś podobnego do:
4bf43ac68ead0e1971000000 4bf43ac68ead0e1971010000 4bf43ac68ead0e1971020000 ... string(5) "user1" string(5) "user2" string(5) "user3" ...
Przykład #2 MongoCollection::batchInsert() example with ignoring errors
<?php
$con = new Mongo;
$db = $con->demo;
$doc1 = array(
'_id' => new MongoId('4cb4ab6d7addf98506010001'),
'id' => 1,
'desc' => "ONE",
);
$doc2 = array(
'_id' => new MongoId('4cb4ab6d7addf98506010002'),
'id' => 2,
'desc' => "TWO",
);
$doc3 = array(
'_id' => new MongoId('4cb4ab6d7addf98506010002'), // same _id as above
'id' => 3,
'desc' => "THREE",
);
$doc4 = array(
'_id' => new MongoId('4cb4ab6d7addf98506010004'),
'id' => 4,
'desc' => "FOUR",
);
$c = $db->selectCollection('c');
$c->batchInsert(
array($doc1, $doc2, $doc3, $doc4),
array('continueOnError' => true)
);
$docs = $c->find();
foreach ($docs as $doc) {
var_dump($doc['desc']);
}
?>
Powyższy przykład wyświetli coś podobnego do:
string(3) "ONE" string(3) "TWO" string(4) "FOUR"
Zobacz też:
- MongoCollection::insert() - Inserts an array into the collection
- MongoCollection::update() - Update records based on a given criteria
- MongoCollection::find() - Querys this collection, returning a MongoCursor for the result set
- MongoCollection::remove() - Remove records from this collection
- MongoDB core docs on » insert.
MongoCollection::__construct
(PECL mongo >=0.9.0)
MongoCollection::__construct — Creates a new collection
Opis
Zwracane wartości
Returns a new collection object.
Błędy/Wyjątki
Throws default exception if the collection name is invalid.
MongoCollection::count
(PECL mongo >=0.9.0)
MongoCollection::count — Counts the number of documents in this collection
Opis
$query = array()
[, int $limit = 0
[, int $skip = 0
]]] )Parametry
-
query -
Associative array or object with fields to match.
-
limit -
Specifies an upper limit to the number returned.
-
skip -
Specifies a number of results to skip before starting the count.
Zwracane wartości
Returns the number of documents matching the query.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 1.0.7 | Added limit and skip parameters. |
Przykłady
Przykład #1 MongoCollection::count() example
<?php
$collection->insert(array('x'=>1));
$collection->insert(array('x'=>2));
$collection->insert(array('x'=>3));
var_dump($collection->count());
var_dump($collection->count(array('x'=>1)));
?>
Powyższy przykład wyświetli coś podobnego do:
int(3) int(1)
MongoCollection::createDBRef
(PECL mongo >=0.9.0)
MongoCollection::createDBRef — Creates a database reference
Opis
$a
)Parametry
-
a -
Object to which to create a reference.
Zwracane wartości
Returns a database reference array.
Przykłady
Przykład #1 MongoCollection::createDBRef() example
<?php
$songs = $db->songs;
$playlists = $db->playlists;
// create a reference to a song
$manamana = $songs->findOne(array('title' => 'Ma na ma na'));
$refToSong = $songs->createDBRef($manamana);
// add the reference to my playlist
$playlists->update(array('username' => 'me'), array('$push' => array('songlist' => $refToSong)));
?>
MongoCollection::deleteIndex
(PECL mongo >=0.9.0)
MongoCollection::deleteIndex — Deletes an index from this collection
Opis
$keys
)This method is identical to:
<?php
public function deleteIndexes($keys) {
// toIndexString is a protected method that turns strings, arrays, and objs
//into index names
$index = $this->toIndexString($keys);
return $this->db->command(array("deleteIndexes" => $this->getName(),
"index" => $index);
}
?>
Each index, when created, is given a unique name. This is generally user-set (with MongoCollection::ensureIndex()'s "name" option) or generated by the driver from a combination of key names and directions. This name is then used by MongoCollection::deleteIndex() to remove the function.
Unfortunately, the MongoCollection::ensureIndex() generates slightly different names than the shell and, due to backwards compatibility issues, MongoCollection::deleteIndex() cannot delete custom-named indexes as well. Thus, the best way to delete indexes created in the shell or with custom names is to directly call the deleteIndexes database command.
Thus, if you named an index "superfast query", you could only delete it with the PHP driver by running:
<?php
$db->command(array("deleteIndexes" => $collection->getName(), "index" => "superfast query");
?>
To find what an index is named, you can query the system.indexes collection of a database and look for the name field.
Parametry
-
keys -
Field or fields from which to delete the index.
Zwracane wartości
Returns the generated name of the key if successful, or NULL otherwise.
Przykłady
Przykład #1 MongoCollection::deleteIndex() example
This example passes the function string and array parameters.
<?php
$m = new Mongo();
$c = $m->example->indices;
// create an index
$c->ensureIndex(array("i"=>1));
// remove a simple index
$c->deleteIndex("i");
// create a multi-key index
$c->ensureIndex(array("j" => 1, "k" => 1));
// remove a multi-key index
$c->deleteIndex(array("j" => 1, "k" => 1));
?>
MongoCollection::deleteIndexes
(PECL mongo >=0.9.0)
MongoCollection::deleteIndexes — Delete all indices for this collection
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the database response.
Przykłady
Przykład #1 MongoCollection::deleteIndexes() example
This example demonstrates how to delete all indexes from a collection and the response to expect.
<?php
$collection = $mongo->my_db->articles;
$response = $collection->deleteIndexes();
print_r($response);
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[nIndexesWas] => 1
[msg] => all indexes deleted for collection
[ok] => 1
)
MongoCollection::drop
(PECL mongo >=0.9.0)
MongoCollection::drop — Drops this collection
Opis
Drops this collection and deletes its indices.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the database response.
Przykłady
Przykład #1 MongoCollection::drop() example
This example demonstrates how to drop a collection and the response to expect.
<?php
$collection = $mongo->my_db->articles;
$response = $collection->drop();
print_r($response);
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[nIndexesWas] => 1
[msg] => all indexes deleted for collection
[ns] => my_db.articles
[ok] => 1
)
MongoCollection::ensureIndex
(PECL mongo >=0.9.0)
MongoCollection::ensureIndex — Creates an index on the given field(s), or does nothing if the index already exists
Opis
$key|keys
[, array $options = array()
] )This method creates an index on the collection and the specified fields. The key specification can either be just a single field name as string, or an array containing one or more field names with their sort direction.
Parametry
-
keys -
An array of fields by which to sort the index on. Each element in the array has as key the field name, and as value either 1 for ascending sort, or -1 for descending sort.
-
options -
This parameter is an associative array of the form array("optionname" => <boolean>, ...). Currently supported options are:
-
"unique"
Create a unique index.
OstrzeżenieA unique index cannot be created on a field if multiple existing documents do not contain the field. The field is effectively
NULLfor these documents and thus already non-unique. -
"dropDups"
If a unique index is being created and duplicate values exist, drop all but one duplicate value.
-
"background"
If you are using MongoDB version 1.3.2+, you can create indexes in the background while other operations are taking place. By default, index creation happens synchronously. If you specify
TRUEwith this option, index creation will be asynchronous. -
"safe"
Starting with driver version 1.0.4, you can specify a boolean value for checking if the index creation succeeded. The driver will throw a MongoCursorException if index creation failed.
If you are using replication and the master has changed, using "safe" will make the driver disconnect from the master, throw and exception, and attempt to find a new master on the next operation (your application must decide whether or not to retry the operation on the new master).
If you do not use "safe" with a replica set and the master changes, there will be no way for the driver to know about the change so it will continuously and silently fail to write.
-
"name"
Starting with driver version 1.0.5 you can specify an index name. This can be useful if you are indexing many keys and Mongo complains about the index name being too long.
-
"timeout"
Integer, defaults to MongoCursor::$timeout. If "safe" is set, this sets how long (in milliseconds) for the client to wait for a database response. If the database does not respond within the timeout period, a MongoCursorTimeoutException will be thrown.
-
Zwracane wartości
Returns TRUE.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 1.0.2 | Changed "options" parameter from boolean to array. Pre-1.0.2, the second parameter was an optional boolean value specifying a unique index. |
| 1.0.11 | "safe" will trigger master failover, if necessary. |
| 1.0.11 | MongoException will be thrown if index name (either generated or set) is longer than 128 bytes. |
| 1.2.0 | Added timeout option. |
| 1.3.0 |
The options parameter does no longer accept
just a boolean to signify a unique index. Instead, this now has to be done
with array('unique' => true).
|
Błędy/Wyjątki
Throws MongoException if the index name is longer than 128 bytes. (Version 1.0.11+)
Throws MongoCursorException if the "safe" option is set and the index creation fails.
Throws MongoCursorTimeoutException if the "safe" option is set and the operation takes longer than MongoCursor::$timeout milliseconds to complete. This does not kill the operation on the server, it is a client-side timeout.
Przykłady
Przykład #1 MongoCollection::ensureIndex() example
<?php
$c = new MongoCollection($db, 'foo');
// create an index on 'x' ascending
$c->ensureIndex('x');
// create an index on 'y' ascending
$c->ensureIndex(array('y' => 1));
// create an index on 'z' ascending and 'zz' descending
$c->ensureIndex(array('z' => 1, 'zz' => -1));
// create a unique index on 'x'
$c->ensureIndex(array('x' => 1), array("unique" => true));
?>
Przykład #2 Drop duplicates example
<?php
$collection->insert(array("username" => "joeschmoe"));
$collection->insert(array("username" => "joeschmoe"));
/*
* index creation fails, you can't create a unique index on a key with
* non-unique values
*/
$collection->ensureIndex(array("username" => 1), array("unique" => 1));
/*
* index creation succeeds: one of the documents is removed from the collection
*/
$collection->ensureIndex(array("username" => 1), array("unique" => 1, "dropDups" => 1));
/*
* now we have a unique index, more inserts with the same username (such as the
* one below) will fail
*/
$collection->insert(array("username" => "joeschmoe"));
?>
Przykład #3 Geospatial Indexing
Mongo supports geospatial indexes, which allow you to search for documents near a given location or within a shape. For example, to create a geospatial index on the "loc" field:
<?php
$collection->ensureIndex(array("loc" => "2d"));
?>
Zobacz też:
MongoDB core docs on » vanilla indexes and » geospatial indexes.
MongoCollection::find
(PECL mongo >=0.9.0)
MongoCollection::find — Querys this collection, returning a MongoCursor for the result set
Opis
Parametry
-
query -
The fields for which to search. MongoDB's query language is quite extensive. The PHP driver will in almost all cases pass the query straight through to the server, so reading the MongoDB core docs on » find is a good idea.
OstrzeżeniePlease make sure that for all special query operators (starting with $) you use single quotes so that PHP doesn't try to replace "$exists" with the value of the variable $exists.
-
fields -
Fields of the results to return. The array is in the format array('fieldname' => true, 'fieldname2' => true). The _id field is always returned.
Zwracane wartości
Returns a cursor for the search results.
Przykłady
Przykład #1 MongoCollection::find() example
This example demonstrates how to search for a range.
<?php
$m = new Mongo();
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'phpmanual');
// search for documents where 5 < x < 20
$rangeQuery = array('x' => array( '$gt' => 5, '$lt' => 20 ));
$cursor = $collection->find($rangeQuery);
foreach ($cursor as $doc) {
var_dump($doc);
}
?>
Powyższy przykład wyświetli:
array(2) {
["_id"]=>
object(MongoId)#10 (1) {
["$id"]=>
string(24) "4ebc3e3710b89f2349000000"
}
["x"]=>
int(12)
}
array(2) {
["_id"]=>
object(MongoId)#11 (1) {
["$id"]=>
string(24) "4ebc3e3710b89f2349000001"
}
["x"]=>
int(12)
}
See MongoCursor for more information how to work with cursors.
Przykład #2 MongoCollection::find() example using $where
This example demonstrates how to search a collection using javascript code to reduce the resultset.
<?php
$m = new Mongo();
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'phpmanual');
$js = "function() {
return this.name == 'Joe' || this.age == 50;
}";
$cursor = $collection->find(array('$where' => $js));
foreach ($cursor as $doc) {
var_dump($doc);
}
?>
Powyższy przykład wyświetli:
array(3) {
["_id"]=>
object(MongoId)#7 (1) {
["$id"]=>
string(24) "4ebc3e3710b89f2349000002"
}
["name"]=>
string(3) "Joe"
["age"]=>
int(20)
}
Przykład #3 MongoCollection::find() example using $in
This example demonstrates how to search a collection using the $in operator.
<?php
$m = new Mongo();
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'phpmanual');
$cursor = $collection->find(array(
'name' => array('$in' => array('Joe', 'Wendy'))
));
?>
Powyższy przykład wyświetli:
array(3) {
["_id"]=>
object(MongoId)#7 (1) {
["$id"]=>
string(24) "4ebc3e3710b89f2349000002"
}
["name"]=>
string(3) "Joe"
["age"]=>
int(20)
}
Przykład #4 Getting results as an array
This returns a MongoCursor. Often, when people are starting out, they are more comfortable using an array. To turn a cursor into an array, use the iterator_to_array() function.
<?php
$m = new Mongo();
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'phpmanual');
$cursor = $collection->find();
$array = iterator_to_array($cursor);
?>
Powyższy przykład wyświetli:
array(3) {
["4ebc40af10b89f5149000000"]=>
array(2) {
["_id"]=>
object(MongoId)#6 (1) {
["$id"]=>
string(24) "4ebc40af10b89f5149000000"
}
["x"]=>
int(12)
}
["4ebc40af10b89f5149000001"]=>
array(2) {
["_id"]=>
object(MongoId)#11 (1) {
["$id"]=>
string(24) "4ebc40af10b89f5149000001"
}
["x"]=>
int(12)
}
["4ebc40af10b89f5149000002"]=>
array(3) {
["_id"]=>
object(MongoId)#12 (1) {
["$id"]=>
string(24) "4ebc40af10b89f5149000002"
}
["name"]=>
string(3) "Joe"
["age"]=>
int(20)
}
}
Using iterator_to_array() forces the driver to load all of the results into memory, so do not do this for result sets that are larger than memory!
Also, certain system collections do not have an _id
field. If you are dealing with a collection that might have documents
without _ids, pass FALSE as the second argument to
iterator_to_array() (so that it will not try to use the
non-existent _id values as keys).
Zobacz też:
- MongoCollection::findOne() - Querys this collection, returning a single element
- MongoCollection::insert() - Inserts an array into the collection
- MongoDB core docs on » find.
MongoCollection::findOne
(PECL mongo >=0.9.0)
MongoCollection::findOne — Querys this collection, returning a single element
Opis
$query = array()
[, array $fields = array()
]] )As opposed to MongoCollection::find(), this method will return only the first result from the result set, and not a MongoCursor that can be iterated over.
Parametry
-
query -
The fields for which to search. MongoDB's query language is quite extensive. The PHP driver will in almost all cases pass the query straight through to the server, so reading the MongoDB core docs on » find is a good idea.
OstrzeżeniePlease make sure that for all special query operaters (starting with $) you use single quotes so that PHP doesn't try to replace "$exists" with the value of the variable $exists.
-
fields -
Fields of the results to return. The array is in the format array('fieldname' => true, 'fieldname2' => true). The _id field is always returned.
Zwracane wartości
Returns record matching the search or NULL.
Błędy/Wyjątki
Throws MongoConnectionException if it cannot reach the database.
Przykłady
Przykład #1 MongoCollection::findOne() document by its id.
This example demonstrates how to find a single document in a collection by its id.
<?php
$articles = $mongo->my_db->articles;
$article = $articles->findOne(array('_id' => new MongoId('47cc67093475061e3d9536d2')));
?>
Przykład #2 MongoCollection::findOne() document by some condition.
This example demonstrates how to find a single document in a collection by some condition and limiting the returned fields.
<?php
$users = $mongo->my_db->users;
$user = $users->findOne(array('username' => 'jwage'), array('password'));
print_r($user);
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[_id] => MongoId Object
(
)
[password] => test
)
Notice how even though the document does have a username field, we limited the results to only contain the password field.
Zobacz też:
- MongoCollection::find() - Querys this collection, returning a MongoCursor for the result set
- MongoCollection::insert() - Inserts an array into the collection
- MongoDB core docs on » find.
MongoCollection::__get
(PECL mongo >=1.0.2)
MongoCollection::__get — Gets a collection
Opis
A concise syntax for getting a collection with a dot-separated name. If a collection name contains strange characters, you may have to use MongoDB::selectCollection() instead.
<?php
$mongo = new Mongo();
// the following two lines are equivalent
$collection = $mongo->selectDB("foo")->selectCollection("bar.baz");
$collection = $mongo->foo->bar->baz;
?>
Parametry
-
name -
The next string in the collection name.
Zwracane wartości
Returns the collection.
MongoCollection::getDBRef
(PECL mongo >=0.9.0)
MongoCollection::getDBRef — Fetches the document pointed to by a database reference
Opis
$ref
)Parametry
-
ref -
A database reference.
Zwracane wartości
Returns the database document pointed to by the reference.
Przykłady
Przykład #1 MongoCollection::getDBRef() example
<?php
$playlists = $db->playlists;
$myList = $playlists->findOne(array('username' => 'me'));
// fetch each song in the playlist
foreach ($myList['songlist'] as $songRef) {
$song = $playlists->getDBRef($songRef);
echo $song['title'] . "\n";
}
?>
Powyższy przykład wyświetli coś podobnego do:
Dazed and Confused Ma na ma na Bohemian Rhapsody
In the above example each $songRef looks something like the following:
Array
(
[$ref] => songs
[$id] => 49902cde5162504500b45c2c
)
MongoCollection::getIndexInfo
(PECL mongo >=0.9.0)
MongoCollection::getIndexInfo — Returns information about indexes on this collection
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
This function returns an array in which each elements describes an array. The elements contain the values name for the name of the index, ns for the namespace (the name of the collection), key containing a list of all the keys and their sort order that make up the index and _id containing a MongoID object with the ID of this index.
Przykłady
Przykład #1 MongoCollection::find() example
This example demonstrates how to search for a range.
<?php
$m = new Mongo;
$c = $m->selectCollection('project', 'outfits');
var_dump($c->getIndexInfo());
?>
Powyższy przykład wyświetli:
array(8) {
[0] =>
array(3) {
'name' =>
string(4) '_id_'
'ns' =>
string(12) 'project.outfits'
'key' =>
array(1) {
'_id' =>
int(1)
}
}
...
[7] =>
array(4) {
'_id' =>
class MongoId#12 (1) {
public $$id => string(24) '4d6f7abd44670a1513190000'
}
'ns' =>
string(12) 'project.outfits'
'key' =>
array(2) {
'created' =>
int(-1)
'userid' =>
int(1)
}
'name' =>
string(19) 'created_-1_userid_1'
}
}
See MongoCursor for more information how to work with cursors.
MongoCollection::getName
(PECL mongo >=0.9.0)
MongoCollection::getName — Returns this collection's name
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the name of this collection.
Przykłady
Przykład #1 MongoCollection::getName() example
<?php
$m = new Mongo();
$c = $m->foo->bar->baz;
echo "Working with collection " . $c->getName() . ".\n";
// the full namespace is given by the MongoCollection::__toString() method
echo "Working in namespace $c.\n";
?>
Powyższy przykład wyświetli coś podobnego do:
Working with collection bar.baz. Working in namespace foo.bar.baz.
MongoCollection::getSlaveOkay
(PECL mongo >=1.1.0)
MongoCollection::getSlaveOkay — Get slaveOkay setting for this collection
Opis
See the query section of this manual for information on distributing reads to slaves.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the value of slaveOkay for this instance.
MongoCollection::group
(PECL mongo >=0.9.2)
MongoCollection::group — Performs an operation similar to SQL's GROUP BY command
Opis
Parametry
-
keys -
Fields to group by. If an array or non-code object is passed, it will be the key used to group results.
1.0.4+: If
keysis an instance of MongoCode,keyswill be treated as a function that returns the key to group by (see the "Passing akeysfunction" example below). -
initial -
Initial value of the aggregation counter object.
-
reduce -
A function that takes two arguments (the current document and the aggregation to this point) and does the aggregation.
-
options -
Optional parameters to the group command. Valid options include:
-
"condition"
Criteria for including a document in the aggregation.
-
"finalize"
Function called once per unique key that takes the final output of the reduce function.
-
Zwracane wartości
Returns an array containing the result.
Przykłady
Przykład #1 MongoCollection::group() example
This groups documents by category and creates a list of names within that category.
<?php
$collection->insert(array("category" => "fruit", "name" => "apple"));
$collection->insert(array("category" => "fruit", "name" => "peach"));
$collection->insert(array("category" => "fruit", "name" => "banana"));
$collection->insert(array("category" => "veggie", "name" => "corn"));
$collection->insert(array("category" => "veggie", "name" => "broccoli"));
$keys = array("category" => 1);
$initial = array("items" => array());
$reduce = "function (obj, prev) { prev.items.push(obj.name); }";
$g = $collection->group($keys, $initial, $reduce);
echo json_encode($g['retval']);
?>
Powyższy przykład wyświetli coś podobnego do:
[{"category":"fruit","items":["apple","peach","banana"]},{"category":"veggie","items":["corn","broccoli"]}]
Przykład #2 MongoCollection::group() example
This example doesn't use any key, so every document will be its own group. It also uses a condition: only documents that match this condition will be processed by the grouping function.
<?php
$collection->save(array("a" => 2));
$collection->save(array("b" => 5));
$collection->save(array("a" => 1));
// use all fields
$keys = array();
// set intial values
$initial = array("count" => 0);
// JavaScript function to perform
$reduce = "function (obj, prev) { prev.count++; }";
// only use documents where the "a" field is greater than 1
$condition = array("a" => array( '$gt' => 1));
$g = $collection->group($keys, $initial, $reduce, $condition);
var_dump($g);
?>
Powyższy przykład wyświetli coś podobnego do:
array(4) {
["retval"]=>
array(1) {
[0]=>
array(1) {
["count"]=>
float(1)
}
}
["count"]=>
float(1)
["keys"]=>
int(1)
["ok"]=>
float(1)
}
Przykład #3 Passing a keys function
If you want to group by something other than a field name, you can pass a function as the first parameter of MongoCollection::group() and it will be run against each document. The return value of the function will be used as its grouping value.
This example demonstrates grouping by the num field modulo 4.
<?php
$c->group(new MongoCode('function(doc) { return {mod : doc.num % 4}; }'),
array("count" => 0),
new MongoCode('function(current, total) { total.count++; }'));
?>
MongoCollection::insert
(PECL mongo >=0.9.0)
MongoCollection::insert — Inserts an array into the collection
Opis
$a
[, array $options = array()
] )All strings sent to the database must be UTF-8. If a string is not UTF-8, a MongoException will be thrown. To insert (or query for) a non-UTF-8 string, use MongoBinData.
Parametry
-
a -
An array.
-
options -
Options for the insert.
-
"safe"
Can be a boolean or integer, defaults to
FALSE. IfFALSE, the program continues executing without waiting for a database response. IfTRUE, the program will wait for the database response and throw a MongoCursorException if the insert did not succeed.If you are using replication and the master has changed, using "safe" will make the driver disconnect from the master, throw an exception, and attempt to find a new master on the next operation (your application must decide whether or not to retry the operation on the new master).
If you do not use "safe" with a replica set and the master changes, there will be no way for the driver to know about the change so it will continuously and silently fail to write.
If safe is an integer, will replicate the insert to that many machines before returning success (or throw an exception if the replication times out, see wtimeout). This overrides the w variable set on the collection.
-
"fsync"
Boolean, defaults to
FALSE. Forces the insert to be synced to disk before returning success. IfTRUE, a safe insert is implied and will override setting safe toFALSE. -
"timeout"
Integer, defaults to MongoCursor::$timeout. If "safe" is set, this sets how long (in milliseconds) for the client to wait for a database response. If the database does not respond within the timeout period, a MongoCursorTimeoutException will be thrown.
-
Zwracane wartości
If safe was set, returns an array containing the
status of the insert. Otherwise, returns a boolean representing if the
array was not empty (an empty array will not be inserted).
If an array is returned, the following keys can be present:
-
ok -
This should almost be 1 (unless last_error itself failed).
-
err -
If this field is non-null, an error occurred on the previous operation. If this field is set, it will be a string describing the error that occurred.
-
code -
If a database error occurred, the relevant error code will be passed back to the client.
-
errmsg -
This field is set if something goes wrong with a database command. It is coupled with ok being 0. For example, if w is set and times out, errmsg will be set to "timed out waiting for slaves" and ok will be 0. If this field is set, it will be a string describing the error that occurred.
-
n -
If the last operation was an insert, an update or a remove, the number of objects affected will be returned.
-
wtimeout -
If the previous option timed out waiting for replication.
-
waited -
How long the operation waited before timing out.
-
wtime -
If w was set and the operation succeeded, how long it took to replicate to w servers.
-
upserted -
If an upsert occured, this field will contain the new record's _id field. For upserts, either this field or updatedExisting will be present (unless an error occurred).
-
updatedExisting -
If an upsert updated an existing element, this field will be true. For upserts, either this field or upserted will be present (unless an error occurred).
Błędy/Wyjątki
Throws MongoCursorException if the "safe" option is set and the insert fails. (Version 1.0.1+)
Throws MongoCursorTimeoutException if the "safe" option is set and the operation takes longer than MongoCursor::$timeout milliseconds to complete. This does not kill the operation on the server, it is a client-side timeout.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 1.0.5 | Changed second parameter to an array of options. Pre-1.0.5, the second parameter was a boolean indicating the "safe" option. |
| 1.0.9 | Added ability to pass integers to "safe" options (only accepted booleans before) and added "fsync" option. |
| 1.0.9 | The return type was changed to be an array containing error information if the "safe" option is used, otherwise it is a boolean as before. |
| 1.0.11 | Disconnects on "not master" errors if "safe" is set. |
| 1.2.0 | Added timeout option. |
| 1.3.0 |
The options parameter does no longer accept
just a boolean to signify a safe insert. Instead, this now has to be done
with array('safe' => true).
|
Przykłady
Przykład #1 MongoCollection::insert() _id example
Inserting an object will add an _id field to it, unless it is passed by reference.
<?php
$m = new Mongo();
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'phpmanual');
$a = array('x' => 12);
$collection->insert($a);
var_dump($a);
$b = array('x' => 12);
$ref = &$b;
$collection->insert($ref);
var_dump($ref);
?>
Powyższy przykład wyświetli coś podobnego do:
array(2) {
["x"]=>
int(12)
["_id"]=>
object(MongoId)#4 (0) {
}
}
array(12) {
["x"]=>
int(1)
}
Przykład #2 MongoCollection::insert() safe example
This example shows inserting two elements with the same _id, which causes
a MongoCursorException to be thrown, as
safe was set.
<?php
$person = array("name" => "Joe", "age" => 20);
$collection->insert($person, true);
// now $person has an _id field, so if we save it
// again, we will get an exception
try {
$collection->insert($person, true);
} catch(MongoCursorException $e) {
echo "Can't save the same person twice!\n";
}
?>
Zobacz też:
- MongoCollection::batchInsert() - Inserts multiple documents into this collection
- MongoCollection::update() - Update records based on a given criteria
- MongoCollection::find() - Querys this collection, returning a MongoCursor for the result set
- MongoCollection::remove() - Remove records from this collection
- MongoDB core docs on » insert.
MongoCollection::remove
(PECL mongo >=0.9.0)
MongoCollection::remove — Remove records from this collection
Opis
$criteria = array()
[, array $options = array()
]] )Parametry
-
criteria -
Description of records to remove.
-
options -
Options for remove.
-
"justOne"
Remove at most one record matching this criteria.
-
"safe"
Can be a boolean or integer, defaults to
FALSE. IfFALSE, the program continues executing without waiting for a database response. IfTRUE, the program will wait for the database response and throw a MongoCursorException if the update did not succeed.If you are using replication and the master has changed, using "safe" will make the driver disconnect from the master, throw and exception, and attempt to find a new master on the next operation (your application must decide whether or not to retry the operation on the new master).
If you do not use "safe" with a replica set and the master changes, there will be no way for the driver to know about the change so it will continuously and silently fail to write.
If safe is an integer, will replicate the update to that many machines before returning success (or throw an exception if the replication times out, see wtimeout). This overrides the w variable set on the collection.
-
"fsync"
Boolean, defaults to
FALSE. Forces the update to be synced to disk before returning success. IfTRUE, a safe update is implied and will override setting safe toFALSE. -
"timeout"
Integer, defaults to MongoCursor::$timeout. If "safe" is set, this sets how long (in milliseconds) for the client to wait for a database response. If the database does not respond within the timeout period, a MongoCursorTimeoutException will be thrown.
-
Zwracane wartości
If safe was set, returns an array containing the
status of the remove. Otherwise, returns a boolean representing if the
array was not empty (an empty array will not be inserted). The fields in
this array are decribed in the documentation for
MongoCollection::insert().
Błędy/Wyjątki
Throws MongoCursorException if the "safe" option is set and the remove fails.
Throws MongoCursorTimeoutException if the "safe" option is set and the operation takes longer than MongoCursor::$timeout milliseconds to complete. This does not kill the operation on the server, it is a client-side timeout.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 1.0.5 | Changed second parameter to an array of options. Pre-1.0.5, the second parameter was a boolean indicating the "justOne" option and there was no safe option. |
| 1.0.9 | Added ability to pass integers to "safe" options (only accepted booleans before) and added "fsync" option. |
| 1.0.9 | The return type was changed to be an array containing error information if the "safe" option is used, otherwise it is a boolean as before. |
| 1.0.11 | Disconnects on "not master" errors if "safe" is set. |
| 1.2.0 | Added timeout option. |
| 1.3.0 |
The options parameter does no longer accept
just a boolean to signify "justOne". Instead, this now has to be done
with array('justOne' => true).
|
Przykłady
Przykład #1 MongoCollection::remove() with justOne example
<?php
$radioactive = $db->radioactive;
// count how much more plutonium there is
$remaining = $radioactive->count(array('type' => 94));
$halflife = $remaining/2;
// remove half of it
while ($halflife > 0) {
$radioactive->remove(array('type' => 94), array("justOne" => true));
$halflife--;
}
?>
Zobacz też:
- MongoCollection::insert() - Inserts an array into the collection
- MongoCollection::update() - Update records based on a given criteria
- MongoDB core docs on » remove.
MongoCollection::save
(PECL mongo >=0.9.0)
MongoCollection::save — Saves an object to this collection
Opis
If the object is from the database, update the existing database object, otherwise insert this object.
Parametry
-
a -
Array to save.
-
options -
Options for the save.
-
"safe"
Can be a boolean or integer, defaults to
FALSE. IfFALSE, the program continues executing without waiting for a database response. IfTRUE, the program will wait for the database response and throw a MongoCursorException if the insert did not succeed.If you are using replication and the master has changed, using "safe" will make the driver disconnect from the master, throw and exception, and attempt to find a new master on the next operation (your application must decide whether or not to retry the operation on the new master).
If you do not use "safe" with a replica set and the master changes, there will be no way for the driver to know about the change so it will continuously and silently fail to write.
If safe is an integer, will replicate the insert to that many machines before returning success (or throw an exception if the replication times out, see wtimeout). This overrides the w variable set on the collection.
-
"fsync"
Boolean, defaults to
FALSE. Forces the insert to be synced to disk before returning success. IfTRUE, a safe insert is implied and will override setting safe toFALSE. -
"timeout"
Integer, defaults to MongoCursor::$timeout. If "safe" is set, this sets how long (in milliseconds) for the client to wait for a database response. If the database does not respond within the timeout period, a MongoCursorTimeoutException will be thrown.
-
Zwracane wartości
If safe was set, returns an array containing the status of the save.
Otherwise, returns a boolean representing if the array was not empty (an empty array will not
be inserted).
Błędy/Wyjątki
Throws MongoCursorException if the "safe" option is set and the save fails.
Throws MongoCursorTimeoutException if the "safe" option is set and the operation takes longer than MongoCursor::$timeout milliseconds to complete. This does not kill the operation on the server, it is a client-side timeout.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 1.0.5 | Added "options" parameter. |
| 1.0.9 | Added ability to pass integers to "safe" options (only accepted booleans before) and added "fsync" option. |
| 1.0.11 | Disconnects on "not master" errors if "safe" is set. |
| 1.2.0 | Added timeout option. |
Przykłady
Przykład #1 MongoCollection::save() example
<?php
$obj = array('x' => 1);
// insert $obj into the db
$collection->save($obj);
// add another field
$obj['foo'] = 'bar';
// $obj cannot be inserted again, causes duplicate _id error
$collection->insert($obj);
// save updates $obj with the new field
$collection->save($obj);
?>
MongoCollection::setSlaveOkay
(PECL mongo >=1.1.0)
MongoCollection::setSlaveOkay — Change slaveOkay setting for this collection
Opis
$ok = true
] )See the query section of this manual for information on distributing reads to slaves.
Parametry
-
ok -
If reads should be sent to secondary members of a replica set for all possible queries using this MongoCollection instance.
Zwracane wartości
Returns the former value of slaveOkay for this instance.
MongoCollection::toIndexString
(No version information available, might only be in SVN)
MongoCollection::toIndexString — Converts keys specifying an index to its identifying string
Opis
Parametry
-
keys -
Field or fields to convert to the identifying string
Zwracane wartości
Returns a string that describes the index.
Przykłady
Przykład #1 MongoCollection::toIndexString() example
This example shows how you can create an index name out of of keys. Because this is a protected (static) method, you need to overload it in a child class first.
<?php
// Create inheritec class to make the method "public".
class MyCollection extends MongoCollection
{
static public function toIndexString($a)
{
return parent::toIndexString($a);
}
}
echo MyCollection::toIndexString("foo")), "\n";
// Outputs: foo_1
echo MyCollection::toIndexString(array('name' => 1, 'age' => -1)), "\n";
// Outputs: name_1_age_-1
?>
Zobacz też:
MongoDB core docs on » indexes.
MongoCollection::__toString
(PECL mongo >=0.9.0)
MongoCollection::__toString — String representation of this collection
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the full name of this collection.
Przykłady
Przykład #1 MongoCollection::__toString() example
<?php
$m = new Mongo();
$c1 = $m->foo->bar->baz;
echo "Working with collection $c1.";
$c2 = $m->selectCollection('[]', '&');
echo "Working with collection $c2.";
?>
Powyższy przykład wyświetli coś podobnego do:
Working with collection foo.bar.baz. Working with collection [].&.
MongoCollection::update
(PECL mongo >=0.9.0)
MongoCollection::update — Update records based on a given criteria
Opis
$criteria
, array $new_object
[, array $options = array()
] )Parametry
-
criteria -
Description of the objects to update.
-
new_object -
The object with which to update the matching records.
-
options -
This parameter is an associative array of the form array("optionname" => <boolean>, ...). Currently supported options are:
-
"upsert"
If no document matches
$criteria, a new document will be created from$criteriaand$new_object(see upsert example below). -
"multiple"
All documents matching $criteria will be updated. MongoCollection::update() has exactly the opposite behavior of MongoCollection::remove(): it updates one document by default, not all matching documents. It is recommended that you always specify whether you want to update multiple documents or a single document, as the database may change its default behavior at some point in the future.
-
"safe"
Can be a boolean or integer, defaults to
FALSE. IfFALSE, the program continues executing without waiting for a database response. IfTRUE, the program will wait for the database response and throw a MongoCursorException if the update did not succeed.If you are using replication and the master has changed, using "safe" will make the driver disconnect from the master, throw and exception, and attempt to find a new master on the next operation (your application must decide whether or not to retry the operation on the new master).
If you do not use "safe" with a replica set and the master changes, there will be no way for the driver to know about the change so it will continuously and silently fail to write.
If safe is an integer, will replicate the update to that many machines before returning success (or throw an exception if the replication times out, see wtimeout). This overrides the w variable set on the collection.
-
"fsync"
Boolean, defaults to
FALSE. Forces the update to be synced to disk before returning success. IfTRUE, a safe update is implied and will override setting safe toFALSE. -
"timeout"
Integer, defaults to MongoCursor::$timeout. If "safe" is set, this sets how long (in milliseconds) for the client to wait for a database response. If the database does not respond within the timeout period, a MongoCursorTimeoutException will be thrown.
-
Zwracane wartości
If safe was set, returns an array containing the
status of the update. Otherwise, returns a boolean representing if the
array was not empty (an empty array will not be inserted). The fields in
this array are decribed in the documentation for
MongoCollection::insert().
Błędy/Wyjątki
Throws MongoCursorException if the "safe" option is set and the update fails.
Throws MongoCursorTimeoutException if the "safe" option is set and the operation takes longer than MongoCursor::$timeout milliseconds to complete. This does not kill the operation on the server, it is a client-side timeout.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 1.0.1 | Changed "options" parameter from boolean to array. Pre-1.0.1, the second parameter was an optional boolean value specifying an upsert. |
| 1.0.5 | Added "safe" option. |
| 1.0.9 | Added ability to pass integers to "safe" options (only accepted booleans before) and added "fsync" option. |
| 1.0.9 | The return type was changed to be an array containing error information if the "safe" option is used, otherwise it is a boolean as before. |
| 1.0.11 | Disconnects on "not master" errors if "safe" is set. |
| 1.2.0 | Added timeout option. |
| 1.3.0 |
The options parameter does no longer accept
just a boolean to signify an upsert. Instead, this now has to be done
with array('upsert' => true).
|
Przykłady
Przykład #1 MongoCollection::update()
Adding an address field to a document.
<?php
$c->insert(array("firstname" => "Bob", "lastname" => "Jones" ));
$newdata = array('$set' => array("address" => "1 Smith Lane"));
$c->update(array("firstname" => "Bob"), $newdata);
var_dump($c->findOne(array("firstname" => "Bob")));
?>
Powyższy przykład wyświetli coś podobnego do:
array(4) {
["_id"]=>
object(MongoId)#6 (0) {
}
["firstname"]=>
string(3) "Bob"
["lastname"]=>
string(5) "Jones"
["address"]=>
string(12) "1 Smith Lane"
}
Przykład #2 MongoCollection::update() upsert example
Upserts can simplify code, as a single line can create the object if it does not exist yet and update it if it does.
<?php
$c->drop();
$c->update(array("uri" => "/summer_pics"), array('$inc' => array("page hits" => 1)), array("upsert" => true));
var_dump($c->findOne());
?>
Powyższy przykład wyświetli coś podobnego do:
array(3) {
["_id"]=>
object(MongoId)#9 (0) {
}
["uri"]=>
string(12) "/summer_pics"
["page hits"]=>
int(1)
}
If $new_object does not contain $-operators, an upsert will
create a new document from the passed fields only. This matches the
behavior of a normal update, where not using $-operators causes the whole
document to be overwritten.
<?php
$c->drop();
$c->update(
array("name" => "joe"),
array("username" => "joe312", "createdAt" => new MongoDate()),
array("upsert" => true)
);
var_dump($c->findOne());
?>
Powyższy przykład wyświetli coś podobnego do:
array(3) {
["_id"]=>
object(MongoId)#10 (0) {
}
["username"]=>
string(6) "joe312"
["createdAt"]=>
object(MongoDate)#4 (0) {
}
}
Przykład #3 MongoCollection::update() multiple example
By default, MongoCollection::update() will only update
the first document matching $criteria that it
finds. Using the "multiple" option can override this behavior, if needed.
This example adds a "gift" field to every person whose birthday is in the next day.
<?php
$today = array('$gt' => new MongoDate(), '$lt' => new MongoDate(strtotime("+1 day")));
$people->update(
array("birthday" => $today),
array('$set' => array('gift' => $surprise)),
array("multiple" => true)
);
?>
Zobacz też:
The PHP documentation on updates and the » MongoDB core docs.
MongoCollection::validate
(PECL mongo >=0.9.0)
MongoCollection::validate — Validates this collection
Opis
$scan_data = FALSE
] )Parametry
-
scan_data -
Only validate indices, not the base collection.
Zwracane wartości
Returns the database's evaluation of this object.
Spis treści
- MongoCollection::batchInsert — Inserts multiple documents into this collection
- MongoCollection::__construct — Creates a new collection
- MongoCollection::count — Counts the number of documents in this collection
- MongoCollection::createDBRef — Creates a database reference
- MongoCollection::deleteIndex — Deletes an index from this collection
- MongoCollection::deleteIndexes — Delete all indices for this collection
- MongoCollection::drop — Drops this collection
- MongoCollection::ensureIndex — Creates an index on the given field(s), or does nothing if the index already exists
- MongoCollection::find — Querys this collection, returning a MongoCursor for the result set
- MongoCollection::findOne — Querys this collection, returning a single element
- MongoCollection::__get — Gets a collection
- MongoCollection::getDBRef — Fetches the document pointed to by a database reference
- MongoCollection::getIndexInfo — Returns information about indexes on this collection
- MongoCollection::getName — Returns this collection's name
- MongoCollection::getSlaveOkay — Get slaveOkay setting for this collection
- MongoCollection::group — Performs an operation similar to SQL's GROUP BY command
- MongoCollection::insert — Inserts an array into the collection
- MongoCollection::remove — Remove records from this collection
- MongoCollection::save — Saves an object to this collection
- MongoCollection::setSlaveOkay — Change slaveOkay setting for this collection
- MongoCollection::toIndexString — Converts keys specifying an index to its identifying string
- MongoCollection::__toString — String representation of this collection
- MongoCollection::update — Update records based on a given criteria
- MongoCollection::validate — Validates this collection
The MongoCursor class
(No version information available, might only be in SVN)
Wstęp
A cursor is used to iterate through the results of a database query. For example, to query the database and see all results, you could do:
<?php
$cursor = $collection->find();
var_dump(iterator_to_array($cursor));
?>
You don't generally create cursors using the MongoCursor constructor, you get a new cursor by calling MongoCollection::find() (as shown above).
Suppose that, in the example above, $collection was a 50GB collection. We certainly wouldn't want to load that into memory all at once, which is what a cursor is for: allowing the client to access the collection in dribs and drabs.
If we have a large result set, we can iterate through it, loading a few megabytes of results into memory at a time. For example, we could do:
<?php
$cursor = $collection->find();
foreach ($cursor as $doc) {
// do something to each document
}
?>
Note that this means that a cursor does not "contain" the database results, it just manages them. Thus, if you print a cursor (with, say, var_dump() or print_r()), you'll just get the cursor object, not your documents. To get the documents themselves, you can use one of the methods shown above.
Cursor Stages
A MongoCursor has two "life stages": pre- and post- query. When a cursor is created, it has not yet contacted the database, so it is in its pre-query state. In this state, the client can further specify what they want the query to do, including adding limits, skips, sorts, and more advanced options.
When the client attempts to get a result (by calling MongoCursor::next(), directly or indirectly), the cursor moves into the post-query stage. At this point, the query has been executed by the database and cannot be modified anymore.
<?php
$cursor = $collection->find()->limit(10);
// database has not yet been queried, so more search options can be added
$cursor = $cursor->sort(array("a" => 1));
var_dump($cursor->getNext());
// now database has been queried and more options cannot be added
// so this will throw an exception:
$cursor->skip(4);
?>
Krótki opis klasy
$connection
, string $ns
[, array $query = array()
[, array $fields = array()
]] )Static Variables
- slaveOkay
-
If the query should have the "slaveOkay" flag set, which allows reads on the slave (slaves are, by default, just for backup and unreadable). Can be overridden with MongoCursor::slaveOkay().
- timeout
-
Set timeout in milliseconds for all database responses. To wait forever, use -1. Can be overridden with MongoCursor::timeout(). This does not cause the MongoDB server to cancel the operation, it just causes the driver to stop waiting for a response and throw a MongoCursorTimeoutException.
Zobacz też:
MongoDB core docs on » cursors.
MongoCursor::addOption
(PECL mongo >=1.0.4)
MongoCursor::addOption — Adds a top-level key/value pair to a query
Opis
This is an advanced function and should not be used unless you know what you're doing.
A query can optionally be nested in a "query" field if other options, such as a sort or hint, are given. For instance, adding a sort causes the query to become a subfield of a bigger query object, like:
<?php
$query = array("query" => $query, "orderby" => $sort);
?>
This method is for adding a top-level field to a query. It makes the query a subobject (if it isn't already) and adds the key/value pair of your chosing to the top level.
It cannot be used to add extra criteria to a query on the fly. For instance, this will not work:
<?php
// NOT CORRECT
$cursor = $users->find()->addOption("name", "joe")->addOption("age", 20);
?>
Parametry
-
key -
Fieldname to add.
-
value -
Value to add.
Zwracane wartości
Returns this cursor.
Błędy/Wyjątki
Throws MongoCursorException if this cursor has started iterating.
Przykłady
Przykład #1 MongoCursor::addOption() example
Using MongoCursor::skip() to skip over millions of results can become slow. One way around this is to use $min or $max options for the query. These can be handy, but they require an index on exactly the fields being searched for. This is an example of how to use $min as an alternative to MongoCursor::skip().
<?php
// make sure we have an index
$c->ensureIndex(array("ts" => 1));
// you may have to modify this to run in a reasonable amount of time on slow
// machines (should take about 30 seconds on a good machine)
for ($i = 0; $i < 30000000; $i++) {
$c->insert(array("ts" => new MongoDate(), "i" => $i));
}
$now = strtotime("now");
// find documents inserted in the last 2 seconds
$cursor = $c->find()->addOption('$min', array("ts" => $now-2));
?>
MongoCursor::batchSize
(PECL mongo >=1.0.11)
MongoCursor::batchSize — Sets the number of results returned per result set
Opis
This cannot override MongoDB's limit on the amount of data it will return to the client (i.e., if you set batch size to 1,000,000,000, MongoDB will still only return 4-16MB of results).
To ensure consistent behavior, the rules of batchSize and limit behavior a little complex but work "as expected". The rules are: hard limits override soft limits with preference given to MongoCursor::limit() over MongoCursor::batchSize(). After that, whichever is set and lower than the other will take precedence. Some examples:
<?php
// one batch, at most 20 items
$cursor->limit(-20)->batchSize(10);
// one batch, at most 10 items
$cursor->limit(20)->batchSize(-10);
// first batch: at most 10 items
$cursor->limit(10);
// first batch: at most 10 items
$cursor->limit(10)->batchSize(20);
// first batch: at most 10 items
$cursor->limit(20)->batchSize(10);
$cursor->limit(30)->batchSize(7)
// if we iterate through 28 items, the next call to getNext() will contact the
// database and request a batch of 2 documents
?>
Parametry
-
num -
The number of results to return in the next batch.
Zwracane wartości
Returns this cursor.
Błędy/Wyjątki
Throws MongoCursorException if this cursor has started iterating. This will change in 1.0.12, as this should be able to be called at any time.
MongoCursor::__construct
(PECL mongo >=0.9.0)
MongoCursor::__construct — Create a new cursor
Opis
$connection
, string $ns
[, array $query = array()
[, array $fields = array()
]] )Parametry
-
connection -
Database connection.
-
ns -
Full name of database and collection.
-
query -
Database query.
-
fields -
Fields to return.
Zwracane wartości
Returns the new cursor.
MongoCursor::count
(PECL mongo >=0.9.2)
MongoCursor::count — Counts the number of results for this query
Opis
$foundOnly = FALSE
] )This method does not affect the state of the cursor: if you haven't queried yet, you can still apply limits, skips, etc. If you have started iterating through results, it will not move the current position of the cursor. If you have exhasted the cursor, it will not reset it.
Parametry
-
foundOnly -
Send cursor limit and skip information to the count function, if applicable.
Zwracane wartości
The number of documents returned by this cursor's query.
Przykłady
Przykład #1 MongoCursor::count() example
<?php
$collection->insert(array('x'=>1));
$collection->insert(array('x'=>2));
$collection->insert(array('x'=>3));
$cursor = $collection->find();
var_dump($cursor->count());
var_dump($cursor->count(true));
$cursor->limit(2);
var_dump($cursor->count());
var_dump($cursor->count(true));
?>
Powyższy przykład wyświetli coś podobnego do:
int(3) int(3) int(3) int(2)
Błędy/Wyjątki
Throws MongoConnectionException if it cannot reach the database.
MongoCursor::current
(PECL mongo >=0.9.0)
MongoCursor::current — Returns the current element
Opis
This returns NULL until MongoCursor::next() is called.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
The current result as an associative array.
MongoCursor::dead
(PECL mongo >=0.9.6)
MongoCursor::dead — Checks if there are documents that have not been sent yet from the database for this cursor
Opis
The database sends responses in batches of documents, up to 4Mb of documents per response. This method checks if the database has more batches or if the result set has been exhausted.
A cursor being "dead" does not mean that
MongoCursor::hasNext() will return FALSE, it only means
that the database is done sending results to the client. The client should
continue iterating through results until
MongoCursor::hasNext() is FALSE.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns if there are more results that have not been sent to the client, yet.
MongoCursor::doQuery
(No version information available, might only be in SVN)
MongoCursor::doQuery — Execute the query.
Opis
This function actually queries the database. All queries and commands go through this function. Thus, this function can be overridden to provide custom query handling.
This handles serializing your query, sending it to the database, receiving a response, and deserializing it. Thus, if you are planning to override this, your code should probably call out to the original to use the existing functionality (see the example below).
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
NULL.
Błędy/Wyjątki
Throws MongoConnectionException if it cannot reach the database.
Przykłady
Przykład #1 MongoCursor::doQuery() example
You could override this function to attempt a query on a slave and, if that fails, try it again on the master.
<?php
class MyCursor extends MongoCursor {
protected function doQuery() {
$this->slaveOkay();
try {
MongoCursor::doQuery();
}
catch(MongoCursorException $e) {
$this->slaveOkay(false);
MongoCursor::doQuery();
}
}
}
?>
MongoCursor::explain
(PECL mongo >=0.9.2)
MongoCursor::explain — Return an explanation of the query, often useful for optimization and debugging
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns an explanation of the query.
Przykłady
Przykład #1 MongoCursor::explain() example
<?php
$cursor = $collection->find(array("x"=>1), array("y"));
$cursor->sort(array("z" => 1))->limit(4)->skip(5);
var_dump($cursor->explain());
?>
Powyższy przykład wyświetli coś podobnego do:
array(8) {
["cursor"]=>
string(15) "BtreeCursor x_1"
["startKey"]=>
array(1) {
["x"]=>
int(1)
}
["endKey"]=>
array(1) {
["x"]=>
int(1)
}
["nscanned"]=>
float(4)
["n"]=>
int(4)
["scanAndOrder"]=>
int(1)
["millis"]=>
int(3)
["allPlans"]=>
array(2) {
[0]=>
array(3) {
["cursor"]=>
string(15) "BtreeCursor x_1"
["startKey"]=>
array(1) {
["x"]=>
int(1)
}
["endKey"]=>
array(1) {
["x"]=>
int(1)
}
}
[1]=>
array(3) {
["cursor"]=>
string(11) "BasicCursor"
["startKey"]=>
array(0) {
}
["endKey"]=>
array(0) {
}
}
}
}
Błędy/Wyjątki
Throws MongoConnectionException if it cannot reach the database.
Zobacz też:
MongoDB core docs on » explain.
MongoCursor::fields
(PECL mongo >=1.0.6)
MongoCursor::fields — Sets the fields for a query
Opis
Fields are specified by "fieldname" : bool. TRUE
indicates that a field should be returned, FALSE indicates that it should
not be returned. You can also use 1 and 0 instead of TRUE and FALSE.
Thus, to return only the "summary" field, one could say:
<?php
$cursor->fields(array("summary" => true));
?>
To return all fields except the "hidden" field:
<?php
$cursor->fields(array("hidden" => false));
?>
Parametry
-
f -
Fields to return (or not return).
Zwracane wartości
Returns this cursor.
Błędy/Wyjątki
Throws MongoCursorException if this cursor has started iterating or a scalar argument is given.
MongoCursor::getNext
(PECL mongo >=0.9.0)
MongoCursor::getNext — Return the next object to which this cursor points, and advance the cursor
Opis
This is identical to the function:
<?php
public function getNext() {
$this->next();
return $this->current();
}
?>
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the next object.
Błędy/Wyjątki
Throws MongoConnectionException if it cannot reach the database and MongoCursorTimeoutException if the timeout is exceeded.
MongoCursor::hasNext
(PECL mongo >=0.9.0)
MongoCursor::hasNext — Checks if there are any more elements in this cursor
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns if there is another element.
Błędy/Wyjątki
Throws MongoConnectionException if it cannot reach the database and MongoCursorTimeoutException if the timeout is exceeded.
MongoCursor::hint
(PECL mongo >=0.9.0)
MongoCursor::hint — Gives the database a hint about the query
Opis
Parametry
-
key_pattern -
Indexes to use for the query.
Zwracane wartości
Returns this cursor.
Błędy/Wyjątki
Throws MongoCursorException if this cursor has started iterating.
MongoCursor::immortal
(PECL mongo >=1.0.1)
MongoCursor::immortal — Sets whether this cursor will timeout
Opis
After remaining idle for some amount of time, cursor, by default, "die." This is generally the behavior one wants. The database cleans up a cursor once all of its results have been sent to the client, but if the client doesn't request all of the results, the cursor will languish there, taking up resources. Thus, after a few minutes, the cursor "times out" and the database assumes the client has gotten everything it needs and cleans up its the cursor's resources.
If, for some reason, you need a cursor to hang around for a long time, you
can prevent the database from cleaning it up by using this method. However,
if you make a cursor immortal, you need to iterate through all of its results
(or at least until Cursor::dead() returns TRUE) or the
cursor will hang around the database forever, taking up resources.
Parametry
-
liveForever -
If the cursor should be immortal.
Zwracane wartości
Returns this cursor.
Błędy/Wyjątki
Throws MongoCursorException if this cursor has started iterating.
MongoCursor::info
(PECL mongo >=1.0.5)
MongoCursor::info — Gets the query, fields, limit, and skip for this cursor
Opis
This can be called before or after the query.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the namespace, limit, skip, query, and fields for this cursor.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 1.0.10 | Added started_iterating field, a boolean indicating if cursor is pre- or post-query. |
| 1.1.0 | Added a number of other fields, including id (the cursor id), at (the driver's counter of which document is current), numReturned (the number returned by the server in the current batch), and server (which server the query was sent to—useful in conjunction with MongoCursor::slaveOkay()). |
Przykłady
Przykład #1 MongoCursor::info() example
<?php
$m = new Mongo();
$cursor = $m->foo->bar->find(array("x" => 4), array("y" => false));
var_dump($cursor->info());
?>
Powyższy przykład wyświetli coś podobnego do:
array(5) {
["ns"]=>
string(7) "foo.bar"
["limit"]=>
int(0)
["skip"]=>
int(0)
["query"]=>
array(1) {
["x"]=>
int(4)
}
["fields"]=>
array(1) {
["y"]=>
int(0)
}
}
MongoCursor::key
(PECL mongo >=0.9.0)
MongoCursor::key — Returns the current result's _id
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
The current result's _id as a string.
MongoCursor::limit
(PECL mongo >=0.9.0)
MongoCursor::limit — Limits the number of results returned
Opis
Parametry
-
num -
The number of results to return.
Zwracane wartości
Returns this cursor.
Błędy/Wyjątki
Throws MongoCursorException if this cursor has started iterating.
Zobacz też:
MongoDB core docs on » limit.
MongoCursor::next
(PECL mongo >=0.9.0)
MongoCursor::next — Advances the cursor to the next result
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
NULL.
Błędy/Wyjątki
Throws MongoConnectionException if it cannot reach the database and MongoCursorTimeoutException if the timeout is exceeded.
MongoCursor::partial
(PECL mongo >=1.2.0)
MongoCursor::partial — If this query should fetch partial results from mongos if a shard is down
Opis
This option allows mongos to send partial query results if a shard is unreachable. This is only applicable when running a sharded MongoDB cluster and connecting to a mongos.
If a shard goes down and a query needs to be sent to that shard, mongos will return the results (if any) from shards it already contacted, then an error message that it could not reach the shard (a MongoCursorException in PHP). If you would like to get whatever results mongos can provide and no exception, you can use this method. Note that this means that you won't have an indication that a shard is down in your query response.
This has no effect on the query if all shards are reachable. This flag was implemented in MongoDB version 1.7.5, so will only work with that version and higher.
Parametry
-
okay -
If receiving partial results is okay.
Zwracane wartości
Returns this cursor.
Błędy/Wyjątki
Throws MongoCursorException if this cursor has started iterating.
MongoCursor::reset
(PECL mongo >=0.9.0)
MongoCursor::reset — Clears the cursor
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
NULL.
MongoCursor::rewind
(PECL mongo >=0.9.0)
MongoCursor::rewind — Returns the cursor to the beginning of the result set
Opis
This is identical to the function:
<?php
public function rewind() {
$this->reset();
$this->next();
}
?>
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
NULL.
Błędy/Wyjątki
Throws MongoConnectionException if it cannot reach the database and MongoCursorTimeoutException if the timeout is exceeded.
MongoCursor::skip
(PECL mongo >=0.9.0)
MongoCursor::skip — Skips a number of results
Opis
Parametry
-
num -
The number of results to skip.
Zwracane wartości
Returns this cursor.
Błędy/Wyjątki
Throws MongoCursorException if this cursor has started iterating.
MongoCursor::slaveOkay
(PECL mongo >=0.9.4)
MongoCursor::slaveOkay — Sets whether this query can be done on a slave
Opis
Calling this will make the driver route reads to slaves if:
- You are using a replica set and
- You created a Mongo instance using the option "replicaSet" => true and
- There is a healthy slave that can be reached by the driver.
Note that you should use this function even if you do not use the automatic routing to slaves. If you connect directly to a secondary in a replica set, you still need to call this function, which basically tells the database that you are aware that you might be getting older data and you're okay with that. If you do not call this, you'll get "not master" errors when you try to query.
This method will override the static class variable MongoCursor::slaveOkay. It will also override Mongo::setSlaveOkay(), MongoDB::setSlaveOkay() and MongoCollection::setSlaveOkay().
Parametry
-
okay -
If it is okay to query the slave.
Zwracane wartości
Returns this cursor.
Błędy/Wyjątki
Throws MongoCursorException if this cursor has started iterating.
Przykłady
Przykład #1 MongoCursor::slaveOkay() example
<?php
MongoCursor::$slaveOkay = false;
// cannot query slave
$cursor = $collection->find();
// can query slave
$cursor = $collection->find()->slaveOkay();
MongoCursor::$slaveOkay = true;
// can query slave
$cursor = $collection->find();
// cannot query slave
$cursor = $collection->find()->slaveOkay(false);
?>
MongoCursor::snapshot
(PECL mongo >=0.9.4)
MongoCursor::snapshot — Use snapshot mode for the query
Opis
Use snapshot mode for the query. Snapshot mode assures no duplicates are returned, or objects missed, which were present at both the start and end of the query's execution (if an object is new during the query, or deleted during the query, it may or may not be returned, even with snapshot mode).
Note that short query responses (less than 1MB) are always effectively snapshotted.
Currently, snapshot mode may not be used with sorting or explicit hints.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns this cursor.
Błędy/Wyjątki
Throws MongoCursorException if this cursor has started iterating.
MongoCursor::sort
(PECL mongo >=0.9.0)
MongoCursor::sort — Sorts the results by given fields
Opis
Parametry
-
fields -
An array of fields by which to sort. Each element in the array has as key the field name, and as value either 1 for ascending sort, or -1 for descending sort.
Each result is first sorted on the first field in the array, then (if it exists) on the second field in the array, etc. This means that the order of the fields in the
fieldsarray is important. See also the examples section.
Zwracane wartości
Returns the same cursor that this method was called on.
Błędy/Wyjątki
Throws MongoCursorException if this cursor has started iterating.
Przykłady
Przykład #1 MongoCursor::sort() example
<?php
// Sort on field x, ascending
$cursor->sort(array('x' => 1));
// The order in the associative array is important. For instance, these two
// examples will yield different results:
// Sort on date ascending and age descending
$cursor->sort(array('date' => 1, 'age' => -1));
// Sort on age descending and date ascending
$cursor->sort(array('age' => -1, 'date' => 1));
?>
MongoCursor::tailable
(PECL mongo >=0.9.4)
MongoCursor::tailable — Sets whether this cursor will be left open after fetching the last results
Opis
Mongo has a feature known as tailable cursors which are similar to the Unix "tail -f" command.
Tailable means cursor is not closed when the last data is retrieved. Rather, the cursor marks the final object's position. you can resume using the cursor later, from where it was located, if more data were received.
Like any "latent cursor", the cursor may become invalid at some point -- for example if that final object it references were deleted. Thus, you should be prepared to requery if the cursor is MongoCursor::dead().
Parametry
-
tail -
If the cursor should be tailable.
Zwracane wartości
Returns this cursor.
Błędy/Wyjątki
Throws MongoCursorException if this cursor has started iterating.
Przykłady
Przykład #1 MongoCursor::tailable() example
<?php
$cursor = $collection->find()->tailable();
$results = array();
while (1) {
if (!$cursor->hasNext()) {
// we've read all the results, exit
if ($cursor->dead()) {
break;
}
// read all results so far, wait for more
sleep(10);
}
else {
$results[] = $cursor->getNext();
}
}
?>
MongoCursor::timeout
(PECL mongo >=1.0.3)
MongoCursor::timeout — Sets a client-side timeout for this query
Opis
A timeout can be set at any time and will affect subsequent queries on the cursor, including fetching more results from the database. For example, to wait forever for an initial response but timeout after 100 ms for subsequent results, one could say:
<?php
$cursor = $collection->find();
// $cursor->hasNext() executes the query. No timeout has been set, so the
// program will wait as long as necessary for a response.
while ($cursor->hasNext()) {
$cursor->timeout(100);
// now the timeout has been set, so if the cursor needs to get more results
// from the database, it will only wait 100 ms for the database's reply
try {
print_r($cursor->getNext());
}
catch(MongoCursorTimeoutException $e) {
echo "query took too long!";
}
}
?>
A timeout of 0 (or a negative number) will wait forever so it can be used to reset the cursor if a timeout is no longer needed.
Parametry
-
ms -
The number of milliseconds for the cursor to wait for a response. By default, the cursor will wait forever.
Zwracane wartości
This cursor.
Przykłady
Przykład #1 MongoCursor::timeout() example
A query where the cursor waits for one second for a response.
<?php
$cursor = $collection->find()->timeout(1000);
try {
foreach ($cursor as $value) {
print_r($value);
}
}
catch(MongoCursorTimeoutException $e) {
echo "query took too long!";
}
?>
Błędy/Wyjątki
Causes methods that fetch results to throw MongoCursorTimeoutExceptions if the query takes longer than the number of milliseconds specified.
MongoCursor::valid
(PECL mongo >=0.9.0)
MongoCursor::valid — Checks if the cursor is reading a valid result.
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
If the current result is not null.
Spis treści
- MongoCursor::addOption — Adds a top-level key/value pair to a query
- MongoCursor::batchSize — Sets the number of results returned per result set
- MongoCursor::__construct — Create a new cursor
- MongoCursor::count — Counts the number of results for this query
- MongoCursor::current — Returns the current element
- MongoCursor::dead — Checks if there are documents that have not been sent yet from the database for this cursor
- MongoCursor::doQuery — Execute the query.
- MongoCursor::explain — Return an explanation of the query, often useful for optimization and debugging
- MongoCursor::fields — Sets the fields for a query
- MongoCursor::getNext — Return the next object to which this cursor points, and advance the cursor
- MongoCursor::hasNext — Checks if there are any more elements in this cursor
- MongoCursor::hint — Gives the database a hint about the query
- MongoCursor::immortal — Sets whether this cursor will timeout
- MongoCursor::info — Gets the query, fields, limit, and skip for this cursor
- MongoCursor::key — Returns the current result's _id
- MongoCursor::limit — Limits the number of results returned
- MongoCursor::next — Advances the cursor to the next result
- MongoCursor::partial — If this query should fetch partial results from mongos if a shard is down
- MongoCursor::reset — Clears the cursor
- MongoCursor::rewind — Returns the cursor to the beginning of the result set
- MongoCursor::skip — Skips a number of results
- MongoCursor::slaveOkay — Sets whether this query can be done on a slave
- MongoCursor::snapshot — Use snapshot mode for the query
- MongoCursor::sort — Sorts the results by given fields
- MongoCursor::tailable — Sets whether this cursor will be left open after fetching the last results
- MongoCursor::timeout — Sets a client-side timeout for this query
- MongoCursor::valid — Checks if the cursor is reading a valid result.
Types
Spis treści
- MongoId
- MongoCode
- MongoDate
- MongoRegex
- MongoBinData
- MongoInt32
- MongoInt64
- MongoDBRef
- MongoMinKey
- MongoMaxKey
- MongoTimestamp
MongoDB allows programmers to save and query for data expressed in all of the basic PHP types, compound types (arrays, associative arrays, and objects), and a half-dozen classes provided by the MongoDB PHP driver (for regular expressions, dates, and other specialized applications).
Booleans and NULL
TRUE, FALSE, and NULL can be used as-is.
Numbers
Numbers are distinct from strings in MongoDB: "123" does not match 123. Thus, if you want to make sure numbers are sorted and matched correctly, you must make sure that they are actually saved as numbers.
<?php
$doc = array("a" => 123, "b" => "123");
$collection->insert($doc);
$doc->find(array("a" => 123)); // matches
$doc->find(array("a" => "123")); // doesn't match
$doc->find(array("a" => 123.0)); // matches
$doc->find(array("b" => 123)); // doesn't match
$doc->find(array("b" => "123")); // matches
?>
As noted above, floating point numbers do compare with/match integer numbers as one would expect.
Large Numbers
By default, on a 32-bit system, numbers are sent to the database as 32-bit integers. On a 64-bit system, they are sent as 64-bit integers. For backwards compatibility, all systems deserialize 64-bit integers as floating point numbers. Floating point numbers are not exact. If you need exact values, you must tweak your » php.ini settings.
On a 32-bit system, if mongo.long_as_object is set, 64-bit integers will be returns as MongoInt64 objects. The integer will be stored in the value field with perfect precision (as a string). You can also use MongoInt64 to save 64-bit integers on 32-bit machines.
On 64-bit systems, you can either set mongo.long_as_object or set mongo.native_long. mongo.native_long will return 64-bit integers and "normal" PHP integers. You can use MongoInt32 to save 32-bit integers on 64-bit machines.
You should set the mongo.long_as_object and mongo.native_long behavior that you plan to use, even if it is the default behavior (to protect against future changes to the defaults).
See also: » php.ini Options, MongoInt32, MongoInt64.
Strings
Strings must be UTF-8. Non-UTF-8 strings must either be converted to UTF-8 before being sent to the database or saved as binary data.
Regular expressions can be used to match strings, and are expressed using the MongoRegex class.
Binary Data
Non-UTF-8 strings, images, and any other binary data should be sent to the database using the MongoBinData type.
Dates
Dates can be created using the MongoDate class. They are stored as milliseconds since the epoch.
MongoTimestamp is not for saving dates or timestamps, it is used internally by MongoDB. Unless you are creating a tool that interacts with the internals of replication or sharding, you should use MongoDate, not MongoTimestamp.
Unique Ids
The driver will automatically create an _id field before inserting a document (unless one is specified by the user). This field is an instance of MongoId (called "ObjectId" in most other languages).
These ids are 12 bytes long and composed of:
-
4 bytes of timestamp
No two records can have the same id if they were inserted at different times.
-
3 bytes machine id
No two records can have the same id if they were inserted on different machines
-
2 bytes thread id
No two records can have the same id if they were inserted by different threads running on the same machine.
-
3 bytes incrementing value
Each time an id is created, a global counter is incremented and used as the increment value of the next id.
JavaScript
MongoDB comes with a JavaScript engine, so you can embed JavaScript in queries (using a $where clause), send it directly to the database to be executed, and use it to perform aggregations.
For security, use MongoCode's scope field to use PHP variables in JavaScript. Code that does not require external values can either use MongoCode or just be a string. See the » section on security for more information about sending JavaScript to the database.
Arrays and Objects
Arrays and objects can also be saved to the database. An array with ascending numeric keys will be saved as a an array, anything else will be saved as an object.
<?php
// $scores will be saved as an array
$scores = array(98, 100, 73, 85);
$collection->insert(array("scores" => $scores));
// $scores will be saved as an object
$scores = array("quiz1" => 98, "midterm" => 100, "quiz2" => 73, "final" => 85);
$collection->insert(array("scores" => $scores));
?>
If you query for these objects using the database shell, they will look like:
> db.students.find()
{ "_id" : ObjectId("4b06beada9ad6390dab17c43"), "scores" : [ 98, 100, 73, 85 ] }
{ "_id" : ObjectId("4b06bebea9ad6390dab17c44"), "scores" : { "quiz1" : 98, "midterm" : 100, "quiz2" : 73, "final" : 85 } }
The database can also save arbitrary PHP objects (although they will be returned as associative arrays). The fields are used for the key/value pairs. For example, a blog post might look like:
<?php
// the blog post class
class Post {
var $author;
var $content;
var $comments = array();
var $date;
public function __construct($author, $content) {
$this->author = $author;
$this->content = $content;
$this->date = new MongoDate();
}
public function setTitle($title) {
$this->title = $title;
}
}
// create a simple blog post and insert it into the database
$post1 = new Post("Adam", "This is a blog post");
$blog->insert($post1);
// there is nothing restricting the type of the "author" field, so we can make
// it a nested object
$author = array("name" => "Fred", "karma" => 42);
$post2 = new Post($author, "This is another blog post.");
// we create an extra field by setting the title
$post2->setTitle("Second Post");
$blog->insert($post2);
?>
From the database shell, this will look something like:
> db.blog.find()
{ "_id" : ObjectId("4b06c263edb87a281e09dad8"), "author" : "Adam", "content" : "This is a blog post", "comments" : [ ], "date" : "Fri Nov 20 2009 11:22:59 GMT-0500 (EST)" }
{ "_id" : ObjectId("4b06c282edb87a281e09dad9"), "author" : { "name" : "Fred", "karma" : 42 }, "content" : "This is a blog post", "comments" : [ ], "date" : "Fri Nov 20 2009 11:23:30 GMT-0500 (EST)", "title" : "Second Post" }
The driver will not detect reference loops in arrays and objects. For example, this will give a fatal error:
<?php
$collection->insert($GLOBALS);
?>
Fatal error: Nesting level too deep - recursive dependency?
The MongoId class
(No version information available, might only be in SVN)
Wstęp
A unique identifier created for database objects. If an object is inserted into the database without an _id field, an _id field will be added to it with a MongoId instance as its value. If the data has a naturally occuring unique field (say, a username or timestamp) it is fine to use this as the _id field instead, and it will not be replaced with a MongoId.
Instances of the MongoId class fulfill the role that autoincrementing does in a relational database: to provide a unique key if the data does not natually have one. Autoincrementing does not work well with a sharded database, as it is impossible to find what the next number should be quickly. This class fulfills the constraints of quickly generating a value that is unique across shards.
Each MongoId is 12 bytes (making its string form 24 hexidecimal characters). The first four bytes are a timestamp, the next three are a hash of the client machine's hostname, the next two are the two least significant bytes of the process id running the script, and the last three bytes are an incrementing value.
MongoIds are serializable/unserializable. Their serialized form is similar to their string form:
C:7:"MongoId":24:{4af9f23d8ead0e1d32000000}
Krótki opis klasy
Fields
- id
- This field contains the string representation of this object.
Zobacz też:
MongoDB core docs on » ids.
MongoId::__construct
(PECL mongo >= 0.8.0)
MongoId::__construct — Creates a new id
Opis
$id = NULL
] )Parametry
-
id -
A string to use as the id. Must be 24 hexidecimal characters. If an invalid string is passed to this constructor, the constructor will ignore it and create a new id value.
Zwracane wartości
Returns a new id.
Przykłady
Przykład #1 MongoId::__construct() example
This example shows how to create a new id. This is seldom necessary, as the driver adds an id to arrays automatically before storing them in the database.
<?php
$id1 = new MongoId();
echo "$id1\n";
$id2 = new MongoId();
echo "$id2\n";
?>
Powyższy przykład wyświetli coś podobnego do:
49a7011a05c677b9a916612a 49a702d5450046d3d515d10d
Przykład #2 Parameter example
This example shows how to use a string parameter to initialize a MongoId with a given value.
<?php
$id1 = new MongoId();
// create a new id from $id1
$id2 = new MongoId("$id1");
// show that $id1 and $id2 have the same hexidecimal value
var_dump($id1 == $id2);
?>
Powyższy przykład wyświetli coś podobnego do:
bool(true)
MongoId::getHostname
(PECL mongo >= 1.0.8)
MongoId::getHostname — Gets the hostname being used for this machine's ids
Opis
This returns the hostname MongoId is using to generate unique ids. This should be the same value gethostname() returns.
It is identical to the function:
<?php
public static function getHostname() {
return gethostname();
}
?>
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the hostname.
MongoId::getInc
(PECL mongo >= 1.0.11)
MongoId::getInc — Gets the incremented value to create this id
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the incremented value used to create this MongoId.
MongoId::getPID
(PECL mongo >= 1.0.11)
MongoId::getPID — Gets the process id used to create this
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the PID used to create this MongoId.
MongoId::getTimestamp
(PECL mongo >= 1.0.1)
MongoId::getTimestamp — Gets the number of seconds since the epoch that this id was created
Opis
This returns the same thing as running time() when the id is created.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the number of seconds since the epoch that this id was created. There are only four bytes of timestamp stored, so MongoDate is a better choice for storing exact or wide-ranging times.
MongoId::__set_state
(PECL mongo >= 1.0.8)
MongoId::__set_state — Create a dummy MongoId
Opis
This function is only used by PHP internally, it shouldn't need to ever be called by the user.
It is identical to the function:
<?php
public static function __set_state($props) {
return new MongoId("000000000000000000000000");
}
?>
Parametry
-
props -
Theoretically, an array of properties used to create the new id. However, as MongoId instances have no properties, this is not used.
Zwracane wartości
A new id with the value "000000000000000000000000".
MongoId::__toString
(PECL mongo >= 0.8.0)
MongoId::__toString — Returns a hexidecimal representation of this id
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
This id.
Przykłady
Przykład #1 MongoId::__toString() example
<?php
$m = new Mongo();
$collection = $m->selectDB("foo")->selectCollection("bar");
$collection->insert(array( "x" => "y" ));
$collection->insert(array( "x" => "y" ));
$cursor = $collection->find();
$r1 = $cursor->next();
$r2 = $cursor->next();
echo $r1["_id"] . "\n";
echo $r2["_id"] . "\n";
?>
Powyższy przykład wyświetli coś podobnego do:
49a7011a05c677b9a916612a 49a702d5450046d3d515d10d
Spis treści
- MongoId::__construct — Creates a new id
- MongoId::getHostname — Gets the hostname being used for this machine's ids
- MongoId::getInc — Gets the incremented value to create this id
- MongoId::getPID — Gets the process id used to create this
- MongoId::getTimestamp — Gets the number of seconds since the epoch that this id was created
- MongoId::__set_state — Create a dummy MongoId
- MongoId::__toString — Returns a hexidecimal representation of this id
The MongoCode class
(No version information available, might only be in SVN)
Wstęp
Represents JavaScript code for the database.
MongoCode objects are composed of two parts: a string of code and an optional scope. The string of code must be valid JavaScript. The scope is a associative array of variable name/value pairs.
Krótki opis klasy
MongoCode::__construct
(PECL mongo >= 0.8.3)
MongoCode::__construct — Creates a new code object
Opis
$code
[, array $scope = array()
] )Parametry
-
code -
A string of code.
-
scope -
The scope to use for the code.
Zwracane wartości
Returns a new code object.
Przykłady
Przykład #1 MongoCode::__construct() example
<?php
$code = new MongoCode('function() { '.
'for(i=0;i<10;i++) {'.
'db.foo.update({z : i}, {z : x});'.
'}'.
'return x-1;'.
'}', array("x" => 4));
var_dump($code);
?>
Powyższy przykład wyświetli coś podobnego do:
object(MongoCode)#1 (2) {
["scope"]=>
array(1) {
["x"]=>
int(4)
}
["code"]=>
string(80) "function() { for(i=0;i<10;i++) { db.foo.update({z : i}, {z : x}); } return x-1; }"
}
Przykład #2 Using MongoCode() with $where
This example queries a collection for elements where the 'x' fields is less than $y. Notice that PHP objects can be passed into the JavaScript scope and that the JavaScript function returns a boolean.
<?php
$cursor = $collection->find(array('$where' => new MongoCode('function() { return this.x < y; }', array('y'=>$y))));
?>
MongoCode::__toString
(PECL mongo >= 0.8.3)
MongoCode::__toString — Returns this code as a string
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
This code, the scope is not returned.
Przykłady
Przykład #1 MongoCode::__toString() example
<?php
$code = new MongoCode('return x;', array("x"=>"hi"));
echo "$code\n";
$code = new MongoCode('function() { for(i=0;i<10;i++) { db.foo.update({x:i}, {x:i+1}); } }');
echo "$code\n";
?>
Powyższy przykład wyświetli coś podobnego do:
return x;
function() { for(i=0;i<10;i++) { db.foo.update({x:i}, {x:i+1}); } }
Spis treści
- MongoCode::__construct — Creates a new code object
- MongoCode::__toString — Returns this code as a string
The MongoDate class
(No version information available, might only be in SVN)
Wstęp
Represent date objects for the database. This class should be used to save dates to the database and to query for dates. For example:
<?php
// save a date to the database
$collection->save(array("ts" => new MongoDate()));
$start = new MongoDate(strtotime("2010-01-15 00:00:00"));
$end = new MongoDate(strtotime("2010-01-30 00:00:00"));
// find dates between 1/15/2010 and 1/30/2010
$collection->find(array("ts" => array('$gt' => $start, '$lte' => $end)));
?>
MongoDB stores dates as milliseconds past the epoch. This means that dates do not contain timezone information. Timezones must be stored in a separate field if needed. Second, this means that any precision beyond milliseconds will be lost when the document is sent to/from the database.
Krótki opis klasy
MongoDate::__construct
(PECL mongo >= 0.8.1)
MongoDate::__construct — Creates a new date.
Opis
$sec = time()
[, int $usec = 0
]] )Creates a new date. If no parameters are given, the current time is used.
Parametry
-
sec -
Number of seconds since January 1st, 1970.
-
usec -
Microseconds.
Zwracane wartości
Returns this new date.
Przykłady
Przykład #1 MongoDate::__construct() example
This example demonstrates creating a new date with the current time and a new date with a given time.
<?php
$d = new MongoDate();
echo "$d\n";
$d = new MongoDate(1234567890);
echo "$d\n";
$d = new MongoDate(strtotime("2009-05-01 00:00:01"));
echo "$d\n";
?>
Powyższy przykład wyświetli coś podobnego do:
0.23660600 1235685067 0.00000000 1234567890 0.00000000 1241150401
MongoDate::__toString
(PECL mongo >= 0.8.1)
MongoDate::__toString — Returns a string representation of this date
Opis
Returns a string representation of this date, similar to the representation returned by microtime().
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
This date.
Spis treści
- MongoDate::__construct — Creates a new date.
- MongoDate::__toString — Returns a string representation of this date
The MongoRegex class
(No version information available, might only be in SVN)
Wstęp
This class can be used to create regular expressions. Typically, these expressions will be used to query the database and find matching strings. More unusually, they can be saved to the database and retrieved.
Mongo recognizes six regular expression flags:
-
i
Case insensitive
-
m
Multiline
-
x
Can contain comments
-
l
locale
-
s
dotall, "." matches everything, including newlines
-
u
match unicode
Krótki opis klasy
MongoRegex::__construct
(PECL mongo >= 0.8.1)
MongoRegex::__construct — Creates a new regular expression
Opis
$regex
)Creates a new regular expression.
Parametry
-
regex -
Regular expression string of the form /expr/flags.
Zwracane wartości
Returns a new regular expression.
Przykłady
Przykład #1 MongoRegex::__construct() example
This example uses a regular expression to query for all documents with a username field matching a regular expression.
<?php
$joe_search = new MongoRegex("/j[o0]e/i");
$cursor = $collection->find(array("username" => $joe_search));
?>
MongoRegex::__toString
(PECL mongo >= 0.8.1)
MongoRegex::__toString — A string representation of this regular expression
Opis
Returns a string representation of this regular expression.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
This regular expression in the form "/expr/flags".
Przykłady
Przykład #1 MongoRegex::__toString() example
<?php
$r = new MongoRegex( "/[a-fA-F0-9]{16}/g" );
echo $r->regex . "\n";
echo $r->flags . "\n";
echo "$r\n";
?>
Powyższy przykład wyświetli coś podobnego do:
[a-fA-F0-9]{16}
g
/[a-fA-F0-9]{16}/g
Spis treści
- MongoRegex::__construct — Creates a new regular expression
- MongoRegex::__toString — A string representation of this regular expression
The MongoBinData class
(No version information available, might only be in SVN)
Wstęp
An object that can be used to store or retrieve binary data from the database.
The maximum size of a single object that can be inserted into the database is 4Mb. For data that is larger than this (movies, music, Henry Kissinger's autobiography), use MongoGridFS. For data that is smaller than 4Mb, it's probably be easier to just embed it into the document using MongoBinData.
For example, to embed an image in a document, one could write:
<?php
$profile = array("username" => "foobity",
"pic" => new MongoBinData(file_get_contents("gravatar.jpg"))
);
$users->save($profile);
?>
This class contains a type field, which currently gives no additional functionality in the driver or the database. There are five predefined types (which are the class constants listed below), and the user can create their own (at the risk of the BSON spec catching up with them). By default, the PHP driver always uses type 2: a byte array.
Krótki opis klasy
Stałe predefiniowane
Binary Data Types
-
MongoBinData::FUNC0x01 - Function.
-
MongoBinData::BYTE_ARRAY0x02 - Array of bytes.
-
MongoBinData::UUID0x03 - Universally unique identifier.
-
MongoBinData::MD50x05 - MD5.
-
MongoBinData::CUSTOM0xf0 - User-defined type.
MongoBinData::__construct
(PECL mongo >= 0.8.1)
MongoBinData::__construct — Creates a new binary data object.
Opis
$data
[, int $type = 2
] )Creates a new binary data object.
There are five types of binary data currently recognized by the BSON spec: function (0x01), byte array (0x02), UUID (0x03), MD5 (0x05), and user defined (0x80). The default type is byte array (0x02). There is no particular difference in how the driver or server interpret different types, so by and large they are irrelevant for now. Any number (between 0 and 255) could be used for type, if the user is willing to assume the risk that the database might eventually do something with binary data based on type.
Parametry
-
data -
Binary data.
-
type -
Data type.
Zwracane wartości
Returns a new binary data object.
MongoBinData::__toString
(PECL mongo >= 0.8.1)
MongoBinData::__toString — The string representation of this binary data object.
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the string "<Mongo Binary Data>". To access the contents of a MongoBinData, use the bin field.
Spis treści
- MongoBinData::__construct — Creates a new binary data object.
- MongoBinData::__toString — The string representation of this binary data object.
The MongoInt32 class
(No version information available, might only be in SVN)
Wstęp
The class can be used to save 32-bit integers to the database on a 64-bit system.
Krótki opis klasy
Fields
- value
- This is the string value of the 64-bit number. For instance, 123's value would be "123".
MongoInt32::__construct
(PECL mongo >= 1.0.9)
MongoInt32::__construct — Creates a new 32-bit integer.
Opis
$value
)Creates a new 32-bit number with the given value.
Parametry
-
value -
A number.
Zwracane wartości
Returns a new integer.
MongoInt32::__toString
(PECL mongo >= 1.0.9)
MongoInt32::__toString — Returns the string representation of this 32-bit integer.
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the string representation of this integer.
Spis treści
- MongoInt32::__construct — Creates a new 32-bit integer.
- MongoInt32::__toString — Returns the string representation of this 32-bit integer.
The MongoInt64 class
(No version information available, might only be in SVN)
Wstęp
The class can be used to save 64-bit integers to the database on a 32-bit system.
Krótki opis klasy
Fields
- value
- This is the string value of the 64-bit number. For instance, 123's value would be "123".
MongoInt64::__construct
(PECL mongo >= 1.0.9)
MongoInt64::__construct — Creates a new 64-bit integer.
Opis
$value
)Creates a new 64-bit number with the given value.
Parametry
-
value -
A number.
Zwracane wartości
Returns a new integer.
MongoInt64::__toString
(PECL mongo >= 1.0.9)
MongoInt64::__toString — Returns the string representation of this 64-bit integer.
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the string representation of this integer.
Spis treści
- MongoInt64::__construct — Creates a new 64-bit integer.
- MongoInt64::__toString — Returns the string representation of this 64-bit integer.
The MongoDBRef class
(No version information available, might only be in SVN)
Wstęp
This class can be used to create lightweight links between objects in different collections.
Motivation: Suppose we need to refer to a document in another collection. The easiest way is to create a field in the current document. For example, if we had a "people" collection and an "addresses" collection, we might want to create a link between each person document and an address document:
<?php
$people = $db->people;
$addresses = $db->addresses;
$myAddress = array("line 1" => "123 Main Street",
"line 2" => null,
"city" => "Springfield",
"state" => "Vermont",
"country" => "USA");
// save the address
$addresses->insert($myAddress);
// save a person with a reference to the address
$me = array("name" => "Fred", "address" => $myAddress['_id']);
$people->insert($me);
?>
Then, later on, we can find the person's address by querying the "addresses" collection with the MongoId we saved in the "people" collection.
Suppose now that we have a more general case, where we don't know which collection (or even which database) contains the referenced document. MongoDBRef is a good choice for this case, as it is a common format that all of the drivers and the database understand.
If each person had a list of things they liked which could come from multiple collections, such as "hobbies", "sports", "books", etc., we could use MongoDBRefs to keep track of what "like" went with what collection:
<?php
$people = $db->selectCollection("people");
// model trains are in the "hobbies" collection
$trainRef = MongoDBRef::create("hobbies", $modelTrains['_id']);
// soccer is in the "sports" collection
$soccerRef = MongoDBRef::create("sports", $soccer['_id']);
// now we'll know what collections the items in the "likes" array came from when
// we retrieve this document
$people->insert(array("name" => "Fred", "likes" => array($trainRef, $soccerRef)));
?>
Database references can be thought of as hyperlinks: they give the unique address of another document, but they do not load it or automatically follow the link/reference.
A database reference is just a normal associative array, not an instance of MongoDBRef, so this class is a little different than the other data type classes. This class contains exclusively static methods for manipulating database references.
Krótki opis klasy
Zobacz też:
MongoDB core docs on » databases references.
MongoDBRef::create
(PECL mongo >= 0.9.0)
MongoDBRef::create — Creates a new database reference
Opis
If no database is given, the current database is used.
Parametry
-
collection -
Collection name (without the database name).
-
id -
The _id field of the object to which to link.
-
database -
Database name.
Zwracane wartości
Returns the reference.
Przykłady
Przykład #1 MongoDBRef::create() example
This creates a database reference to a document in the addresses collection. The MongoCollection::getName() function returns the name of the collection (not including the database name).
<?php
$addresses = $db->addresses;
$people = $db->people;
// save $address so it has an _id
$addresses->insert($address);
// create a reference
$ref = MongoDBRef::create($addresses->getName(), $address['_id']);
// set the field in $person
$person['address'] = $ref;
$people->save($person);
?>
Zobacz też:
- MongoDB::createDBRef() - Creates a database reference
- MongoCollection::createDBRef() - Creates a database reference
MongoDBRef::get
(PECL mongo >= 0.9.0)
MongoDBRef::get — Fetches the object pointed to by a reference
Opis
Parametry
-
db -
Database to use.
-
ref -
Reference to fetch.
Zwracane wartości
Returns the document to which the reference refers or NULL if the document
does not exist (the reference is broken).
Przykłady
Przykład #1 MongoCollection::createDBRef() example
<?php
// get $person out of the db
$person = $people->findOne();
// dereference the address
$address = MongoDBRef::get($people->db, $person['address']);
?>
Zobacz też:
- MongoDB::getDBRef() - Fetches the document pointed to by a database reference
- MongoCollection::getDBRef() - Fetches the document pointed to by a database reference
MongoDBRef::isRef
(PECL mongo >= 0.9.0)
MongoDBRef::isRef — Checks if an array is a database reference
Opis
This not actually follow the reference, so it does not determine if it is
broken or not. It merely checks that ref is in valid
database reference format (in that it is an object or array with $ref and $id
fields).
Parametry
-
ref -
Array or object to check.
Zwracane wartości
Returns if ref is a reference.
Spis treści
- MongoDBRef::create — Creates a new database reference
- MongoDBRef::get — Fetches the object pointed to by a reference
- MongoDBRef::isRef — Checks if an array is a database reference
The MongoMinKey class
(No version information available, might only be in SVN)
Wstęp
MongoMinKey is a special type used by the database that evaluates to less than any other type. Thus, if a query is sorted by a given field in ascending order, any document with a MongoMinKey as its value will be returned first.
MongoMinKey has no associated fields, methods, or constants. It is merely the "smallest" thing that can be inserted into the database.
Krótki opis klasy
Using MongoMinKey as a value
<?php
$collection->insert(array("task" => "lunch", "do by" => new MongoMinKey));
$collection->insert(array("task" => "staff meeting", "do by" => new MongoDate(strtotime("+4 days"))));
$cursor = $collection->find()->sort(array("do by" => 1));
?>
The cursor will contain the lunch document, then the staff meeting document. The lunch document will always be returned first, regardless of what else is added to the collection (unless other documents are added with MongoMinKey in the "do by" field).
The MongoMaxKey class
(No version information available, might only be in SVN)
Wstęp
MongoMaxKey is a special type used by the database that evaluates to greater than any other type. Thus, if a query is sorted by a given field in ascending order, any document with a MongoMaxKey as its value will be returned last.
MongoMaxKey has no associated fields, methods, or constants. It is merely the "largest" thing that can be inserted into the database.
Krótki opis klasy
Using MongoMaxKey as a value
<?php
$collection->insert(array("task" => "dishes", "do by" => new MongoMaxKey));
$collection->insert(array("task" => "staff meeting", "do by" => new MongoDate(strtotime("+4 days"))));
$cursor = $collection->find()->sort(array("do by" => 1));
?>
The cursor will contain the staff meeting document, then the dishes document. The dishes document will always be returned last, regardless of what else is added to the collection (unless other documents are added with MongoMaxKey in the "do by" field).
The MongoTimestamp class
(No version information available, might only be in SVN)
Wstęp
MongoTimestamp is used by sharding. If you're not looking to write sharding tools, what you probably want is MongoDate.
MongoTimestamp is 4 bytes of timestamp (seconds since the epoch) and 4 bytes of increment.
This class is not for measuring time, creating a timestamp on a document or automatically adding or updating a timestamp on a document. Unless you are writing something that interacts with the sharding internals, stop, go directly to MongoDate, do not pass go, do not collect 200 dollars. This is not the class you are looking for.
If you are writing sharding tools, read on.
Krótki opis klasy
MongoTimestamp::__construct
(PECL mongo >= 1.0.1)
MongoTimestamp::__construct — Creates a new timestamp.
Opis
$sec = time()
[, int $inc
]] )Creates a new timestamp. If no parameters are given, the current time is used and the increment is automatically provided. The increment is set to 0 when the module is loaded and is incremented every time this constructor is called (without the $inc parameter passed in).
Parametry
-
sec -
Number of seconds since January 1st, 1970.
-
inc -
Increment.
Zwracane wartości
Returns this new timestamp.
MongoTimestamp::__toString
(PECL mongo >= 1.0.1)
MongoTimestamp::__toString — Returns a string representation of this timestamp
Opis
Returns the "sec" field of this timestamp.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
The seconds since epoch represented by this timestamp.
Spis treści
- MongoTimestamp::__construct — Creates a new timestamp.
- MongoTimestamp::__toString — Returns a string representation of this timestamp
GridFS Classes
Spis treści
The MongoGridFS class
(No version information available, might only be in SVN)
Wstęp
Utilities for storing and retrieving files from the database.
GridFS is a storage specification all supported drivers implement. Basically, it defines two collections: files, for file metadata, and chunks, for file content. If the file is large, it will automatically be split into smaller chunks and each chunk will be saved as a document in the chunks collection.
Each document in the files collection contains the filename, upload date, and md5 hash. It also contains a unique _id field, which can be used to query the chunks collection for the file's content. Each document in the chunks collection contains a chunk of binary data, a files_id field that matches its file's _id, and the position of this chunk in the overall file.
For example, the files document is something like:
<?php
array("_id" => 123456789, "filename" => "foo.txt", "chunkSize" => 3, "length" => 12);
?>
<?php
array("files_id" => 123456789, "n" => 0, "data" => new MongoBinData("abc"));
array("files_id" => 123456789, "n" => 1, "data" => new MongoBinData("def"));
array("files_id" => 123456789, "n" => 2, "data" => new MongoBinData("ghi"));
array("files_id" => 123456789, "n" => 3, "data" => new MongoBinData("jkl"));
?>
Inter-Language Compatibility
You should be able to use any files created by MongoGridFS with any other drivers, and vice versa. However, some drivers expect that all metadata associated with a file be in a "metadata" field. If you're going to be using other languages, it's a good idea to wrap info you might want them to see in a "metadata" field. For example, instead of:
<?php
$grid->storeFile("somefile.txt", array("date" => new MongoDate()));
?>
use something like:
<?php
$grid->storeFile("somefile.txt", array("metadata" => array("date" => new MongoDate())));
?>
The MongoGridFS Family
MongoGridFS represents the files and chunks collections. MongoGridFS extends MongoCollection, and an instance of MongoGridFS has access to all of MongoCollection methods, which act on the files collection:
<?php
$grid = $db->getGridFS();
$grid->update(array("filename" => "foo"), $newObj); // update on the files collection
?>
Another example of manipulating metadata:
<?php
// save a file
$id = $grid->storeFile("game.tgz");
$game = $grid->findOne();
// add a downloads counter
$game->file['downloads'] = 0;
$grid->save($game->file);
// increment the counter
$grid->update(array("_id" => $id), array('$inc' => array("downloads" => 1)));
?>
You can also access the chunks collection from an instance of MongoGridFS:
<?php
$chunks = $grid->chunks; // $chunks is a normal MongoCollection
$chunks->insert(array("x" => 4));
?>
There are some methods for MongoGridFS with the same name as MongoCollection methods, that behave slightly differently. For example, MongoGridFS::remove() will remove any objects that match the criteria from the files collection and their content from the chunks collection.
To store something new in GridFS, there are a couple options. If you have a filename, you can say:
<?php
$grid->storeFile($filename, array("whatever" => "metadata", "you" => "want"));
?>
If you have a string of bytes that isn't a file, you can also store that using MongoGridFS::storeBytes():
<?php
$grid->storeBytes($bytes, array("whatever" => "metadata", "you" => "want"));
?>
Querying a MongoGridFS collection returns a MongoGridFSCursor, which behaves like a normal MongoCursor except that it returns MongoGridFSFiles instead of associative arrays.
MongoGridFSFiles can be written back to disc using MongoGridFSFile::write() or retrieved in memory using MongoGridFSFile::getBytes(). There is currently no method that automatically streams chunks, but it would be fairly easy to write by querying the $grid->chunks collection.
MongoGridFSFile objects contain a field file which contains any file metadata.
Krótki opis klasy
NULL
;NULL
;$filename
[, array $extra = array()
[, array $options = array()
]] )Zobacz też:
MongoDB core docs on » GridFS. There's also a nice intro to » saving user uploads and » adding metadata at LightCubeSolutions.com.
MongoGridFS::__construct
(PECL mongo >=0.9.0)
MongoGridFS::__construct — Creates new file collections
Opis
Files as stored across two collections, the first containing file meta information, the second containing chunks of the actual file. By default, fs.files and fs.chunks are the collection names used.
Use one argument to specify a prefix other than "fs":
$fs = new MongoGridFS($db, "myfiles");
Parametry
-
db -
Database.
-
files -
Optional collection name prefix.
MongoGridFS::delete
(PECL mongo >=1.0.8)
MongoGridFS::delete — Delete a file from the database
Opis
Parametry
-
id -
_id of the file to remove.
Zwracane wartości
Returns if the remove was successfully sent to the database.
MongoGridFS::drop
(PECL mongo >=0.9.0)
MongoGridFS::drop — Drops the files and chunks collections
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
The database response.
MongoGridFS::find
(PECL mongo >=0.9.0)
MongoGridFS::find — Queries for files
Opis
$query = array()
[, array $fields = array()
]] )Parametry
-
query -
The query.
-
fields -
Fields to return.
Zwracane wartości
MongoGridFS::findOne
(PECL mongo >=0.9.0)
MongoGridFS::findOne — Returns a single file matching the criteria
Opis
$query = array()
[, mixed $fields = array()
]] )Parametry
-
query -
The filename or criteria for which to search.
Zwracane wartości
Returns a MongoGridFSFile or NULL.
Przykłady
Przykład #1 MongoGridFS::findOne() example
Example demonstrating how to find a single file from the MongoGridFS.
<?php
$downloads = $mongo->my_db->getGridFS('downloads');
$downloads->storeFile('filename.tgz');
$download = $downloads->findOne('filename.tgz'); // instance of MongoGridFSFile
print_r($download);
?>
See MongoGridFSFile for more information about how to work with files.
Powyższy przykład wyświetli coś podobnego do:
MongoGridFSFile Object
(
[file] => Array
(
[_id] => MongoId Object
(
)
[filename] => filename.tgz
[uploadDate] => MongoDate Object
(
[sec] => 1274288014
[usec] => 467000
)
[chunkSize] => 262144
[md5] => d41d8cd98f00b204e9800998ecf8427e
)
[gridfs:protected] => MongoGridFS Object
(
[chunks] => MongoCollection Object
(
)
[filesName:protected] => downloads.files
[chunksName:protected] => downloads.chunks
)
)
MongoGridFS::get
(PECL mongo >=1.0.8)
MongoGridFS::get — Retrieve a file from the database
Opis
Parametry
-
id -
_id of the file to find.
Zwracane wartości
Returns the file, if found, or NULL.
MongoGridFS::put
(PECL mongo >=1.0.8)
MongoGridFS::put — Stores a file in the database
Opis
Parametry
-
filename -
The name of the file.
-
extra -
Other metadata to add to the file saved.
Zwracane wartości
Returns the _id of the saved object.
MongoGridFS::remove
(PECL mongo >=0.9.0)
MongoGridFS::remove — Removes files from the collections
Opis
$criteria = array()
[, array $options = array()
]] )Parametry
-
query -
The filename or criteria for which to search.
-
options -
Options for the remove. Valid options are:
-
"safe"
Check that the remove succeeded.
-
Zwracane wartości
Returns if the removal was successfully sent to the database.
MongoGridFS::storeBytes
(PECL mongo >=0.9.2)
MongoGridFS::storeBytes — Chunkifies and stores bytes in the database
Opis
$bytes
[, array $extra = array()
[, array $options = array()
]] )Parametry
-
bytes -
A string of bytes to store.
-
extra -
Other metadata to add to the file saved.
-
options -
Options for the store.
-
"safe"
Check that this store succeeded.
-
Zwracane wartości
The _id of the object saved.
Błędy/Wyjątki
Throws MongoCursorException if the "safe" option is set and the insert fails.
MongoGridFS::storeFile
(PECL mongo >=0.9.0)
MongoGridFS::storeFile — Stores a file in the database
Opis
$filename
[, array $extra = array()
[, array $options = array()
]] )Parametry
-
filename -
The name of the file.
-
extra -
Other metadata to add to the file saved.
-
options -
Options for the store.
-
"safe"
Check that this store succeeded.
-
Zwracane wartości
Returns the _id of the saved object.
Błędy/Wyjątki
Throws MongoCursorException if the "safe" option is set and the insert fails.
MongoGridFS::storeUpload
(PECL mongo >=0.9.0)
MongoGridFS::storeUpload — Saves an uploaded file to the database
Opis
Stores files directly from a POST to the database. For example, suppose you had the following HTML form:
<form method="POST" enctype="multipart/form-data">
Please upload a profile picture: <input type="file" name="pic"/>
<input type="submit"/>
</form>
If you wanted to store this upload in MongoDB, you could do:
<?php
$grid->storeUpload("pic", array("username" => "joe"));
?>
Note that the "name" field in HTML matches the name parameter.
Parametry
-
name -
The name field of the uploaded file.
-
metadata -
An array of extra fields for the uploaded file.
Zwracane wartości
Returns the _id of the uploaded file.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 1.2.5 | Changed second parameter to an array of metadata. Pre-1.2.5, the second parameter was an optional string overriding the filename. |
Spis treści
- MongoGridFS::__construct — Creates new file collections
- MongoGridFS::delete — Delete a file from the database
- MongoGridFS::drop — Drops the files and chunks collections
- MongoGridFS::find — Queries for files
- MongoGridFS::findOne — Returns a single file matching the criteria
- MongoGridFS::get — Retrieve a file from the database
- MongoGridFS::put — Stores a file in the database
- MongoGridFS::remove — Removes files from the collections
- MongoGridFS::storeBytes — Chunkifies and stores bytes in the database
- MongoGridFS::storeFile — Stores a file in the database
- MongoGridFS::storeUpload — Saves an uploaded file to the database
The MongoGridFSFile class
(No version information available, might only be in SVN)
Wstęp
A database file object.
Krótki opis klasy
NULL
;MongoGridfsFile::__construct
(PECL mongo >=0.9.0)
MongoGridfsFile::__construct — Create a new GridFS file
Opis
Parametry
-
gridfs -
The parent MongoGridFS instance.
-
file -
A file from the database.
Zwracane wartości
Returns a new MongoGridFSFile.
MongoGridFSFile::getBytes
(PECL mongo >=0.9.0)
MongoGridFSFile::getBytes — Returns this file's contents as a string of bytes
Opis
Warning: this will load the file into memory. If the file is bigger than your memory, this will cause problems!
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns a string of the bytes in the file.
Przykłady
Przykład #1 MongoGridFSFile::getBytes() example
<?php
$images = $db->my_db->getGridFS('images');
$image = $images->findOne('jwage.png');
header('Content-type: image/png;');
echo $image->getBytes();
?>
MongoGridFSFile::getFilename
(PECL mongo >=0.9.0)
MongoGridFSFile::getFilename — Returns this file's filename
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the filename.
MongoGridFSFile::getResource
(No version information available, might only be in SVN)
MongoGridFSFile::getResource — Returns a resource that can be used to read the stored file
Opis
This method returns a stream resource that can be used with all file functions in PHP. The contents of the file are pulled out of MongoDB on the fly, so that the whole file does not have to be loaded into memory first.
At most two GridFSFile chunks will be loaded in memory.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns a resource that can be used to read the file with
Przykłady
Przykład #1 MongoGridFSFile::getResource() example
<?php
$m = new Mongo;
$images = $m->my_db->getGridFS('images');
$image = $images->findOne('mongo.png');
header('Content-type: image/png;');
$stream = $image->getResource();
while (!feof($stream)) {
echo fread($stream, 8192);
}
?>
MongoGridFSFile::getSize
(PECL mongo >=0.9.0)
MongoGridFSFile::getSize — Returns this file's size
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns this file's size
MongoGridFSFile::write
(PECL mongo >=0.9.0)
MongoGridFSFile::write — Writes this file to the filesystem
Opis
$filename = NULL
] )Parametry
-
filename -
The location to which to write the file. If none is given, the stored filename will be used.
Zwracane wartości
Returns the number of bytes written.
Przykłady
Przykład #1 MongoGridFSFile::write() example
<?php
$images = $db->my_db->getGridFS('images');
$image = $images->findOne('jwage.png');
$image->write('/path/to/write/jwage.png');
?>
Spis treści
- MongoGridfsFile::__construct — Create a new GridFS file
- MongoGridFSFile::getBytes — Returns this file's contents as a string of bytes
- MongoGridFSFile::getFilename — Returns this file's filename
- MongoGridFSFile::getResource — Returns a resource that can be used to read the stored file
- MongoGridFSFile::getSize — Returns this file's size
- MongoGridFSFile::write — Writes this file to the filesystem
The MongoGridFSCursor class
(No version information available, might only be in SVN)
Wstęp
Cursor for database file results.
Krótki opis klasy
$gridfs
, resource $connection
, string $ns
, array $query
, array $fields
)MongoGridFSCursor::__construct
(PECL mongo >=0.9.0)
MongoGridFSCursor::__construct — Create a new cursor
Opis
$gridfs
, resource $connection
, string $ns
, array $query
, array $fields
)Parametry
-
gridfs -
Related GridFS collection.
-
connection -
Database connection.
-
ns -
Full name of database and collection.
-
query -
Database query.
-
fields -
Fields to return.
Zwracane wartości
Returns the new cursor.
MongoGridFSCursor::current
(PECL mongo >=0.9.0)
MongoGridFSCursor::current — Returns the current file
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
The current file.
MongoGridFSCursor::getNext
(PECL mongo >=0.9.0)
MongoGridFSCursor::getNext — Return the next file to which this cursor points, and advance the cursor
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the next file.
MongoGridFSCursor::key
(PECL mongo >=0.9.0)
MongoGridFSCursor::key — Returns the current result's filename
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
The current result's filename.
Spis treści
- MongoGridFSCursor::__construct — Create a new cursor
- MongoGridFSCursor::current — Returns the current file
- MongoGridFSCursor::getNext — Return the next file to which this cursor points, and advance the cursor
- MongoGridFSCursor::key — Returns the current result's filename
Miscellaneous
Spis treści
The MongoLog class
(No version information available, might only be in SVN)
Wstęp
Logging can be used to get detailed information about what the driver is doing. With PHP-CLI, log output will be printed to stderr. Under an app server, log messages will generally be printed to an error log.
Logging is turned off, by default. This class allows you to turn on specific levels of logging for specific parts of the driver. Some examples:
<?php
// print every log message possible
MongoLog::setLevel(MongoLog::ALL); // all log levels
MongoLog::setModule(MongoLog::ALL); // all parts of the driver
// print significant events about replica set failover
MongoLog::setLevel(MongoLog::INFO);
MongoLog::setModule(MongoLog::RS);
// print info- and server tuning-level events from replica sets and connection pooling
MongoLog::setLevel(MongoLog::INFO|MongoLog::FINE);
MongoLog::setModule(MongoLog::RS|MongoLog::POOL);
?>
Krótki opis klasy
Stałe predefiniowane
MongoLog Constants
These constants can be used by both MongoLog::setLevel() and MongoLog::setModule().
-
MongoLog::NONE - Constant for turning logging off.
-
MongoLog::ALL - Constant for logging everything.
MongoLog Level Constants
These constants can be used by MongoLog::setLevel().
-
MongoLog::WARNING - This will print log messages about somewhat exceptional but not-quite-exception-worthy happenings.
-
MongoLog::INFO - Logs events that may be of interest to administrators, but are not particularly noteworthy.
-
MongoLog::FINE - Logs most events that the driver performs. Depending on the module being logged, this can be extremely noisy and is primarily for debugging.
MongoLog Module Constants
These constants can be used by MongoLog::setModule().
-
MongoLog::IO - Logs traffic to/from the database. Unless your program is trivial, this will create an enormous number of log messages.
-
MongoLog::PARSE - Log server string parsing.
-
MongoLog::POOL - Log connection pool activity. Creating new connections, reusing connections, and closing connections.
-
MongoLog::RS - Log replica set activity. Failovers, pinging, chosing secondaries to read from, etc.
-
MongoLog::SERVER - Log server status changes. Detecting primary, secondary and duplication detection.
MongoLog::getLevel
(No version information available, might only be in SVN)
MongoLog::getLevel — Gets the log level
Opis
This can be used to see the log level. Use the constants described in the MongoLog section with bitwise operators to check the level.
<?php
if (MongoLog::getLevel() & MongoLog::FINE) {
echo "lots 'o logs\n";
}
if (MongoLog::getLevel() ^ MongoLog::NONE) {
echo "logging, at least a little\n";
}
if (MongoLog::getLevel() == MongoLog::ALL) {
echo "logging at the highest levels\n";
}
?>
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the current level.
MongoLog::getModule
(No version information available, might only be in SVN)
MongoLog::getModule — Gets the modules currently being logged
Opis
This function can be used to see which parts of the driver's functionality are being logged. Use the constants described in the MongoLog section with bitwise operators to check if specific modules are being logged.
<?php
if (MongoLog::getModule() & MongoLog::RS) {
echo "logging replica sets\n";
}
if (MongoLog::getModule() ^ MongoLog::NONE) {
echo "logging something\n";
}
if ((MongoLog::getModule() & MongoLog::IO) == 0) {
echo "not logging io\n";
}
?>
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the modules currently being logged.
MongoLog::setLevel
(No version information available, might only be in SVN)
MongoLog::setLevel — Sets logging level
Opis
$level
)This function can be used to set how verbose logging should be and the types of activities that should be logged. Use the constants described in the MongoLog section with bitwise operators to specify levels.
<?php
// first, turning on logging for a module
MongoLog::setModule(MongoLog::POOL);
// log messages of every level
MongoLog::setLevel(MongoLog::ALL);
// log warnings and info
MongoLog::setLevel(MongoLog::WARNING|MongoLog::INFO);
// log everything except fine activity
MongoLog::setLevel(MongoLog::ALL & (~MongoLog::FINE));
?>
Note that you must also call MongoLog::setModule() to choose what part of the driver to log.
Parametry
-
level -
The levels you would like to log.
MongoLog::setModule
(No version information available, might only be in SVN)
MongoLog::setModule — Sets driver functionality to log
Opis
$module
)This function can be used to set which parts of the driver's functionality should be logged. Use the constants described in the MongoLog section with bitwise operators to specify modules.
<?php
// first, turning up the logging level
MongoLog::setLevel(MongoLog::ALL);
// log replica set activity
MongoLog::setModule(MongoLog::RS);
// log replica sets and connection pooling
MongoLog::setModule(MongoLog::RS|MongoLog::ALL);
// log everything except IO activity
MongoLog::setModule(MongoLog::ALL & (~MongoLog::IO));
?>
Note that you must also call MongoLog::setLevel() to turn on logging.
Parametry
-
module -
The module(s) you would like to log.
Spis treści
- MongoLog::getLevel — Gets the log level
- MongoLog::getModule — Gets the modules currently being logged
- MongoLog::setLevel — Sets logging level
- MongoLog::setModule — Sets driver functionality to log
The MongoPool class
(No version information available, might only be in SVN)
Wstęp
In version 1.2.0 of the driver, built-in connection pooling was introduced. This class gives you some control and information about pooling.
Informacja:
The functions in this class were originally static members of Mongo. It is highly recommended that you use these functions in the future, as the static Mongo functions are considered deprecated.
MongoPool::getSize
(No version information available, might only be in SVN)
MongoPool::getSize — Get pool size for connection pools
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the current pool size.
Przykłady
Przykład #1 Changing pool size
This returns the default pool size, sets a new pool size, then prints the new pool size and the pool debugging information. Note that changing the pool size only affects new connection pools, it does not change old ones.
<?php
$connection = new Mongo("host1");
// pool size is -1
echo "pool size is: ".MongoPool::getSize()."\n";
echo "setting pool size to 200\n";
MongoPool::setSize(200);
// pool size is 200
echo "pool size is: ".MongoPool::getSize()."\n";
$conn2 = new Mongo("host2");
// remaining for host1 is -2
// remaining for host2 is 199
var_dump(Mongo::poolDebug());
?>
Zobacz też:
- MongoPool::setSize() - Set the size for future connection pools.
- MongoPool::info() - Returns information about all connection pools.
- The connection documentation.
MongoPool::info
(No version information available, might only be in SVN)
MongoPool::info — Returns information about all connection pools.
Opis
Returns an array of information about all connection pools.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Each connection pool has an identifier, which starts with the host. For each pool, this function shows the following fields:
-
in use -
The number of connections currently being used by Mongo instances.
-
in pool -
The number of connections currently in the pool (not being used).
-
remaining -
The number of connections that could be created by this pool. For example, suppose a pool had 5 connections remaining and 3 connections in the pool. We could create 8 new instances of Mongo before we exhausted this pool (assuming no instances of Mongo went out of scope, returning their connections to the pool).
A negative number means that this pool will spawn unlimited connections.
Before a pool is created, you can change the max number of connections by calling Mongo::setPoolSize(). Once a pool is showing up in the output of this function, its size cannot be changed.
-
total -
The total number of connections allowed for this pool. This should be greater than or equal to "in use" + "in pool" (or -1).
-
timeout -
The socket timeout for connections in this pool. This is how long connections in this pool will attempt to connect to a server before giving up.
-
waiting -
If you have capped the pool size, workers requesting connections from the pool may block until other workers return their connections. This field shows how many milliseconds workers have blocked for connections to be released. If this number keeps increasing, you may want to use MongoPool::setSize() to add more connections to your pool.
MongoPool::setSize
(No version information available, might only be in SVN)
MongoPool::setSize — Set the size for future connection pools.
Opis
$size
)Sets the max number of connections new pools will be able to create.
Parametry
-
size -
The max number of connections future pools will be able to create. Negative numbers mean that the pool will spawn an infinite number of connections.
Zwracane wartości
Returns the former value of pool size.
Przykłady
Przykład #1 Mongo::setPoolSize() example
If you set the pool size to n and then create n connections, attempting to create an n+1st connection will throw a MongoConnectionException.
<?php
// only allow one connection to a server
MongoPool::setSize(1);
// creates one connection to localhost:27017
$m1 = new Mongo();
// attempt to create a second connection to localhost:27017
// only one connection is allowed, so this will throw an exception
$m2 = new Mongo();
?>
Powyższy przykład wyświetli coś podobnego do:
Fatal error: Uncaught exception 'MongoConnectionException' with message 'no more connections in pool' in /path/to/php/script.php:10
Stack trace:
#0 /path/to/php/script.php(10): Mongo->__construct()
#1 {main}
thrown in /path/to/php/script.php on line 10
Zobacz też:
- MongoPool::getSize() - Get pool size for connection pools
- MongoPool::info() - Returns information about all connection pools.
- The connection documentation.
Spis treści
- MongoPool::getSize — Get pool size for connection pools
- MongoPool::info — Returns information about all connection pools.
- MongoPool::setSize — Set the size for future connection pools.
Functions
Spis treści
Mongo Funkcje
bson_decode
(PECL mongo >=1.0.1)
bson_decode — Deserializes a BSON object into a PHP array
Opis
$bson
)This function is very beta and entirely useless for 99% of users. It is only useful if you're doing something weird, such as writing your own driver on top of the PHP driver.
Parametry
-
bson -
The BSON to be deserialized.
Zwracane wartości
Returns the deserialized BSON object.
bson_encode
(PECL mongo >=1.0.1)
bson_encode — Serializes a PHP variable into a BSON string
Opis
This function is very beta and entirely useless for 99% of users. It is only useful if you're doing something weird, such as writing your own driver on top of the PHP driver.
Parametry
-
anything -
The variable to be serialized.
Zwracane wartości
Returns the serialized string.
Spis treści
- bson_decode — Deserializes a BSON object into a PHP array
- bson_encode — Serializes a PHP variable into a BSON string
Exceptions
Spis treści
- MongoException
- MongoCursorException
- MongoCursorTimeoutException
- MongoConnectionException
- MongoGridFSException
VMWare Oddities
If you are running VMWare on Windows and are using CIFS, pausing the VM will cause CIFS to go out of sync and cause weird errors on un-pausing it ("The Mongo object has not been correctly initialized by its constructor"). Permanently mounting the Windows shares will fix this and you'll be able to pause and unpause at will.
To permanently mount the Windows shares, run:
$ sudo update-rc.d -f umountnfs.sh remove $ sudo update-rc.d umountnfs.sh stop 15 0 6 .
See » the Ubuntu docs for the most up-to-date instructions.
The MongoException class
(No version information available, might only be in SVN)
Wstęp
Default Mongo exception.
This covers a bunch of different error conditions that may eventually be moved to more specific exceptions, but will always extend MongoException.
-
The MongoSomething object has not been correctly initialized by its constructor
Code: 0
Probably your Mongo object is not connected to a database server.
-
zero-length keys are not allowed, did you use $ with double quotes?
Code: 1
You tried to save "" as a key. You generally should not do this. "" can mess up subobject access and is used by MongoDB internally. However, if you really want, you can set mongo.allow_empty_keys to true in your php.ini file to override this sanity check. If you override this, it is highly recommended that you set error checking to strict to avoid string interpolation errors.
-
'.' not allowed in key: <key>
Code: 2
You attempted to write a key with '.' in it, which is prohibited.
-
insert too large: <size>, max: <max>
Code: 3
You're attempting to send too much data to the database at once: the database will only accept inserts up to a certain size (currently 16 MB).
-
no elements in doc
Code: 4
You're attempting to save a document with no fields.
-
size of BSON doc is <size> bytes, max <max>MB
Code: 5
You're attempting to save a document that is larger than MongoDB can save.
-
no documents given
Code: 6
You're attempting to batch insert an empty array of documents.
-
MongoCollection::group takes an array, object, or MongoCode key
Code: 7
Wrong type parameter send to MongoCollection::group().
-
field names must be strings
Code: 8
You should format field selectors as array("field1" => 1, "field2" => 1, ..., "fieldN" => 1).
-
invalid regex
Code: 8
The regex passed to MongoRegex is not of the correct form.
-
MongoDBRef::get: $ref field must be a string
Code: 10
-
MongoDBRef::get: $db field must be a string
Code: 11
-
non-utf8 string: <str>
Code: 12
This error occurs if you attempt to send a non-utf8 string to the database. All strings going into the database should be UTF8. See php.ini options for the transition option of quieting this exception.
-
mutex error: <err>
Code: 13
The driver uses mutexes for synchronizing requests and responses in multithreaded environments. This is a fairly serious error and may not have a stack trace. It's unusual and should be reported to maintainers with any system information and steps to reproduce that you can provide.
-
index name too long: <len>, max <max> characters
Code: 14
Indexes with names longer than 128 characters cannot be created. If you get this error, you should use MongoCollection::ensureIndex()'s "name" option to create a shorter name for your index.
Krótki opis klasy
The MongoCursorException class
(No version information available, might only be in SVN)
Wstęp
Caused by accessing a cursor incorrectly or a error receiving a reply. Note that this can be thrown by any database request that receives a reply, not just queries. Writes, commands, and any other operation that sends information to the database and waits for a response can throw a MongoCursorException. The only exception is new Mongo() (creating a new connection), which will only throw MongoConnectionExceptions.
This returns a specific error message to help diagnose the problem and a numeric error code associated with the cause of the exception.
For example, suppose you tried to insert two documents with the same _id:
<?php
try {
$collection->insert(array("_id" => 1), array("safe" => true));
$collection->insert(array("_id" => 1), array("safe" => true));
}
catch (MongoCursorException $e) {
echo "error message: ".$e->getMessage()."\n";
echo "error code: ".$e->getCode()."\n";
}
?>
error message: E11000 duplicate key error index: foo.bar.$_id_ dup key: { : 1 }
error code: 11000
The following is a list of common errors, codes, and causes. Exact errors are in italics, errors where the message can vary are described in obliques.
-
cannot modify cursor after beginning iteration
Code: 0
You are calling a method that sets up the query after executing the query. Reset the cursor and try again.
An example:
<?php
try {
$cursor = $collection->find();
var_dump($cursor->getNext());
// getNext() queried the database, it's too late to set a limit
$cursor->limit(1);
}
catch (MongoCursorException $e) {
echo "error message: ".$e->getMessage()."\n";
echo "error code: ".$e->getCode()."\n";
}
// this will work, though:
$cursor->getNext();
$cursor->reset();
$cursor->limit(1);
?> -
Get next batch send errors
Code: 1
Could not send the query to the database. Make sure the database is still up and the network is okay.
-
cursor not found
Code: 2
The driver was trying to fetch more results from the database, but the database did not have a record of the query. This usually means that the cursor timed out on the server side: after a few minutes of inactivity, the database will kill a cursor (see MongoCursor::immortal() for information on preventing this).
An example:
<?php
try {
$cursor = $collection->find();
$cursor->getNext();
// sleep for 15 minutes
sleep(60*15);
while ($cursor->hasNext()) {
$cursor->getNext();
}
}
catch (MongoCursorException $e) {
echo "error message: ".$e->getMessage()."\n";
echo "error code: ".$e->getCode()."\n";
}
?> -
cursor->buf.pos is null
Code: 3
This may indicate you are out of RAM or some other extraordinary circumstance.
-
couldn't get response header
Code: 4
A common error if the database or network goes down. This means that the driver couldn't get a response from the connection.
-
no db response
Code: 5
This may not even be an error, for example, the database command "shutdown" returns no response. However, if you were expecting a response, this means the database didn't give one.
-
bad response length: %d, did the db assert?
Code: 6
This means that the database said that its response was less than 0. This error probably indicates a network error or database corruption.
-
incomplete header
Code: 7
Highly unusual. Occurs if the database response started out correctly, but broke off in the middle. Probably indicates a network problem.
-
incomplete response
Code: 8
Highly unusual. Occurs if the database response started out correctly, but broke off in the middle. Probably indicates a network problem.
-
couldn't find a response
Code: 9
If the response was cached and now cannot be located.
-
error getting socket
Code: 10
The socket was closed or encountered an error. The driver should automatically reconnect (if possible) on the next operation.
-
couldn't find reply, please try again
Code: 11
The driver saves any database responses it cannot immediately match with a request. This exception occurs if the driver has already passed your request's response and cannot find your response in its cache.
-
error getting database response: errstr
WSA error getting database response: errstr
"errstr" is an io error reported directly from the C socket subsystem. On Windows, the error message is prefixed with "WSA".
-
Timeout error
Code: 13
If there was an error while waiting for a query to complete.
-
couldn't send query: <various>
Code: 14
C socket error on send.
-
max number of retries exhausted, couldn't send query
Code: 19
The driver will automatically retry "plain" queries (not commands) a couple of times if the first attempt failed for certain reasons. This is to cause fewer exceptions during replica set failover (although you will probably still have to deal with some) and gloss over transient network issues.
This can also be caused by the driver not being able to reconnect at all to the database (if, for example, the database is unreachable).
Version 1.2.2+.
Errors passed through by the database
Database errors should always trigger MongoCursorExceptions on queries. Error messages and codes are sent directly from the database and you should be able to see matching errors in the database log.
A few common database errors are listed below:
-
E11000 duplicate key error index: foo.bar.$X dup key: { /* ... */ }
Code: 11000
Database error for duplicate keys.
-
not master
Codes: 10107, 13435, and 10058
Not master errors, piped through by the database. Each of these will cause the driver to disconnect and attempt to find a new master. The actual error you get on failover may not be a "not master" error, depending on when the change in master occurs.
Krótki opis klasy
The MongoCursorTimeoutException class
(No version information available, might only be in SVN)
Wstęp
Caused by a query timing out. You can set the length of time to wait before this exception is thrown by calling MongoCursor::timeout() on the cursor or setting MongoCursor::$timeout. The static variable is useful for queries such as database commands and MongoCollection::findOne(), both of which implicitly use cursors.
Krótki opis klasy
The MongoConnectionException class
(No version information available, might only be in SVN)
Wstęp
Thrown when the driver fails to connect to the database.
There are a number of possible error messages to help you diagnose the connection problem. These are:
-
No server name given.
This error occurs if you pass in "" as the server name, probably because of an typo with string interpolation, e.g., "$servr" instead of "$server".
-
failed to get host [hostname] or port [portnum] from [server].
This indicated that the server string was malformed. "[hostname]" and "[portnum]" will be as much as the driver could dicipher of it.
-
Operation in progress
Connecting to the database timed out.
-
Transport endpoint is not connected
Generally means that the connection string isn't correct, the driver couldn't even find the database server.
-
couldn't determine master
Neither server in a paired connection appeared to be master.
-
couldn't get host info for [server]
This indicated that DNS could not resolve the server address you gave. This could easily be caused by a typo, for example, "server" instead of "$server".
-
Invalid Argument
This can be caused by attempting to connect to a machine that is up but that the database isn't actually running on. Make sure that you've started the database server before connecting.
-
Permission denied
This means that the socket could not be opened due to permissions issues. On Red Hat variants, this can be caused by a default setting that does not allow Apache to create network connections. You can override this setting by running:
then restarting Apache.$ /usr/sbin/setsebool -P httpd_can_network_connect 1
If the error message is not listed above, it is probably an error from the C socket, and you can search the web for its usual cause.
Krótki opis klasy
The MongoGridFSException class
(No version information available, might only be in SVN)
Wstęp
Thrown when there are errors reading or writing files to or from the database.
Krótki opis klasy
- Manual
- Core Classes
- Mongo — The Mongo class
- MongoDB — The MongoDB class
- MongoCollection — The MongoCollection class
- MongoCursor — The MongoCursor class
- Types
- MongoId — The MongoId class
- MongoCode — The MongoCode class
- MongoDate — The MongoDate class
- MongoRegex — The MongoRegex class
- MongoBinData — The MongoBinData class
- MongoInt32 — The MongoInt32 class
- MongoInt64 — The MongoInt64 class
- MongoDBRef — The MongoDBRef class
- MongoMinKey — The MongoMinKey class
- MongoMaxKey — The MongoMaxKey class
- MongoTimestamp — The MongoTimestamp class
- GridFS Classes
- MongoGridFS — The MongoGridFS class
- MongoGridFSFile — The MongoGridFSFile class
- MongoGridFSCursor — The MongoGridFSCursor class
- Miscellaneous
- Functions
- Exceptions
- MongoException — The MongoException class
- MongoCursorException — The MongoCursorException class
- MongoCursorTimeoutException — The MongoCursorTimeoutException class
- MongoConnectionException — The MongoConnectionException class
- MongoGridFSException — The MongoGridFSException class
mSQL
Wstęp
Te funkcje pozwalają uzyskać dostęp do serwerów baz danych mSQL. Więcej informacji na temat mSQL można znaleźć na stronie » http://www.hughes.com.au/.
Instalacja/Konfiguracja
Spis treści
Wymagania
Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.
Instalacja
Aby te funkcje były dostępne, musimy skompilować PHP z obsługą msql używając opcji --with-msql[=DIR] . DIR jest katalogiem instalacji mSQL, domyślnie /usr/local/msql3.
Informacja: Informacja dla użytkowników Windows
Aby poprawnie działało rozszerzenie, pliki DLL muszą znajdować się w miejscu wskazanym przez PATH systemu Windows. Aby uzyskać więcej informacji zobacz FAQ zatytułowane "Jak mam dodać mój katalog PHP do PATH w Windows". Chociaż skopiowanie plików DLL z folderu PHP do systemowego katalogu Windows także zadziała (ponieważ katalog systemowy jest domyślnie w PATH systemu), ale nie jest to wymagane. To rozszerzenie wymaga następujących plików znajdujących się w PATH: msql.dll
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Wartość domyślna | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| msql.allow_persistent | "1" | PHP_INI_ALL | |
| msql.max_persistent | "-1" | PHP_INI_ALL | |
| msql.max_links | "-1" | PHP_INI_ALL |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
Typy zasobów
Istnieją dwa typy zasobów używane w rozszerzeniu mSQL. Pierwszy z nich to identyfikator połączenia z bazą danych, natomiast drugi to zasób przechowujący wyniki zapytania.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
Przykłady
Spis treści
Podstawowe użycie
Ten prosty przykład pokazuje jak można połączyć się do bazy mSQL, wykonać zapytanie, wyświetlić wiersze z wynikami i zamknąć połączenie.
Przykład #1 Przykład użycia mSQL
<?php
/* Nawiązanie połączenia, wybór bazy danych */
$link = msql_connect('localhost')
or die('Nie można nawiązać połączenia : ' . msql_error());
msql_select_db('database', $link)
or die('Nie można wybrać bazy danych');
/* Wykonanie zapytania SQL */
$query = 'SELECT * FROM my_table';
$result = msql_query($query, $link) or die('Wykonanie zapytania nie powiodło się : ' . msql_error());
/* Wyświetlenie wyników w postaci tabeli HTML */
echo "<table>\n";
while ($row = msql_fetch_array($result, MSQL_ASSOC)) {
echo "\t<tr>\n";
foreach ($row as $col_value) {
echo "\t\t<td>$col_value</td>\n";
}
echo "\t</tr>\n";
}
echo "</table>\n";
/* Zwolnienie pamięci zajmowanej przez wynik */
msql_free_result($result);
/* Zamknięcie połączenia */
msql_close($link);
?>
Funkcje mSQL
msql_affected_rows
(PHP 4, PHP 5)
msql_affected_rows — Returns number of affected rows
Opis
$result
)
Returns number of affected rows by the last SELECT, UPDATE or DELETE
query associated with result.
Parametry
-
wynik -
Wynik w postaci zmiennej typu resource, który jest przetwarzany. Wynik pochodzi z wywołania funkcji msql_query().
Zwracane wartości
Returns the number of affected rows on success, or FALSE on error.
msql_close
(PHP 4, PHP 5)
msql_close — Zamyka połączenie z serwerem mSQL
Opis
$identyfikator_połączenia
] )msql_close() zamyka nietrwałe połączenie do serwera mSQL skojarzone z określonym identyfikatorem połączenia.
Używanie msql_close() zazwyczaj nie jest konieczne, jako że nietrwałe połączenia są automatycznie zamykane po zakończeniu wykonywania skryptu. Patrz także: zwalnianie zasobów.
Parametry
-
identyfikator_połączenia -
Połączenie mSQL. Jeśli nie zostanie podany, używane jest ostatnie połączenie otwarte przez msql_connect(). Jeśli nie zostanie ono znalezione, funkcja spróbuje nawiązać połączenie tak, jakby wywołana została funkcja msql_connect(), i je użyje.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- msql_connect() - Otwiera połączenie z serwerem mSQL
- msql_pconnect() - Otwiera trwałe połączenie do serwera mSQL
msql_connect
(PHP 4, PHP 5)
msql_connect — Otwiera połączenie z serwerem mSQL
Opis
$nazwa_hosta
] )msql_connect() nawiązuje połączenie z serwerem mSQL.
W przypadku kolejnego wywołania funkcji msql_connect() z takimi samymi argumentami, nie jest otwierane nowe połączenie, jednak w to miejsce powinien zostać zwrócony identyfikator już otwartego połączenia.
Połączenie z serwerem powinno zostać zamknięte wkrótce po tym, gdy wykonywanie skryptu PHP się zakończy, o ile nie zostanie zamknięte wcześniej przez jawne wywołanie funkcji msql_close().
Parametry
-
nazwa_hosta -
Parametr nazwa_hosta może mieć dołączony numer portu np. hostname,port.
Jeśli go nie określono, to połączenie jest nawiązywane za pomocą gniazd domenowych Uniksa, które są znacznie bardziej wydajne niż połączenia TCP z hostem lokalnym.
Informacja:
Ta funkcja pozwala na stosowanie dwukropka (:) jako separatora hosta/portu, ale bardziej preferowaną metodą jest używanie przecinka (,).
Zwracane wartości
Zwraca identyfikator połączenia do mSQL w przypadku sukcesu
lub FALSE w przypadku błędu.
Zobacz też:
- msql_pconnect() - Otwiera trwałe połączenie do serwera mSQL
- msql_close() - Zamyka połączenie z serwerem mSQL
msql_create_db
(PHP 4, PHP 5)
msql_create_db — Tworzy nową bazę danych na serwerze mSQL
Opis
$nazwa_bazy_danych
[, resource $identyfikator_połączenia
] )msql_create_db() próbuje utworzyć nową bazę danych na serwerze mSQL.
Parametry
-
nazwa_bazy_danych -
Nazwa nowej bazy danych mSQL.
-
identyfikator_połączenia -
Połączenie mSQL. Jeśli nie zostanie podany, używane jest ostatnie połączenie otwarte przez msql_connect(). Jeśli nie zostanie ono znalezione, funkcja spróbuje nawiązać połączenie tak, jakby wywołana została funkcja msql_connect(), i je użyje.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Opis
Ta funkcja jest aliasem dla: msql_create_db().
msql_data_seek
(PHP 4, PHP 5)
msql_data_seek — Move internal row pointer
Opis
$result
, int $row_number
)msql_data_seek() moves the internal row pointer of the mSQL result associated with the specified query identifier to point to the specified row number. The next call to msql_fetch_row() would return that row.
Parametry
-
wynik -
Wynik w postaci zmiennej typu resource, który jest przetwarzany. Wynik pochodzi z wywołania funkcji msql_query().
-
row_number -
The seeked row number.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- msql_fetch_array() - Fetch row as array
- msql_fetch_object() - Fetch row as object
- msql_fetch_row() - Get row as enumerated array
- msql_result() - Get result data
msql_db_query
(PHP 4, PHP 5)
msql_db_query — Send mSQL query
Opis
$database
, string $query
[, resource $link_identifier
] )msql_db_query() selects a database and executes a query on it.
Parametry
-
database -
The name of the mSQL database.
-
query -
The SQL query.
-
identyfikator_połączenia -
Połączenie mSQL. Jeśli nie zostanie podany, używane jest ostatnie połączenie otwarte przez msql_connect(). Jeśli nie zostanie ono znalezione, funkcja spróbuje nawiązać połączenie tak, jakby wywołana została funkcja msql_connect(), i je użyje.
Zwracane wartości
Returns a positive mSQL query identifier to the query result, or FALSE
on error.
Opis
Ta funkcja jest aliasem dla: msql_result().
msql_drop_db
(PHP 4, PHP 5)
msql_drop_db — Usuwa bazę danych z serwera mSQL
Opis
$nazwa_bazy_danych
[, resource $identyfikator_połączenia
] )msql_drop_db() próbuje usunąć bazę danych z serwera mSQL.
Parametry
-
nazwa_bazy_danych -
Nazwa bazy danych.
-
identyfikator_połączenia -
Połączenie mSQL. Jeśli nie zostanie podany, używane jest ostatnie połączenie otwarte przez msql_connect(). Jeśli nie zostanie ono znalezione, funkcja spróbuje nawiązać połączenie tak, jakby wywołana została funkcja msql_connect(), i je użyje.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
msql_error
(PHP 4, PHP 5)
msql_error — Returns error message of last msql call
Opis
msql_error() returns the last issued error by the mSQL server. Note that only the last error message is accessible with msql_error().
Zwracane wartości
The last error message or an empty string if no error was issued.
msql_fetch_array
(PHP 4, PHP 5)
msql_fetch_array — Fetch row as array
Opis
$result
[, int $result_type
] )msql_fetch_array() is an extended version of msql_fetch_row(). In addition to storing the data in the numeric indices of the result array, it also stores the data in associative indices, using the field names as keys.
An important thing to note is that using msql_fetch_array() is NOT significantly slower than using msql_fetch_row(), while it provides a significant added value.
Parametry
-
wynik -
Wynik w postaci zmiennej typu resource, który jest przetwarzany. Wynik pochodzi z wywołania funkcji msql_query().
-
result_type -
A constant that can take the following values:
MSQL_ASSOC,MSQL_NUM, andMSQL_BOTHwithMSQL_BOTHbeing the default.
Zwracane wartości
Returns an array that corresponds to the fetched row, or FALSE if
there are no more rows.
Przykłady
Przykład #1 msql_fetch_array() example
<?php
$con = msql_connect();
if (!$con) {
die('Server connection problem: ' . msql_error());
}
if (!msql_select_db('test', $con)) {
die('Database connection problem: ' . msql_error());
}
$result = msql_query('SELECT id, name FROM people', $con);
if (!$result) {
die('Query execution problem: ' . msql_error());
}
while ($row = msql_fetch_array($result, MSQL_ASSOC)) {
echo $row['id'] . ': ' . $row['name'] . "\n";
}
msql_free_result($result);
?>
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.3.11 and 5.0.4 |
A bug was fixed when retrieving data from columns containing NULL
values. Such columns were not placed into the resulting array.
|
Zobacz też:
- msql_fetch_row() - Get row as enumerated array
- msql_fetch_object() - Fetch row as object
- msql_data_seek() - Move internal row pointer
- msql_result() - Get result data
msql_fetch_field
(PHP 4, PHP 5)
msql_fetch_field — Get field information
Opis
$result
[, int $field_offset = 0
] )msql_fetch_field() can be used in order to obtain information about fields in a certain query result.
Parametry
-
wynik -
Wynik w postaci zmiennej typu resource, który jest przetwarzany. Wynik pochodzi z wywołania funkcji msql_query().
-
field_offset -
The field offset. If not specified, the next field that wasn't yet retrieved by msql_fetch_field() is retrieved.
Zwracane wartości
Returns an object containing field information. The properties of the object are:
-
name - column name
-
table - name of the table the column belongs to
-
not_null - 1 if the column cannot be
NULL -
unique - 1 if the column is a unique key
- type - the type of the column
msql_fetch_object
(PHP 4, PHP 5)
msql_fetch_object — Fetch row as object
Opis
$result
)msql_fetch_object() is similar to msql_fetch_array(), with one difference - an object is returned, instead of an array. Indirectly, that means that you can only access the data by the field names, and not by their offsets (numbers are illegal property names).
Speed-wise, the function is identical to msql_fetch_array(), and almost as quick as msql_fetch_row() (the difference is insignificant).
Parametry
-
wynik -
Wynik w postaci zmiennej typu resource, który jest przetwarzany. Wynik pochodzi z wywołania funkcji msql_query().
Zwracane wartości
Returns an object with properties that correspond to the fetched
row, or FALSE if there are no more rows.
Przykłady
Przykład #1 msql_fetch_object() example
<?php
$con = msql_connect();
if (!$con) {
die('Server connection problem: ' . msql_error());
}
if (!msql_select_db('test', $con)) {
die('Database connection problem: ' . msql_error());
}
$result = msql_query('SELECT id, name FROM people', $con);
if (!$result) {
die('Query execution problem: ' . msql_error());
}
while ($row = msql_fetch_object($result, MSQL_ASSOC)) {
echo $row->id . ': ' . $row->name . "\n";
}
msql_free_result($result);
?>
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.3.11 and 5.0.4 |
A bug was fixed when retrieving data from columns containing NULL
values. Such columns were not placed into the resulting array.
|
Zobacz też:
- msql_fetch_array() - Fetch row as array
- msql_fetch_row() - Get row as enumerated array
- msql_data_seek() - Move internal row pointer
- msql_result() - Get result data
msql_fetch_row
(PHP 4, PHP 5)
msql_fetch_row — Get row as enumerated array
Opis
$result
)msql_fetch_row() fetches one row of data from the result associated with the specified query identifier. The row is returned as an array. Each result column is stored in an array offset, starting at offset 0.
Subsequent call to msql_fetch_row() would
return the next row in the result set, or FALSE if there are no
more rows.
Parametry
-
wynik -
Wynik w postaci zmiennej typu resource, który jest przetwarzany. Wynik pochodzi z wywołania funkcji msql_query().
Zwracane wartości
Returns an array that corresponds to the fetched row, or FALSE if
there are no more rows.
Przykłady
Przykład #1 msql_fetch_row() example
<?php
$con = msql_connect();
if (!$con) {
die('Server connection problem: ' . msql_error());
}
if (!msql_select_db('test', $con)) {
die('Database connection problem: ' . msql_error());
}
$result = msql_query('SELECT id, name FROM people', $con);
if (!$result) {
die('Query execution problem: ' . msql_error());
}
while ($row = msql_fetch_row($result)) {
echo $row[0] . ': ' . $row[1] . "\n";
}
msql_free_result($result);
?>
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.3.11 and 5.0.4 |
A bug was fixed when retrieving data from columns containing NULL
values. Such columns were not placed into the resulting array.
|
Zobacz też:
- msql_fetch_array() - Fetch row as array
- msql_fetch_object() - Fetch row as object
- msql_data_seek() - Move internal row pointer
- msql_result() - Get result data
msql_field_flags
(PHP 4, PHP 5)
msql_field_flags — Get field flags
Opis
$result
, int $field_offset
)msql_field_flags() returns the field flags of the specified field.
Parametry
-
wynik -
Wynik w postaci zmiennej typu resource, który jest przetwarzany. Wynik pochodzi z wywołania funkcji msql_query().
-
przesunięcie_pola -
Liczbowe przesunięcie pola.
przesunięcie_polazaczyna się od wartości 1.
Zwracane wartości
Returns a string containing the field flags of the specified key. This can be: primary key not null, not null, primary key, unique not null or unique.
msql_field_len
(PHP 4, PHP 5)
msql_field_len — Get field length
Opis
$result
, int $field_offset
)msql_field_len() returns the length of the specified field.
Parametry
-
wynik -
Wynik w postaci zmiennej typu resource, który jest przetwarzany. Wynik pochodzi z wywołania funkcji msql_query().
-
przesunięcie_pola -
Liczbowe przesunięcie pola.
przesunięcie_polazaczyna się od wartości 1.
Zwracane wartości
Returns the length of the specified field or FALSE on error.
msql_field_name
(PHP 4, PHP 5)
msql_field_name — Get the name of the specified field in a result
Opis
$result
, int $field_offset
)msql_field_name() gets the name of the specified field index.
Parametry
-
wynik -
Wynik w postaci zmiennej typu resource, który jest przetwarzany. Wynik pochodzi z wywołania funkcji msql_query().
-
przesunięcie_pola -
Liczbowe przesunięcie pola.
przesunięcie_polazaczyna się od wartości 1.
Zwracane wartości
The name of the field lub FALSE w przypadku niepowodzenia.
msql_field_seek
(PHP 4, PHP 5)
msql_field_seek — Set field offset
Opis
$result
, int $field_offset
)Seeks to the specified field offset. If the next call to msql_fetch_field() won't include a field offset, this field would be returned.
Parametry
-
wynik -
Wynik w postaci zmiennej typu resource, który jest przetwarzany. Wynik pochodzi z wywołania funkcji msql_query().
-
przesunięcie_pola -
Liczbowe przesunięcie pola.
przesunięcie_polazaczyna się od wartości 1.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
msql_field_table
(PHP 4, PHP 5)
msql_field_table — Get table name for field
Opis
$result
, int $field_offset
)Returns the name of the table that the specified field is in.
Parametry
-
wynik -
Wynik w postaci zmiennej typu resource, który jest przetwarzany. Wynik pochodzi z wywołania funkcji msql_query().
-
przesunięcie_pola -
Liczbowe przesunięcie pola.
przesunięcie_polazaczyna się od wartości 1.
Zwracane wartości
The name of the table on success lub FALSE w przypadku niepowodzenia.
msql_field_type
(PHP 4, PHP 5)
msql_field_type — Get field type
Opis
$result
, int $field_offset
)msql_field_type() gets the type of the specified field index.
Parametry
-
wynik -
Wynik w postaci zmiennej typu resource, który jest przetwarzany. Wynik pochodzi z wywołania funkcji msql_query().
-
przesunięcie_pola -
Liczbowe przesunięcie pola.
przesunięcie_polazaczyna się od wartości 1.
Zwracane wartości
The type of the field. One of int,
char, real, ident,
null or unknown. This functions will
return FALSE on failure.
Opis
Ta funkcja jest aliasem dla msql_field_flags().
Opis
Ta funkcja jest aliasem dla msql_field_len().
Opis
Ta funkcja jest aliasem dla msql_field_name().
Opis
Ta funkcja jest aliasem dla msql_field_table().
Opis
Ta funkcja jest aliasem dla msql_field_type().
msql_free_result
(PHP 4, PHP 5)
msql_free_result — Free result memory
Opis
$result
)
msql_free_result() frees the memory associated
with query_identifier. When PHP completes a
request, this memory is freed automatically, so you only need to
call this function when you want to make sure you don't use too
much memory while the script is running.
Parametry
-
wynik -
Wynik w postaci zmiennej typu resource, który jest przetwarzany. Wynik pochodzi z wywołania funkcji msql_query().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
msql_list_dbs
(PHP 4, PHP 5)
msql_list_dbs — List mSQL databases on server
Opis
$link_identifier
] )
msql_list_tables() lists the databases available on the
specified link_identifier.
Parametry
-
identyfikator_połączenia -
Połączenie mSQL. Jeśli nie zostanie podany, używane jest ostatnie połączenie otwarte przez msql_connect(). Jeśli nie zostanie ono znalezione, funkcja spróbuje nawiązać połączenie tak, jakby wywołana została funkcja msql_connect(), i je użyje.
Zwracane wartości
Returns a result set which may be traversed with any function that fetches
result sets, such as msql_fetch_array(). On failure,
this function will return FALSE.
Zobacz też:
- msql_list_tables() - List tables in an mSQL database
- msql_list_fields() - List result fields
msql_list_fields
(PHP 4, PHP 5)
msql_list_fields — List result fields
Opis
$database
, string $tablename
[, resource $link_identifier
] )msql_list_fields() returns information about the given table.
Parametry
-
database -
The name of the database.
-
tablename -
The name of the table.
-
identyfikator_połączenia -
Połączenie mSQL. Jeśli nie zostanie podany, używane jest ostatnie połączenie otwarte przez msql_connect(). Jeśli nie zostanie ono znalezione, funkcja spróbuje nawiązać połączenie tak, jakby wywołana została funkcja msql_connect(), i je użyje.
Zwracane wartości
Returns a result set which may be traversed with any function that fetches
result sets, such as msql_fetch_array(). On failure,
this function will return FALSE.
Zobacz też:
- msql_list_tables() - List tables in an mSQL database
- msql_list_dbs() - List mSQL databases on server
msql_list_tables
(PHP 4, PHP 5)
msql_list_tables — List tables in an mSQL database
Opis
$database
[, resource $link_identifier
] )
msql_list_tables() lists the tables on the specified
database.
Parametry
-
database -
The name of the database.
-
identyfikator_połączenia -
Połączenie mSQL. Jeśli nie zostanie podany, używane jest ostatnie połączenie otwarte przez msql_connect(). Jeśli nie zostanie ono znalezione, funkcja spróbuje nawiązać połączenie tak, jakby wywołana została funkcja msql_connect(), i je użyje.
Zwracane wartości
Returns a result set which may be traversed with any function that fetches
result sets, such as msql_fetch_array(). On failure,
this function will return FALSE.
msql_num_fields
(PHP 4, PHP 5)
msql_num_fields — Get number of fields in result
Opis
$result
)msql_num_fields() returns the number of fields in a result set.
Parametry
-
wynik -
Wynik w postaci zmiennej typu resource, który jest przetwarzany. Wynik pochodzi z wywołania funkcji msql_query().
Zwracane wartości
Returns the number of fields in the result set.
Zobacz też:
- msql_query() - Send mSQL query
- msql_fetch_field() - Get field information
- msql_num_rows() - Get number of rows in result
msql_num_rows
(PHP 4, PHP 5)
msql_num_rows — Get number of rows in result
Opis
$query_identifier
)msql_num_rows() returns the number of rows in a result set.
Parametry
-
wynik -
Wynik w postaci zmiennej typu resource, który jest przetwarzany. Wynik pochodzi z wywołania funkcji msql_query().
Zwracane wartości
Returns the number of rows in the result set.
Opis
Ta funkcja jest aliasem dla msql_num_fields().
Opis
Ta funkcja jest aliasem dla msql_num_rows().
msql_pconnect
(PHP 4, PHP 5)
msql_pconnect — Otwiera trwałe połączenie do serwera mSQL
Opis
$nazwa_hosta
] )msql_pconnect() zachowuje się prawie jak msql_connect() z dwoma zasadniczymi różnicami:
Pierwsza, podczas łączenia funkcja najpierw spróbuje znaleźć połączenie (trwałe), już otwarte dla tego samego hosta. Jeżeli je znajdzie, to jego identyfikator zostanie zwrócony zamiast otwierania nowego połączenia.
Druga, połączenie do serwera mSQL nie zostanie zamknięte po zakończeniu wykonywania skryptu. Zamiast tego połączenie pozostanie otwarte do późniejszego użycia (msql_close() nie zamyka połączeń nawiązanych za pomocą tej funkcji).
Parametry
-
nazwa_hosta -
Parametr nazwa_hosta może mieć dołączony numer portu np. nazwa_hosta,port.
Jeśli go nie określono, to połączenie jest nawiązywane za pomocą gniazd domenowych Uniksa, które są znacznie bardziej wydajne niż połączenia TCP z hostem lokalnym.
Informacja: Ta funkcja pozwala na stosowanie dwukropka (:) jako separatora hosta/portu, ale bardziej preferowaną metodą jest używanie przecinka (,).
Zwracane wartości
Zwraca identyfikator połączenia do mSQL w przypadku sukcesu
lub FALSE w przypadku błędu.
Zobacz też:
- msql_connect() - Otwiera połączenie z serwerem mSQL
- msql_close() - Zamyka połączenie z serwerem mSQL
msql_query
(PHP 4, PHP 5)
msql_query — Send mSQL query
Opis
$query
[, resource $link_identifier
] )msql_query() sends a query to the currently active database on the server that's associated with the specified link identifier.
Parametry
-
query -
The SQL query.
-
identyfikator_połączenia -
Połączenie mSQL. Jeśli nie zostanie podany, używane jest ostatnie połączenie otwarte przez msql_connect(). Jeśli nie zostanie ono znalezione, funkcja spróbuje nawiązać połączenie tak, jakby wywołana została funkcja msql_connect(), i je użyje.
Zwracane wartości
Returns a positive mSQL query identifier on success, or FALSE on
error.
Przykłady
Przykład #1 msql_query() example
<?php
$link = msql_connect("dbserver")
or die("unable to connect to msql server: " . msql_error());
msql_select_db("db", $link)
or die("unable to select database 'db': " . msql_error());
$result = msql_query("SELECT * FROM table WHERE id=1", $link);
if (!$result) {
die("query failed: " . msql_error());
}
while ($row = msql_fetch_array($result)) {
echo $row["id"];
}
?>
Zobacz też:
- msql_db_query() - Send mSQL query
- msql_select_db() - Select mSQL database
- msql_connect() - Otwiera połączenie z serwerem mSQL
Opis
Ta funkcja jest aliasem dla sql_regcase().
msql_result
(PHP 4, PHP 5)
msql_result — Get result data
Opis
msql_result() returns the contents of one cell from a mSQL result set.
When working on large result sets, you should consider using one of the functions that fetch an entire row (specified below). As these functions return the contents of multiple cells in one function call, they are often much quicker than msql_result().
Recommended high-performance alternatives: msql_fetch_row(), msql_fetch_array(), and msql_fetch_object().
Parametry
-
wynik -
Wynik w postaci zmiennej typu resource, który jest przetwarzany. Wynik pochodzi z wywołania funkcji msql_query().
-
row -
The row offset.
-
field -
Can be the field's offset, or the field's name, or the field's table dot field's name (tablename.fieldname.). If the column name has been aliased ('select foo as bar from ...'), use the alias instead of the column name.
Informacja:
Specifying a numeric field offset is much quicker than specifying a fieldname or tablename.fieldname.
Zwracane wartości
Returns the contents of the cell at the row and offset in the specified mSQL result set.
msql_select_db
(PHP 4, PHP 5)
msql_select_db — Select mSQL database
Opis
$database_name
[, resource $link_identifier
] )
msql_select_db() sets the current active database on
the server that's associated with the specified
link_identifier.
Subsequent calls to msql_query() will be made on the active database.
Parametry
-
database_name -
The database name.
-
identyfikator_połączenia -
Połączenie mSQL. Jeśli nie zostanie podany, używane jest ostatnie połączenie otwarte przez msql_connect(). Jeśli nie zostanie ono znalezione, funkcja spróbuje nawiązać połączenie tak, jakby wywołana została funkcja msql_connect(), i je użyje.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- msql_connect() - Otwiera połączenie z serwerem mSQL
- msql_pconnect() - Otwiera trwałe połączenie do serwera mSQL
- msql_query() - Send mSQL query
Opis
Ta funkcja jest aliasem dla msql_result().
Opis
Ta funkcja jest aliasem dla msql_db_query().
Spis treści
- msql_affected_rows — Returns number of affected rows
- msql_close — Zamyka połączenie z serwerem mSQL
- msql_connect — Otwiera połączenie z serwerem mSQL
- msql_create_db — Tworzy nową bazę danych na serwerze mSQL
- msql_createdb — Alias dla msql_create_db
- msql_data_seek — Move internal row pointer
- msql_db_query — Send mSQL query
- msql_dbname — Alias dla msql_result
- msql_drop_db — Usuwa bazę danych z serwera mSQL
- msql_error — Returns error message of last msql call
- msql_fetch_array — Fetch row as array
- msql_fetch_field — Get field information
- msql_fetch_object — Fetch row as object
- msql_fetch_row — Get row as enumerated array
- msql_field_flags — Get field flags
- msql_field_len — Get field length
- msql_field_name — Get the name of the specified field in a result
- msql_field_seek — Set field offset
- msql_field_table — Get table name for field
- msql_field_type — Get field type
- msql_fieldflags — Alias dla msql_field_flags
- msql_fieldlen — Alias dla msql_field_len
- msql_fieldname — Alias dla msql_field_name
- msql_fieldtable — Alias dla msql_field_table
- msql_fieldtype — Alias dla msql_field_type
- msql_free_result — Free result memory
- msql_list_dbs — List mSQL databases on server
- msql_list_fields — List result fields
- msql_list_tables — List tables in an mSQL database
- msql_num_fields — Get number of fields in result
- msql_num_rows — Get number of rows in result
- msql_numfields — Alias dla msql_num_fields
- msql_numrows — Alias dla msql_num_rows
- msql_pconnect — Otwiera trwałe połączenie do serwera mSQL
- msql_query — Send mSQL query
- msql_regcase — Alias dla sql_regcase
- msql_result — Get result data
- msql_select_db — Select mSQL database
- msql_tablename — Alias dla msql_result
- msql — Alias dla msql_db_query
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Przykłady
- Funkcje mSQL
- msql_affected_rows — Returns number of affected rows
- msql_close — Zamyka połączenie z serwerem mSQL
- msql_connect — Otwiera połączenie z serwerem mSQL
- msql_create_db — Tworzy nową bazę danych na serwerze mSQL
- msql_createdb — Alias dla msql_create_db
- msql_data_seek — Move internal row pointer
- msql_db_query — Send mSQL query
- msql_dbname — Alias dla msql_result
- msql_drop_db — Usuwa bazę danych z serwera mSQL
- msql_error — Returns error message of last msql call
- msql_fetch_array — Fetch row as array
- msql_fetch_field — Get field information
- msql_fetch_object — Fetch row as object
- msql_fetch_row — Get row as enumerated array
- msql_field_flags — Get field flags
- msql_field_len — Get field length
- msql_field_name — Get the name of the specified field in a result
- msql_field_seek — Set field offset
- msql_field_table — Get table name for field
- msql_field_type — Get field type
- msql_fieldflags — Alias dla msql_field_flags
- msql_fieldlen — Alias dla msql_field_len
- msql_fieldname — Alias dla msql_field_name
- msql_fieldtable — Alias dla msql_field_table
- msql_fieldtype — Alias dla msql_field_type
- msql_free_result — Free result memory
- msql_list_dbs — List mSQL databases on server
- msql_list_fields — List result fields
- msql_list_tables — List tables in an mSQL database
- msql_num_fields — Get number of fields in result
- msql_num_rows — Get number of rows in result
- msql_numfields — Alias dla msql_num_fields
- msql_numrows — Alias dla msql_num_rows
- msql_pconnect — Otwiera trwałe połączenie do serwera mSQL
- msql_query — Send mSQL query
- msql_regcase — Alias dla sql_regcase
- msql_result — Get result data
- msql_select_db — Select mSQL database
- msql_tablename — Alias dla msql_result
- msql — Alias dla msql_db_query
Microsoft SQL Server
Wstęp
Te funkcje umożliwiają dostęp do serwerów baz danych MS SQL Server.
To rozszerzenie nie jest już dostępne na Windows od PHP 5.3 i nowszych wersji.
SQLSRV - opcjonalny sterownik do MS SQL jest dostępny od Microsoft: » http://msdn.microsoft.com/en-us/sqlserver/ff657782.aspx.
Instalacja/Konfiguracja
Spis treści
Wymagania
Wymagania dla platform Win32.
Rozszerzenie wymaga aby w systemie, w którym jest zainstalowany PHP, znajdowały się narzędzia MS SQL Client Tools. Client Tools można zainstalować z płyty instalacyjnej serwera MS SQL Server lub skopiować plik ntwdblib.dll z katalogu \winnt\system32 systemu, na którym jest uruchomiony serwer do katalogu \winnt\system32 systemu, na którym znajduje się PHP. Skopiowanie ntwdblib.dll powinno umożliwić tylko dostęp poprzez potoki nazwane. Pełna konfiguracja klienta wymaga instalacji wszystkich narzędzi Client Tools.
To rozszerzenie nie jest już dostępne na Windows od PHP 5.3 i nowszych wersji.
SqlSrv - opcjonalny sterownik do MS SQL jest dostępny na witrynie firmy Microsoft: » http://msdn.microsoft.com/en-us/sqlserver/ff657782.aspx.
Wymagania dla platform Unix/Linux.
Aby używać rozszerzenia MSSQL w Unix/Linux, należy najpierw skompilować i zainstalować bibliotekę FreeTDS. Kod źródłowy i instrukcje instalacji są dostępne na witrynie FreeTDS: » http://www.freetds.org/
Informacja:
W Windows jest używana DBLIB Microsoftu. Funkcje, które zwracają nazwy kolumn używają wewnętrznej funkcji DBLIB dbcolname(). DBLIB została zaprojektowana dla SQL Server 6.x gdzie maksymalna długość identyfikatora wynosiła 30. Z tego powodu, maksymalna długość zwracanej nazwy kolumny wynosi 30 znaków. Na platformach gdzie używa się FreeTDS (Linux), nie ma takiego problemu.
Informacja:
W Windows z zainstalowanym serwerem MSSQL 2005 lub nowszym należy skopiować bibliotekę ntwdblib.dll do katalogu w którym jest zainstalowany PHP i w razie potrzeby nadpisać znajdującą się tam bibliotekę. Należy to zrobić, gdyż wersja biblioteki dystrybuowana z PHP jest przestarzała. Innym sposobem nawiązania połączenia z MSSQL są rozszerzenia: » http://msdn.microsoft.com/en-us/sqlserver/ff657782.aspx, ODBC, PDO_DBLIB lub PDO_ODBC.
Instalacja
Rozszerzenie MSSQL włącza się poprzez dodanie linii extension=php_mssql.dll w php.ini.
Aby te funkcje działały, należy skompilować PHP z opcją --with-mssql[=DIR] , gdzie DIR jest ścieżką instalacji FreeTDS. Natomiast FreeTDS powinien być skompilowany z opcją --enable-msdblib .
Funkcje MS SQL są aliasami funkcji Sybase jeśli PHP został skompilowany z rozszerzeniem Sybase i bez rozszerzenia MS SQL.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Wartość domyślna | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| mssql.allow_persistent | "1" | PHP_INI_SYSTEM | |
| mssql.max_persistent | "-1" | PHP_INI_SYSTEM | |
| mssql.max_links | "-1" | PHP_INI_SYSTEM | |
| mssql.min_error_severity | "10" | PHP_INI_ALL | |
| mssql.min_message_severity | "10" | PHP_INI_ALL | |
| mssql.compatability_mode | "0" | PHP_INI_ALL | |
| mssql.connect_timeout | "5" | PHP_INI_ALL | |
| mssql.timeout | "60" | PHP_INI_ALL | Dostępna od PHP 4.1.0. |
| mssql.textsize | "-1" | PHP_INI_ALL | |
| mssql.textlimit | "-1" | PHP_INI_ALL | |
| mssql.batchsize | "0" | PHP_INI_ALL | Dostępna od PHP 4.0.4. |
| mssql.datetimeconvert | "1" | PHP_INI_ALL | Dostępna od PHP 4.2.0. |
| mssql.secure_connection | "0" | PHP_INI_SYSTEM | Dostępna od PHP 4.3.0. |
| mssql.max_procs | "-1" | PHP_INI_ALL | Dostępna od PHP 4.3.0. |
| mssql.charset | "" | PHP_INI_ALL | Dostępna od PHP 5.1.2, gdy zostanie zbudowany z obsługą FreeTDS 7.0 lub nowszej. |
Typy zasobów
identyfikator połączenia mssql
Identyfikator połączenia zwrócony przez mssql_connect() lub mssql_pconnect().
zbiór wynikowy mssql
Zbiór wynikowy zwrócony przez mssql_query() dla zapytań SELECT.
identyfikator instrukcji mssql
Identyfikator instrukcji zwrócony przez mssql_init().
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
-
MSSQL_ASSOC(integer) - Zwraca tablicę asocjacyjną. Używane w funkcji mssql_fetch_array() jako parametr dla result_type.
-
MSSQL_NUM(integer) - Zwraca tablicę numeryczną. Używane w funkcji mssql_fetch_array() jako parametr result_type.
-
MSSQL_BOTH(integer) - Zwraca tablicę z kluczami numerycznymi i kluczami jako nazwy pól. Jest to wartość domyślna w funkcji mssql_fetch_array() jako parametr result_type.
-
SQLTEXT(integer) - Wskazuje typ 'TEXT' w MSSQL używany przez mssql_bind() jako parametr type.
-
SQLVARCHAR(integer) - Wskazuje typ 'VARCHAR' w MSSQL używany przez mssql_bind() jako parametr type.
-
SQLCHAR(integer) - Wskazuje typ 'CHAR' w MSSQL używany przez mssql_bind() jako parametr type.
-
SQLINT1(integer) - Reprezentuje jeden bajt z zakresem od -128 do 127.
-
SQLINT2(integer) - Reprezentuje dwa bajty z zakresem od -32768 do 32767.
-
SQLINT4(integer) - Reprezentuje cztery bajty z zakresem od -2147483648 do 2147483647.
-
SQLBIT(integer) - Wskazuje typ 'BIT' w MSSQL używany przez mssql_bind() jako parametr type.
-
SQLFLT4(integer) - Reprezentuje czterobajtową liczbę typu float.
-
SQLFLT8(integer) - Reprezentuje ośmiobajtową liczbę typu float.
Funkcje Mssql
mssql_bind
(PHP 4 >= 4.0.7, PHP 5, PECL odbtp >= 1.1.1)
mssql_bind — Adds a parameter to a stored procedure or a remote stored procedure
Opis
$stmt
, string $param_name
, mixed &$var
, int $type
[, bool $is_output = false
[, bool $is_null = false
[, int $maxlen = -1
]]] )Binds a parameter to a stored procedure or a remote stored procedure.
Parametry
-
stmt -
Statement resource, obtained with mssql_init().
-
param_name -
The parameter name, as a string.
Informacja:
You have to include the @ character, like in the T-SQL syntax. See the explanation included in mssql_execute().
-
var -
The PHP variable you'll bind the MSSQL parameter to. It is passed by reference, to retrieve OUTPUT and RETVAL values after the procedure execution.
-
type -
One of:
SQLTEXT,SQLVARCHAR,SQLCHAR,SQLINT1,SQLINT2,SQLINT4,SQLBIT,SQLFLT4,SQLFLT8,SQLFLTN. -
is_output -
Whether the value is an OUTPUT parameter or not. If it's an OUTPUT parameter and you don't mention it, it will be treated as a normal input parameter and no error will be thrown.
-
is_null -
Whether the parameter is
NULLor not. Passing theNULLvalue asvarwill not do the job. -
maxlen -
Used with char/varchar values. You have to indicate the length of the data so if the parameter is a varchar(50), the type must be
SQLVARCHARand this value 50.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 mssql_bind() example
<?php
// Connect to MSSQL and select the database
mssql_connect('KALLESPC\SQLEXPRESS', 'sa', 'phpfi');
mssql_select_db('php');
// Create a new stored prodecure
$stmt = mssql_init('NewUserRecord');
// Bind the field names
mssql_bind($stmt, '@username', 'Kalle', SQLVARCHAR, false, false, 60);
mssql_bind($stmt, '@name', 'Kalle', SQLVARCHAR, false, false, 60);
mssql_bind($stmt, '@age', 19, SQLINT1, false, false, 3);
// Execute
mssql_execute($stmt);
// Free statement
mssql_free_statement($stmt);
?>
Zobacz też:
- mssql_execute() - Executes a stored procedure on a MS SQL server database
- mssql_free_statement() - Free statement memory
- mssql_init() - Initializes a stored procedure or a remote stored procedure
mssql_close
(PHP 4, PHP 5, PECL odbtp >= 1.1.1)
mssql_close — Zamyka połączenie z MS SQL Server
Opis
$identyfikator_połączenia
] )Zamyka połączenie z MS SQL Server skojarzone z podanym identyfikatorem połączenia. Jeśli identyfikator_połączenia nie został podany, przyjmowane jest ostatnio otwarte połączenie.
Stosowanie tej funkcji zazwyczaj nie jest potrzebne, jako że niestałe połączenia są automatycznie zamykane po zakończeniu wykonywania skryptu.
Parametry
-
identyfikator_połączenia -
Identyfikator połączenia MS SQL, zwracany przez mssql_connect().
Ta funkcje nie zamyka stałych połączeń nawiązanych za pomocą mssql_pconnect().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Przykład mssql_close()
<?php
// Połączenie do MSSQL
$link = mssql_connect('KALLESPC\SQLEXPRESS', 'sa', 'phpfi');
// Wykonanie operacji na bazie danych
// Zamknięcie połączenia z MSSQL
mssql_close($link);
?>
Zobacz też:
- mssql_connect() - Otwiera połączenie z serwerem MS SQL
- mssql_pconnect() - Open persistent MS SQL connection
mssql_connect
(PHP 4, PHP 5, PECL odbtp >= 1.1.1)
mssql_connect — Otwiera połączenie z serwerem MS SQL
Opis
$nazwa_serwera
[, string $nazwa_użytkownika
[, string $hasło
[, bool $nowy_identyfikator_połączenia = false
]]]] )mssql_connect() nawiązuje połączenie do serwera MS SQL.
Połączenie do serwera powinno zostać zamknięte automatycznie zaraz po zakończeniu wykonywania skryptu, o ile nie zostanie zamknięte wcześniej poprzez jawne wywołanie mssql_close().
Parametry
-
nazwa_serwera -
Określa MS SQL Server. Może zawierać numer portu np. hostname:port (Linux), lub hostname,port (Windows).
-
nazwa_użytkownika -
Login użytkownika.
-
hasło -
Hasło użytkownika.
-
nowy_identyfikator_połączenia -
Jeśli następuje kolejne wywołanie mssql_connect() z tymi samymi argumentami, nie jest nawiązywanie nowe połączenie, lecz zamiast tego zwracany jest identyfikator już otwartego połączenia. Ten parametr modyfikuje to zachowanie tak, że mssql_connect() zawsze otwiera nowe połączenie, nawet gdy mssql_connect() była wywołana wcześniej z takimi samymi parametrami.
Zwracane wartości
Zwraca identyfikator połączenia do MS SQL w przypadku powodzenia lub FALSE w przypadku błędu.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.4.1 i 5.1.0 |
Dodano parametr nowy_identyfikator_połączenia
|
Przykłady
Przykład #1 mssql_connect() example
<?php
// Serwer w następującym formacie: <komputer>\<nazwa instancji> lub
// <serwer>,<port> jeśli używany jest niestandardowy port
$server = 'KALLESPC\SQLEXPRESS';
// Połączenie do MSSQL
$link = mssql_connect($server, 'sa', 'phpfi');
if (!$link) {
die('Wystąpił błąd podczas połączenia do MSSQL');
}
?>
Zobacz też:
- mssql_close() - Zamyka połączenie z MS SQL Server
- mssql_pconnect() - Open persistent MS SQL connection
mssql_data_seek
(PHP 4, PHP 5, PECL odbtp >= 1.1.1)
mssql_data_seek — Moves internal row pointer
Opis
$result_identifier
, int $row_number
)mssql_data_seek() moves the internal row pointer of the MS SQL result associated with the specified result identifier to point to the specified row number, first row being number 0. The next call to mssql_fetch_row() would return that row.
Parametry
-
result_identifier -
The result resource that is being evaluated.
-
row_number -
The desired row number of the new result pointer.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 mssql_data_seek() example
<?php
// Connect to MSSQL and select the database
$link = mssql_connect('MANGO\SQLEXPRESS', 'sa', 'phpfi');
mssql_select_db('php', $link);
// Select all people
$result = mssql_query('SELECT [name], [age] FROM [persons] WHERE [age] >= 13');
if (!$result) {
die('Query failed.');
}
// Select every 4th student in the results
for ($i = mssql_num_rows($result) - 1; $i % 4; $i++) {
if (!mssql_data_seek($result, $i)) {
continue;
}
// Fetch the row ...
}
// Free the query result
mssql_free_result($result);
?>
mssql_execute
(PHP 4 >= 4.0.7, PHP 5, PECL odbtp >= 1.1.1)
mssql_execute — Executes a stored procedure on a MS SQL server database
Opis
Executes a stored procedure on a MS SQL server database
Parametry
-
stmt -
Statement handle obtained with mssql_init().
-
skip_results -
Whenever to skip the results or not.
Przykłady
Przykład #1 mssql_execute() example
<?php
// Create a new statement
$stmt = mssql_init('NewBlogEntry');
// Some data strings
$title = 'Test of blogging system';
$content = 'If you can read this, then the new system is compatible with MSSQL';
// Bind values
mssql_bind($stmt, '@author', 'Felipe Pena', SQLVARCHAR, false, false, 60);
mssql_bind($stmt, '@date', '08/10/2008', SQLVARCHAR, false, false, 20);
mssql_bind($stmt, '@title', $title, SQLVARCHAR, false, false, 60);
mssql_bind($stmt, '@content', $content, SQLTEXT);
// Execute the statement
mssql_execute($stmt);
// And we can free it like so:
mssql_free_statement($stmt);
?>
Notatki
Informacja:
If the stored procedure returns parameters or a return value these will be available after the call to mssql_execute() unless the stored procedure returns more than one result set. In that case use mssql_next_result() to shift through the results. When the last result has been processed the output parameters and return values will be available.
Zobacz też:
- mssql_bind() - Adds a parameter to a stored procedure or a remote stored procedure
- mssql_free_statement() - Free statement memory
- mssql_init() - Initializes a stored procedure or a remote stored procedure
mssql_fetch_array
(PHP 4, PHP 5, PECL odbtp >= 1.1.1)
mssql_fetch_array — Fetch a result row as an associative array, a numeric array, or both
Opis
$result
[, int $result_type = MSSQL_BOTH
] )mssql_fetch_array() is an extended version of mssql_fetch_row(). In addition to storing the data in the numeric indices of the result array, it also stores the data in associative indices, using the field names as keys.
An important thing to note is that using mssql_fetch_array() is NOT significantly slower than using mssql_fetch_row(), while it provides a significant added value.
Parametry
-
result -
The result resource that is being evaluated. This result comes from a call to mssql_query().
-
result_type -
The type of array that is to be fetched. It's a constant and can take the following values:
MSSQL_ASSOC,MSSQL_NUM, andMSSQL_BOTH.
Zwracane wartości
Returns an array that corresponds to the fetched row, or FALSE if there
are no more rows.
Przykłady
Przykład #1 mssql_fetch_array() example
<?php
// Send a select query to MSSQL
$query = mssql_query('SELECT [username], [name] FROM [php].[dbo].[userlist]');
// Check if there were any records
if (!mssql_num_rows($query)) {
echo 'No records found';
} else {
// The following is equal to the code below:
//
// while ($row = mssql_fetch_row($query)) {
while ($row = mssql_fetch_array($query, MSSQL_NUM)) {
// ...
}
}
// Free the query result
mssql_free_result($query);
?>
Notatki
Informacja: Nazwy pól zwracane przez tą funkcję rozróżniają wielkość znaków.
Informacja: Ta funkcja ustala wartość pól NULL na
NULL.
mssql_fetch_assoc
(PHP 4 >= 4.2.0, PHP 5, PECL odbtp >= 1.1.1)
mssql_fetch_assoc — Returns an associative array of the current row in the result
Opis
$result_id
)
Returns an associative array that corresponds to the fetched row and moves
the internal data pointer ahead. mssql_fetch_assoc() is
equivalent to calling mssql_fetch_array() with
MSSQL_ASSOC for the optional second parameter.
Parametry
-
result_id -
The result resource that is being evaluated. This result comes from a call to mssql_query().
Zwracane wartości
Returns an associative array that corresponds to the fetched row, or
FALSE if there are no more rows.
Przykłady
Przykład #1 mssql_fetch_assoc() example
<?php
// Send a select query to MSSQL
$query = mssql_query('SELECT [username], [name] FROM [php].[dbo].[userlist]');
// Check if there were any records
if (!mssql_num_rows($query)) {
echo 'No records found';
}
else
{
// Print a nice list of users in the format of:
// * name (username)
echo '<ul>';
while ($row = mssql_fetch_assoc($query)) {
echo '<li>' . $row['name'] . ' (' . $row['username'] . ')</li>';
}
echo '</ul>';
}
// Free the query result
mssql_free_result($query);
?>
mssql_fetch_batch
(PHP 4 >= 4.0.4, PHP 5, PECL odbtp >= 1.1.1)
mssql_fetch_batch — Returns the next batch of records
Opis
$result
)Returns the next batch of records
Parametry
-
result -
The result resource that is being evaluated. This result comes from a call to mssql_query().
Zwracane wartości
Returns the batch number as an integer.
Przykłady
Przykład #1 mssql_fetch_batch() example
<?php
// Connect to MSSQL and select the database
$link = mssql_connect('MANGO\SQLEXPRESS', 'sa', 'phpfi');
mssql_select_db('php', $link);
// Send a query
$result = mssql_query('SELECT * FROM [php].[dbo].[people]', $link, 100);
$records = 10;
while ($records >= 0) {
while ($row = mssql_fetch_assoc($result)) {
// Do stuff ...
}
--$records;
}
if ($batchsize = mssql_fetch_batch($result)) {
// $batchsize is the number of records left
// in the result, but not shown above
}
?>
mssql_fetch_field
(PHP 4, PHP 5, PECL odbtp >= 1.1.1)
mssql_fetch_field — Get field information
Opis
$result
[, int $field_offset = -1
] )mssql_fetch_field() can be used in order to obtain information about fields in a certain query result.
Parametry
-
result -
The result resource that is being evaluated. This result comes from a call to mssql_query().
-
field_offset -
The numerical field offset. If the field offset is not specified, the next field that was not yet retrieved by this function is retrieved. The
field_offsetstarts at 0.
Zwracane wartości
Returns an object containing field information.
The properties of the object are:
- name - column name. if the column is a result of a function, this property is set to computed#N, where #N is a serial number.
- column_source - the table from which the column was taken
- max_length - maximum length of the column
- numeric - 1 if the column is numeric
- type - the column type.
Przykłady
Przykład #1 mssql_fetch_field() example
<?php
// Connect to MSSQL and select the database
mssql_connect('MANGO\SQLEXPRESS', 'sa', 'phpfi');
mssql_select_db('php');
// Send a select query to MSSQL
$query = mssql_query('SELECT * FROM [php].[dbo].[persons]');
// Construct table
echo '<h3>Table structure for \'persons\'</h3>';
echo '<table border="1">';
// Table header
echo '<thead>';
echo '<tr>';
echo '<td>Field name</td>';
echo '<td>Data type</td>';
echo '<td>Max length</td>';
echo '</tr>';
echo '</thead>';
// Dump all fields
echo '<tbody>';
for ($i = 0; $i < mssql_num_fields($query); ++$i) {
// Fetch the field information
$field = mssql_fetch_field($query, $i);
// Print the row
echo '<tr>';
echo '<td>' . $field->name . '</td>';
echo '<td>' . strtoupper($field->type) . '</td>';
echo '<td>' . $field->max_length . '</td>';
echo '</tr>';
}
echo '</tbody>';
echo '</table>';
// Free the query result
mssql_free_result($query);
?>
mssql_fetch_object
(PHP 4, PHP 5, PECL odbtp >= 1.1.1)
mssql_fetch_object — Fetch row as object
Opis
$result
)mssql_fetch_object() is similar to mssql_fetch_array(), with one difference - an object is returned, instead of an array. Indirectly, that means that you can only access the data by the field names, and not by their offsets (numbers are illegal property names).
Speed-wise, the function is identical to mssql_fetch_array(), and almost as quick as mssql_fetch_row() (the difference is insignificant).
Parametry
-
result -
The result resource that is being evaluated. This result comes from a call to mssql_query().
Zwracane wartości
Returns an object with properties that correspond to the fetched row, or
FALSE if there are no more rows.
Przykłady
Przykład #1 mssql_fetch_object() example
<?php
// Send a select query to MSSQL
$query = mssql_query('SELECT [username], [name] FROM [php].[dbo].[userlist]');
// Check if there were any records
if (!mssql_num_rows($query)) {
echo 'No records found';
} else {
// Print a nice list of users in the format of:
// * name (username)
echo '<ul>';
while ($row = mssql_fetch_object($query)) {
echo '<li>' . $row->name . ' (' . $row->username . ')</li>';
}
echo '</ul>';
}
// Free the query result
mssql_free_result($query);
?>
Notatki
Informacja: Nazwy pól zwracane przez tą funkcję rozróżniają wielkość znaków.
Informacja: Ta funkcja ustala wartość pól NULL na
NULL.
Zobacz też:
- mssql_fetch_array() - Fetch a result row as an associative array, a numeric array, or both
- mssql_fetch_row() - Get row as enumerated array
mssql_fetch_row
(PHP 4, PHP 5, PECL odbtp >= 1.1.1)
mssql_fetch_row — Get row as enumerated array
Opis
$result
)mssql_fetch_row() fetches one row of data from the result associated with the specified result identifier. The row is returned as an array. Each result column is stored in an array offset, starting at offset 0.
Subsequent call to mssql_fetch_row() would
return the next row in the result set, or FALSE if there are no
more rows.
Parametry
-
result -
The result resource that is being evaluated. This result comes from a call to mssql_query().
Zwracane wartości
Returns an array that corresponds to the fetched row, or FALSE if there
are no more rows.
Przykłady
Przykład #1 mssql_fetch_row() example
<?php
// Connect to MSSQL and select the database
$link = mssql_connect('MANGO\SQLEXPRESS', 'sa', 'phpfi');
mssql_select_db('php', $link);
// Query to execute
$query = mssql_query('SELECT [id], [quote] FROM [quotes] WHERE [id] = \'42\'', $link);
// Did the query fail?
if (!$query) {
die('MSSQL error: ' . mssql_get_last_message());
}
// Fetch the row
$row = mssql_fetch_row($query);
// Print the 'quote'
echo 'Quote #' . $row[0] . ': "' . $row[1] . '"';
?>
Powyższy przykład wyświetli coś podobnego do:
Quote #42: "The answer to everything..."
Notatki
Informacja: Ta funkcja ustala wartość pól NULL na
NULL.
Zobacz też:
- mssql_fetch_array() - Fetch a result row as an associative array, a numeric array, or both
- mssql_fetch_object() - Fetch row as object
- mssql_data_seek() - Moves internal row pointer
- mssql_result() - Get result data
mssql_field_length
(PHP 4, PHP 5, PECL odbtp >= 1.1.1)
mssql_field_length — Get the length of a field
Opis
$result
[, int $offset = -1
] )
Returns the length of field no. offset in
result.
Parametry
-
result -
The result resource that is being evaluated. This result comes from a call to mssql_query().
-
offset -
The field offset, starts at 0. If omitted, the current field is used.
Zwracane wartości
The length of the specified field index on success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 mssql_field_length() example
<?php
// Connect to MSSQL and select the database
mssql_connect('MANGO\SQLEXPRESS', 'sa', 'phpfi');
mssql_select_db('php');
// Send a select query to MSSQL
$query = mssql_query('SELECT [name], [age] FROM [php].[dbo].[persons]');
// Print the field length
echo 'The field \'age\' has a data length of ' . mssql_field_length($query, 1);
// Free the query result
mssql_free_result($query);
?>
Powyższy przykład wyświetli coś podobnego do:
The field 'age' has a data length of 4
Notatki
Informacja: Note to Windows Users
Due to a limitation in the underlying API used by PHP (MS DBLib C API), the length of VARCHAR fields is limited to 255. If you need to store more data, use a TEXT field instead.
Zobacz też:
- mssql_field_name() - Get the name of a field
- mssql_field_type() - Gets the type of a field
mssql_field_name
(PHP 4, PHP 5, PECL odbtp >= 1.1.1)
mssql_field_name — Get the name of a field
Opis
$result
[, int $offset = -1
] )
Returns the name of field no. offset in
result.
Parametry
-
result -
The result resource that is being evaluated. This result comes from a call to mssql_query().
-
offset -
The field offset, starts at 0. If omitted, the current field is used.
Zwracane wartości
The name of the specified field index on success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 mssql_field_name() example
<?php
// Send a select query to MSSQL
$query = mssql_query('SELECT [username], [name], [email] FROM [php].[dbo].[userlist]');
echo 'Result set contains the following field(s):', PHP_EOL;
// Dump all field names in result
for ($i = 0; $i < mssql_num_fields($query); ++$i) {
echo ' - ' . mssql_field_name($query, $i), PHP_EOL;
}
// Free the query result
mssql_free_result($query);
?>
Powyższy przykład wyświetli coś podobnego do:
Result set contains the following field(s): - username - name - email
Zobacz też:
- mssql_field_length() - Get the length of a field
- mssql_field_type() - Gets the type of a field
mssql_field_seek
(PHP 4, PHP 5, PECL odbtp >= 1.1.1)
mssql_field_seek — Seeks to the specified field offset
Opis
$result
, int $field_offset
)Seeks to the specified field offset. If the next call to mssql_fetch_field() won't include a field offset, this field would be returned.
Parametry
-
result -
The result resource that is being evaluated. This result comes from a call to mssql_query().
-
field_offset -
The field offset, starts at 0.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Using mssql_field_seek() on the example for mssql_fetch_field()
<?php
// Connect to MSSQL and select the database
mssql_connect('MANGO\SQLEXPRESS', 'sa', 'phpfi');
mssql_select_db('php');
// Send a select query to MSSQL
$query = mssql_query('SELECT * FROM [php].[dbo].[persons]');
// Construct table
echo '<h3>Table structure for \'persons\'</h3>';
echo '<table border="1">';
// Table header
echo '<thead>';
echo '<tr>';
echo '<td>Field name</td>';
echo '<td>Data type</td>';
echo '<td>Max length</td>';
echo '</tr>';
echo '</thead>';
// Dump all fields
echo '<tbody>';
for ($i = 0; $i < mssql_num_fields($query); ++$i) {
// Fetch the field information, notice the
// field_offset parameter is not set. See
// the mssql_field_seek call below
$field = mssql_fetch_field($query);
// Print the row
echo '<tr>';
echo '<td>' . $field->name . '</td>';
echo '<td>' . strtoupper($field->type) . '</td>';
echo '<td>' . $field->max_length . '</td>';
echo '</tr>';
// Move the internal seek pointer to the next
// row in the result set
mssql_field_seek($query, $i + 1);
}
echo '</tbody>';
echo '</table>';
// Free the query result
mssql_free_result($query);
?>
mssql_field_type
(PHP 4, PHP 5, PECL odbtp >= 1.1.1)
mssql_field_type — Gets the type of a field
Opis
$result
[, int $offset = -1
] )
Returns the type of field no. offset in
result.
Parametry
-
result -
The result resource that is being evaluated. This result comes from a call to mssql_query().
-
offset -
The field offset, starts at 0. If omitted, the current field is used.
Zwracane wartości
The type of the specified field index on success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 mssql_field_type() example
<?php
// Connect to MSSQL and select the database
mssql_connect('MANGO\SQLEXPRESS', 'sa', 'phpfi');
mssql_select_db('php');
// Send a select query to MSSQL
$query = mssql_query('SELECT [name] FROM [php].[dbo].[persons]');
// Print the field type and length
echo '\'' . mssql_field_name($query, 0) . '\' is a type of ' .
strtoupper(mssql_field_type($query, 0)) .
'(' . mssql_field_length($query, 0) . ')';
// Free the query result
mssql_free_result($query);
?>
Powyższy przykład wyświetli coś podobnego do:
'name' is a type of CHAR(50)
Zobacz też:
- mssql_field_length() - Get the length of a field
- mssql_field_name() - Get the name of a field
mssql_free_result
(PHP 4, PHP 5, PECL odbtp >= 1.1.1)
mssql_free_result — Free result memory
Opis
$result
)mssql_free_result() only needs to be called if you are worried about using too much memory while your script is running. All result memory will automatically be freed when the script ends. You may call mssql_free_result() with the result identifier as an argument and the associated result memory will be freed.
Parametry
-
result -
The result resource that is being freed. This result comes from a call to mssql_query().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 mssql_free_result() example
<?php
// Select some data from a table
$query = mssql_query('SELECT * FROM [php].[dbo].[persons]', $link);
// Handle query result here
// When we're done we free the result by calling
// mssql_free_result like so:
mssql_free_result($query);
?>
mssql_free_statement
(PHP 4 >= 4.3.2, PHP 5, PECL odbtp >= 1.1.1)
mssql_free_statement — Free statement memory
Opis
$stmt
)mssql_free_statement() only needs to be called if you are worried about using too much memory while your script is running. All statement memory will automatically be freed when the script ends. You may call mssql_free_statement() with the statement identifier as an argument and the associated statement memory will be freed.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 mssql_free_statement() example
<?php
// Create a new statement
$stmt = mssql_init('test');
// Bind values here and execute the statement
// once we're done, we clear it from the memory
// using mssql_free_statement like so:
mssql_free_statement($stmt);
?>
Zobacz też:
- mssql_bind() - Adds a parameter to a stored procedure or a remote stored procedure
- mssql_execute() - Executes a stored procedure on a MS SQL server database
- mssql_init() - Initializes a stored procedure or a remote stored procedure
- mssql_free_result() - Free result memory
mssql_get_last_message
(PHP 4, PHP 5, PECL odbtp >= 1.1.1)
mssql_get_last_message — Zwraca ostatni komunikat z serwera
Opis
Pobiera ostatni komunikat z serwera MS-SQL
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Zwraca ostatnią informację o błędzie z serwera lub pusty łańcuch znaków, jeśli MSSQL nie zwrócił żadnego błędu.
Przykłady
Przykład #1 Przykład mssql_get_last_message()
<?php
// Połączenie do MSSQL i wybranie bazy danych
mssql_connect('KALLESPC\SQLEXPRESS', 'sa', 'phpfi');
mssql_select_db('php');
// Make a query that will fail
$query = @mssql_query('SELECT * FROM [php].[dbo].[not-found]');
if (!$query) {
// The query has failed, print a nice error message
// using mssql_get_last_message()
die('MSSQL error: ' . mssql_get_last_message());
}
?>
Powyższy przykład wyświetli coś podobnego do:
MSSQL error: Invalid object name 'php.dbo.not-found'.
Zobacz też:
- mssql_min_error_severity() - Ustawia poziom ważności zwracanych kodów błędów
- mssql_min_message_severity() - Ustawia poziom ważności zwracanych komunikatów o błędach
mssql_guid_string
(PHP 4 >= 4.0.7, PHP 5, PECL odbtp >= 1.1.1)
mssql_guid_string — Converts a 16 byte binary GUID to a string
Opis
$binary
[, bool $short_format = false
] )Converts a 16 byte binary GUID to a string.
Parametry
-
binary -
A 16 byte binary GUID.
-
short_format -
Whenever to use short format.
Zwracane wartości
Returns the converted string on success.
Przykłady
Przykład #1 mssql_guid_string() example
<?php
$binary = '19555081977808608437941339997619274330352755554827939936';
var_dump(mssql_guid_string($binary));
var_dump(mssql_guid_string($binary, true));
?>
Powyższy przykład wyświetli:
string(36) "35353931-3035-3138-3937-373830383630" string(32) "31393535353038313937373830383630"
mssql_init
(PHP 4 >= 4.0.7, PHP 5, PECL odbtp >= 1.1.1)
mssql_init — Initializes a stored procedure or a remote stored procedure
Opis
$sp_name
[, resource $link_identifier
] )Initializes a stored procedure or a remote stored procedure.
Parametry
-
sp_name -
Stored procedure name, like ownew.sp_name or otherdb.owner.sp_name.
-
link_identifier -
A MS SQL link identifier, returned by mssql_connect().
Zwracane wartości
Returns a resource identifier "statement", used in subsequent calls to
mssql_bind() and mssql_execute(),
or FALSE on errors.
Przykłady
Przykład #1 mssql_init() example
<?php
// Connect to MSSQL and select the database
$link = mssql_connect('KALLESPC\SQLEXPRESS', 'sa', 'phpfi');
mssql_select_db('php', $link);
// Create a new statement
$stmt = mssql_init('StatementTest', $link);
// Bind values here
// Once values are binded we execute our statement
// using mssql_execute:
mssql_execute($stmt);
// And we can free it like so:
mssql_free_statement($stmt);
?>
Zobacz też:
- mssql_bind() - Adds a parameter to a stored procedure or a remote stored procedure
- mssql_execute() - Executes a stored procedure on a MS SQL server database
- mssql_free_statement() - Free statement memory
mssql_min_error_severity
(PHP 4, PHP 5, PECL odbtp >= 1.1.1)
mssql_min_error_severity — Ustawia poziom ważności zwracanych kodów błędów
Opis
$poziom ważności
)Ustawia poziom ważności zwracanych kodów błędów.
Parametry
-
poziom ważności -
Nowy poziom ważności zwracanych kodów błędów.
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 Przykład mssql_min_error_severity()
<?php
// Połączenie do MSSQL i wybór bazy danych
mssql_connect('KALLESPC\SQLEXPRESS', 'sa', 'phpfi');
mssql_select_db('php');
// Set the minimum error severity to not include SQL
// syntax errors by setting it to something greater than
// or equal to 1.
mssql_min_error_severity(1);
// Send a query we know that will cause an syntax error, in
// this case we use the MySQL quote signs instead of wrapping
// square brackets around the field and table names.
$query = mssql_query('SELECT `syntax`, `error` FROM `MSSQL`');
if (!$query) {
// Custom error handler ...
}
?>
mssql_min_message_severity
(PHP 4, PHP 5, PECL odbtp >= 1.1.1)
mssql_min_message_severity — Ustawia poziom ważności zwracanych komunikatów o błędach
Opis
$poziom ważności
)Ustawia poziom ważności zwracanych komunikatów o błędach
Parametry
-
poziom ważności -
Nowy poziom ważności zwracanych komunikatów o błędach.
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 Przykład mssql_min_message_severity()
<?php
// Połączenie do MSSQL
mssql_connect('KALLESPC\SQLEXPRESS', 'sa', 'phpfi');
// Ustaw poziom ważności zwracanych komunikatów o błędach na 17.
// To nie wywoła żadnego komunikatu o błędzie, gdy przez API
// zostanie wybrana nieistniejąca baza danych
mssql_min_message_severity(17);
// Wybranie nieistniejącej bazy danych
mssql_select_db('THIS_DATABASE_DOES_NOT_EXISTS');
?>
Powyższy przykład wyświetli:
mssql_select_db(): Nie można wybrać bazy danych: THIS_DATABASE_DOES_NOT_EXISTS
mssql_next_result
(PHP 4 >= 4.0.5, PHP 5, PECL odbtp >= 1.1.1)
mssql_next_result — Move the internal result pointer to the next result
Opis
$result_id
)When sending more than one SQL statement to the server or executing a stored procedure with multiple results, it will cause the server to return multiple result sets. This function will test for additional results available form the server. If an additional result set exists it will free the existing result set and prepare to fetch the rows from the new result set.
Parametry
-
result_id -
The result resource that is being evaluated. This result comes from a call to mssql_query().
Zwracane wartości
Returns TRUE if an additional result set was available or FALSE
otherwise.
Przykłady
Przykład #1 mssql_next_result() example
<?php
// Connect to MSSQL and select the database
$link = mssql_connect('MANGO\SQLEXPRESS', 'sa', 'phpfi');
mssql_select_db('php', $link);
// Send a query to MSSQL
$sql = 'SELECT [name], [age] FROM [php].[dbo].[persons]';
$query = mssql_query($sql, $link);
// Iterate through returned records
do {
while ($row = mssql_fetch_row($query)) {
// Handle record ...
}
} while (mssql_next_result($query));
// Clean up
mssql_free_result($query);
mssql_close($link);
?>
mssql_num_fields
(PHP 4, PHP 5, PECL odbtp >= 1.1.1)
mssql_num_fields — Zwraca liczbę pól w zbiorze wynikowym
Opis
$wynik
)mssql_num_fields() zwraca liczbę pól w zbiorze wynikowym.
Parametry
-
wynik -
Obliczane są zasoby zbioru wynikowego. Zbiór wynikowy powstaje w następstwie wywołania mssql_query().
Zwracane wartości
Zwraca liczbę pól, jako integer.
Przykłady
Przykład #1 Przykład mssql_num_fields()
<?php
// Połączenie do MSSQL i wybór bazy danych
$link = mssql_connect('KALLESPC\SQLEXPRESS', 'sa', 'phpfi');
mssql_select_db('php', $link);
// Pobranie danych z bazy danych
$data = mssql_query('SELECT [name], [age] FROM [php].[dbo].[persons]');
// Utworzenie tabeli HTML
echo '<table border="1">';
$header = false;
// Iteracja, dopóki zwracane są wiersze
while ($row = mssql_fetch_array($data)) {
// Utworzenie nagłówka tabeli HTML
if (!$header) {
echo '<thead>';
echo '<tr>';
for ($i = 1; ($i + 1) <= mssql_num_fields($data); ++$i) {
echo '<td>' . ucfirst($row[$i]) . '</td>';
}
echo '</tr>';
echo '</thead>';
echo '<tbody>';
$header = true;
}
// Utworzenie wiersza HTML
echo '<tr>';
foreach($row as $value) {
echo '<td>' . $value . '</td>';
}
echo '</tr>';
}
// Zamknięcie tabeli HTML
echo '</tbody>';
echo '</table>';
// Zwolnienie pamięci zajmowanej przez wynik
mssql_free_result($data);
mssql_close($link);
?>
Zobacz też:
- mssql_query() - Wysyła zapytanie do serwera MS SQL
- mssql_fetch_field() - Get field information
- mssql_num_rows() - Zwraca liczbę wierszy w zbiorze wynikowym
mssql_num_rows
(PHP 4, PHP 5, PECL odbtp >= 1.1.1)
mssql_num_rows — Zwraca liczbę wierszy w zbiorze wynikowym
Opis
$wynik
)mssql_num_rows() zwraca liczbę wierszy znajdujących się w zbiorze wynikowym.
Parametry
-
wynik -
Obliczane są zasoby zbioru wynikowego. Zbiór wynikowy powstaje w następstwie wywołania mssql_query().
Zwracane wartości
Zwraca liczbę wierszy, jako integer.
Przykłady
Przykład #1 Przykład mssql_num_rows()
<?php
// Połączenie do MSSQL i wybór bazy danych
$link = mssql_connect('KALLESPC\SQLEXPRESS', 'sa', 'phpfi');
mssql_select_db('php');
// Pobranie wszystkich wierszy z tabeli
$query = mssql_query('SELECT * FROM [php].[dbo].[persons]');
echo 'Liczba wierszy w tabeli: ' . mssql_num_rows($query);
// Clean up
mssql_free_result($query);
?>
Zobacz też:
- mssql_query() - Wysyła zapytanie do serwera MS SQL
- mssql_fetch_row() - Get row as enumerated array
mssql_pconnect
(PHP 4, PHP 5, PECL odbtp >= 1.1.1)
mssql_pconnect — Open persistent MS SQL connection
Opis
$servername
[, string $username
[, string $password
[, bool $new_link = false
]]]] )mssql_pconnect() acts very much like mssql_connect() with two major differences.
First, when connecting, the function would first try to find a (persistent) link that's already open with the same host, username and password. If one is found, an identifier for it will be returned instead of opening a new connection.
Second, the connection to the SQL server will not be closed when the execution of the script ends. Instead, the link will remain open for future use (mssql_close() will not close links established by mssql_pconnect()).
This type of links is therefore called 'persistent'.
Parametry
-
servername -
The MS SQL server. It can also include a port number. e.g. hostname:port.
-
username -
The username.
-
password -
The password.
-
new_link -
If a second call is made to mssql_pconnect() with the same arguments, no new link will be established, but instead, the link identifier of the already opened link will be returned. This parameter modifies this behavior and makes mssql_pconnect() always open a new link, even if mssql_pconnect() was called before with the same parameters.
Zwracane wartości
Returns a positive MS SQL persistent link identifier on success, or
FALSE on error.
Przykłady
Przykład #1 mssql_pconnect() using the new_link parameter
<?php
// Connect to MSSQL and select the database
$link1 = mssql_pconnect('MANGO\SQLEXPRESS', 'sa', 'phpfi');
mssql_select_db('php', $link1);
// Create a new link
$link2 = mssql_pconnect('MANGO\SQLEXPRESS', 'sa', 'phpfi', true);
mssql_select_db('random', $link2);
?>
mssql_query
(PHP 4, PHP 5, PECL odbtp >= 1.1.1)
mssql_query — Wysyła zapytanie do serwera MS SQL
Opis
$zapytanie
[, resource $identyfikator_połączenia
[, int $ograniczenie_liczby_wyników
]] )mssql_query() wysyła zapytanie do aktywnej bazy danych, na serwerze skojarzonym za pomocą identyfikatora połączenia.
Parametry
-
zapytanie -
Zapytanie SQL.
-
identyfikator_połączenia -
Identyfikator połączenia z MS SQL, zwrócony przez mssql_connect() lub mssql_pconnect().
Jeśli nie podano identyfikatora połączenia, przyjmowane jest ostatnio otwarte połączenie. Jeśli połączenie nie jest otwarte, funkcja próbuje nawiązać nowe i go użyć, tak jakby została wywołana mssql_connect().
-
ograniczenie_liczby_wyników -
Maksymalna liczba rekordów, które mają zostać umieszczone w buforze wynikowym.
Zwracane wartości
Zwraca identyfikator zbioru wynikowego, TRUE jeśli nie zostały
zwrócone wiersze lub FALSE kiedy wystąpił błąd.
Przykłady
Przykład #1 Przykład mssql_query()
<?php
// Połączenie do MSSQL
$link = mssql_connect('KALLESPC\SQLEXPRESS', 'sa', 'phpfi');
if (!$link || !mssql_select_db('php', $link)) {
die('Nie można nawiązać połączenia lub wybrać bazy danych!');
}
// Wykonaj proste zapytanie, pobierz wersję
// MSSQL i ją wyświetl.
$version = mssql_query('SELECT @@VERSION');
$row = mssql_fetch_array($version);
echo $row[0];
// Zwolnienie zasobów serwera zajmowanych przez zbiór wynikowy
mssql_free_result($version);
?>
Notatki
Informacja:
Jeśli zapytanie zwraca wiele wyników, wówczas konieczne jest pobranie ich wszystkich za pomocą mssql_next_result() lub też zwolnienie za pomocą mssql_free_result() przed wykonaniem następnego zapytania.
Zobacz też:
- mssql_select_db() - Select MS SQL database
- mssql_connect() - Otwiera połączenie z serwerem MS SQL
mssql_result
(PHP 4, PHP 5, PECL odbtp >= 1.1.1)
mssql_result — Get result data
Opis
mssql_result() returns the contents of one cell from a MS SQL result set.
Parametry
-
result -
The result resource that is being evaluated. This result comes from a call to mssql_query().
-
row -
The row number.
-
field -
Can be the field's offset, the field's name or the field's table dot field's name (tablename.fieldname). If the column name has been aliased ('select foo as bar from...'), it uses the alias instead of the column name.
Informacja:
Specifying a numeric offset for the
fieldargument is much quicker than specifying a fieldname or tablename.fieldname argument.
Zwracane wartości
Returns the contents of the specified cell.
Przykłady
Przykład #1 mssql_result() example
<?php
// Send a select query to MSSQL
$query = mssql_query('SELECT [username] FROM [php].[dbo].[userlist]');
// Check if there were any records
if (!mssql_num_rows($query)) {
echo 'No records found';
} else {
for ($i = 0; $i < mssql_num_rows($query); ++$i) {
echo mssql_result($query, $i, 'username'), PHP_EOL;
}
}
// Free the query result
mssql_free_result($query);
?>
Powyższy przykład wyświetli coś podobnego do:
Kalle Felipe Emil Ross
Przykład #2 Faster alternative to above example
<?php
// Send a select query to MSSQL
$query = mssql_query('SELECT [username] FROM [php].[dbo].[userlist]');
// Check if there were any records
if (!mssql_num_rows($query)) {
echo 'No records found';
} else {
while ($row = mssql_fetch_array($query)) {
echo $row['username'], PHP_EOL;
}
}
// Free the query result
mssql_free_result($query);
?>
Notatki
Informacja:
When working on large result sets, you should consider using one of the functions that fetch an entire row (specified below). As these functions return the contents of multiple cells in one function call, they're MUCH quicker than mssql_result().
Zobacz też:
Recommended high-performance alternatives:
- mssql_fetch_row() - Get row as enumerated array
- mssql_fetch_array() - Fetch a result row as an associative array, a numeric array, or both
- mssql_fetch_assoc() - Returns an associative array of the current row in the result
- mssql_fetch_object() - Fetch row as object
mssql_rows_affected
(PHP 4 >= 4.0.4, PHP 5, PECL odbtp >= 1.1.1)
mssql_rows_affected — Zwraca liczbę rekordów przetworzonych przez ostatnie zapytanie
Opis
$identyfikator_połączenia
)Zwraca liczbę rekordów przetworzonych przez ostatnie zapytanie do obróbki danych.
Parametry
-
identyfikator_połączenia -
Identyfikator połączenia z serwerem MS SQL, zwracany przez mssql_connect() lub mssql_pconnect().
Zwracane wartości
Zwraca liczbę rekordów przetworzonych podczas ostatniej operacji.
Przykłady
Przykład #1 Przykład mssql_rows_affected()
<?php
// Usuń wszystkie rekordy z tabeli
mssql_query('TRUNCATE TABLE [php].[dbo].[persons]');
echo 'Usunięto ' . mssql_rows_affected($link) . ' rekordów';
?>
mssql_select_db
(PHP 4, PHP 5, PECL odbtp >= 1.1.1)
mssql_select_db — Select MS SQL database
Opis
$database_name
[, resource $link_identifier
] )mssql_select_db() sets the current active database on the server that's associated with the specified link identifier.
Every subsequent call to mssql_query() will be made on the active database.
Parametry
-
database_name -
The database name.
To escape the name of a database that contains spaces, hyphens ("-"), or any other exceptional characters, the database name must be enclosed in brackets, as is shown in the example, below. This technique must also be applied when selecting a database name that is also a reserved word (such as primary).
-
link_identifier -
A MS SQL link identifier, returned by mssql_connect() or mssql_pconnect().
If no link identifier is specified, the last opened link is assumed. If no link is open, the function will try to establish a link as if mssql_connect() was called, and use it.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 mssql_select_db() example
<?php
// Create a link to MSSQL
$link = mssql_connect('KALLESPC\SQLEXPRESS', 'sa', 'phpfi');
// Select the database 'php'
mssql_select_db('php', $link);
?>
Przykład #2 Escaping the database name with square brackets
<?php
// Create a link to MSSQL
$link = mssql_connect('KALLESPC\SQLEXPRESS', 'sa', 'phpfi');
// Select the database 'my.database-name'
mssql_select_db('[my.database-name]', $link);
?>
Zobacz też:
- mssql_connect() - Otwiera połączenie z serwerem MS SQL
- mssql_pconnect() - Open persistent MS SQL connection
- mssql_query() - Wysyła zapytanie do serwera MS SQL
Spis treści
- mssql_bind — Adds a parameter to a stored procedure or a remote stored procedure
- mssql_close — Zamyka połączenie z MS SQL Server
- mssql_connect — Otwiera połączenie z serwerem MS SQL
- mssql_data_seek — Moves internal row pointer
- mssql_execute — Executes a stored procedure on a MS SQL server database
- mssql_fetch_array — Fetch a result row as an associative array, a numeric array, or both
- mssql_fetch_assoc — Returns an associative array of the current row in the result
- mssql_fetch_batch — Returns the next batch of records
- mssql_fetch_field — Get field information
- mssql_fetch_object — Fetch row as object
- mssql_fetch_row — Get row as enumerated array
- mssql_field_length — Get the length of a field
- mssql_field_name — Get the name of a field
- mssql_field_seek — Seeks to the specified field offset
- mssql_field_type — Gets the type of a field
- mssql_free_result — Free result memory
- mssql_free_statement — Free statement memory
- mssql_get_last_message — Zwraca ostatni komunikat z serwera
- mssql_guid_string — Converts a 16 byte binary GUID to a string
- mssql_init — Initializes a stored procedure or a remote stored procedure
- mssql_min_error_severity — Ustawia poziom ważności zwracanych kodów błędów
- mssql_min_message_severity — Ustawia poziom ważności zwracanych komunikatów o błędach
- mssql_next_result — Move the internal result pointer to the next result
- mssql_num_fields — Zwraca liczbę pól w zbiorze wynikowym
- mssql_num_rows — Zwraca liczbę wierszy w zbiorze wynikowym
- mssql_pconnect — Open persistent MS SQL connection
- mssql_query — Wysyła zapytanie do serwera MS SQL
- mssql_result — Get result data
- mssql_rows_affected — Zwraca liczbę rekordów przetworzonych przez ostatnie zapytanie
- mssql_select_db — Select MS SQL database
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Funkcje Mssql
- mssql_bind — Adds a parameter to a stored procedure or a remote stored procedure
- mssql_close — Zamyka połączenie z MS SQL Server
- mssql_connect — Otwiera połączenie z serwerem MS SQL
- mssql_data_seek — Moves internal row pointer
- mssql_execute — Executes a stored procedure on a MS SQL server database
- mssql_fetch_array — Fetch a result row as an associative array, a numeric array, or both
- mssql_fetch_assoc — Returns an associative array of the current row in the result
- mssql_fetch_batch — Returns the next batch of records
- mssql_fetch_field — Get field information
- mssql_fetch_object — Fetch row as object
- mssql_fetch_row — Get row as enumerated array
- mssql_field_length — Get the length of a field
- mssql_field_name — Get the name of a field
- mssql_field_seek — Seeks to the specified field offset
- mssql_field_type — Gets the type of a field
- mssql_free_result — Free result memory
- mssql_free_statement — Free statement memory
- mssql_get_last_message — Zwraca ostatni komunikat z serwera
- mssql_guid_string — Converts a 16 byte binary GUID to a string
- mssql_init — Initializes a stored procedure or a remote stored procedure
- mssql_min_error_severity — Ustawia poziom ważności zwracanych kodów błędów
- mssql_min_message_severity — Ustawia poziom ważności zwracanych komunikatów o błędach
- mssql_next_result — Move the internal result pointer to the next result
- mssql_num_fields — Zwraca liczbę pól w zbiorze wynikowym
- mssql_num_rows — Zwraca liczbę wierszy w zbiorze wynikowym
- mssql_pconnect — Open persistent MS SQL connection
- mssql_query — Wysyła zapytanie do serwera MS SQL
- mssql_result — Get result data
- mssql_rows_affected — Zwraca liczbę rekordów przetworzonych przez ostatnie zapytanie
- mssql_select_db — Select MS SQL database
MySQL Drivers and Plugins
PHP offers several MySQL drivers and plugins for accessing and handling MySQL.
The differences and functionality of the MySQL extensions are described within the overview of this section.
Overview of the MySQL PHP drivers
Terminology overview
This section provides an introduction to the options available to you when developing a PHP application that needs to interact with a MySQL database.
What is an API?
An Application Programming Interface, or API, defines the classes, methods, functions and variables that your application will need to call in order to carry out its desired task. In the case of PHP applications that need to communicate with databases the necessary APIs are usually exposed via PHP extensions.
APIs can be procedural or object-oriented. With a procedural API you call functions to carry out tasks, with the object-oriented API you instantiate classes and then call methods on the resulting objects. Of the two the latter is usually the preferred interface, as it is more modern and leads to better organized code.
When writing PHP applications that need to connect to the MySQL server there are several API options available. This document discusses what is available and how to select the best solution for your application.
What is a Connector?
In the MySQL documentation, the term connector refers to a piece of software that allows your application to connect to the MySQL database server. MySQL provides connectors for a variety of languages, including PHP.
If your PHP application needs to communicate with a database server you will need to write PHP code to perform such activities as connecting to the database server, querying the database and other database-related functions. Software is required to provide the API that your PHP application will use, and also handle the communication between your application and the database server, possibly using other intermediate libraries where necessary. This software is known generically as a connector, as it allows your application to connect to a database server.
What is a Driver?
A driver is a piece of software designed to communicate with a specific type of database server. The driver may also call a library, such as the MySQL Client Library or the MySQL Native Driver. These libraries implement the low-level protocol used to communicate with the MySQL database server.
By way of an example, the PHP Data Objects (PDO) database abstraction layer may use one of several database-specific drivers. One of the drivers it has available is the PDO MYSQL driver, which allows it to interface with the MySQL server.
Sometimes people use the terms connector and driver interchangeably, this can be confusing. In the MySQL-related documentation the term "driver" is reserved for software that provides the database-specific part of a connector package.
What is an Extension?
In the PHP documentation you will come across another term - extension. The PHP code consists of a core, with optional extensions to the core functionality. PHP's MySQL-related extensions, such as the mysqli extension, and the mysql extension, are implemented using the PHP extension framework.
An extension typically exposes an API to the PHP programmer, to allow its facilities to be used programmatically. However, some extensions which use the PHP extension framework do not expose an API to the PHP programmer.
The PDO MySQL driver extension, for example, does not expose an API to the PHP programmer, but provides an interface to the PDO layer above it.
The terms API and extension should not be taken to mean the same thing, as an extension may not necessarily expose an API to the programmer.
Choosing an API
PHP offers three different APIs to connect to MySQL. Below we show the APIs provided by the mysql, mysqli, and PDO extensions. Each code snippet creates a connection to a MySQL server running on "example.com" using the username "user" and the password "password". And a query is run to greet the user.
Przykład #1 Comparing the three MySQL APIs
<?php
// mysqli
$mysqli = new mysqli("example.com", "user", "password", "database");
$result = $mysqli->query("SELECT 'Hello, dear MySQL user!' AS _message FROM DUAL");
$row = $result->fetch_assoc();
echo htmlentities($row['_message']);
// PDO
$pdo = new PDO('mysql:host=example.com;dbname=database', 'user', 'password');
$statement = $pdo->query("SELECT 'Hello, dear MySQL user!' AS _message FROM DUAL");
$row = $statement->fetch(PDO::FETCH_ASSOC);
echo htmlentities($row['_message']);
// mysql
$c = mysql_connect("example.com", "user", "password");
mysql_select_db("database");
$result = mysql_query("SELECT 'Hello, dear MySQL user!' AS _message FROM DUAL");
$row = mysql_fetch_assoc($result);
echo htmlentities($row['_message']);
?>
Recommended API
It is recommended to use either the mysqli or PDO_MySQL extensions. It is not recommended to use the old mysql extension for new development. A detailed feature comparison matrix is provided below. The overall performance of all three extensions is considered to be about the same. Although the performance of the extension contributes only a fraction of the total run time of a PHP web request. Often, the impact is as low as 0.1%.
Feature comparison
| ext/mysqli | PDO_MySQL | ext/mysql | |
|---|---|---|---|
| PHP version introduced | 5.0 | 5.1 | 2.0 |
| Included with PHP 5.x | Yes | Yes | Yes |
| Development status | Active | Active | Maintenance only |
| Lifecycle | Active | Active | Long term deprecation announced |
| Recommended for new projects | Yes | Yes | No |
| OOP Interface | Yes | Yes | No |
| Procedural Interface | Yes | No | Yes |
| API supports non-blocking, asynchronous queries with mysqlnd | Yes | No | No |
| Persistent Connections | Yes | Yes | Yes |
| API supports Charsets | Yes | Yes | Yes |
| API supports server-side Prepared Statements | Yes | Yes | No |
| API supports client-side Prepared Statements | No | Yes | No |
| API supports Stored Procedures | Yes | Yes | No |
| API supports Multiple Statements | Yes | Most | No |
| API supports Transactions | Yes | Yes | No |
| Transactions can be controlled with SQL | Yes | Yes | Yes |
| API supports Transactions | Yes | Yes | No |
| Supports all MySQL 5.1+ functionality | Yes | Most | No |
Choosing a library
The mysqli, PDO_MySQL and mysql PHP extensions are lightweight wrappers on top of a C client library. The extensions can either use the mysqlnd library or the libmysql library. Choosing a library is a compile time decision.
The mysqlnd library is part of the PHP distribution since 5.3.0. It offers features like lazy connections and query caching, features that are not available with libmysql, so using the built-in mysqlnd library is highly recommended. See the mysqlnd documentation for additional details, and a listing of features and functionality that it offers.
Przykład #1 Configure commands for using mysqlnd or libmysql
// Recommended, compiles with mysqlnd $ ./configure --with-mysqli=mysqlnd --with-pdo-mysql=mysqlnd --with-mysql=mysqlnd // Not recommended, compiles with libmysql $ ./configure --with-mysqli=/path/to/mysql_config --with-pdo-mysql=/path/to/mysql_config --with-mysql=/path/to/mysql_config
Library feature comparison
It is recommended to use the mysqlnd library instead of the MySQL Client Server library (libmysql). Both libraries are supported and constantly being improved.
| MySQL native driver (mysqlnd) | MySQL client server library (libmysql) | |
|---|---|---|
| Part of the PHP distribution | Yes | No |
| PHP version introduced | 5.3.0 | N/A |
| License | PHP License 3.01 | Dual-License |
| Development status | Active | Active |
| Lifecycle | No end announced | No end announced |
| PHP 5.4 compile default (for all MySQL extensions) | Yes | No |
| PHP 5.3 compile default (for all MySQL extensions) | No | Yes |
| Compression protocol support | Yes (5.3.1+) | yes |
| SSL support | Yes (5.3.3+) | Yes |
| Named pipe support | Yes (5.3.4+) | Yes |
| Non-blocking, asynchronous queries | Yes | No |
| Performance statistics | Yes | No |
| LOAD LOCAL INFILE respects the open_basedir directive | Yes | No |
| PHP memory limits followed | Yes | No |
| Return numeric column as double (COM_QUERY) | Yes | No |
| Return numeric column as string (COM_QUERY) | Yes | Yes |
| Plugin API | Yes | Limited |
| Read/Write splitting for MySQL Replication | Yes, with plugin | No |
| Load Balancing | Yes, with plugin | No |
| Fail over | Yes, with plugin | No |
| Lazy connections | Yes, with plugin | No |
| Query caching | Yes, with plugin | No |
| Transparent query manipulations (E.g., auto-EXPLAIN or monitoring) | Yes, with plugin | No |
Oryginalne API MySQL
Wstęp
Te funkcje pozwalają na dostęp do serwerów baz danych MySQL. Wiecej informacji o MySQL znajduje się pod adresem » http://www.mysql.com/.
Dokumentacja MySQL znajduje się pod adresem » http://dev.mysql.com/doc/.
Przegląd warunków połączenia do bazy danych MySQL i produktów znajduje się na stronie Overview.
Instalacja/Konfiguracja
Spis treści
Wymagania
Aby te funkcje były dostępne należy skompilować PHP z obsługą MySQL.
Instalacja
For compiling, simply use the --with-mysql[=DIR] configuration option where the optional [DIR] points to the MySQL installation directory.
Although this MySQL extension is compatible with MySQL 4.1.0 and greater, it doesn't support the extra functionality that these versions provide. For that, use the MySQLi extension.
If you would like to install the mysql extension along with the mysqli extension you have to use the same client library to avoid any conflicts.
Installation on Linux Systems
Note: [DIR] is the path to the MySQL client library files (headers and libraries), which can be downloaded from » MySQL.
| PHP Wersja | Domyślnie | Opcje konfiguracyjne: mysqlnd | Opcje konfiguracyjne: libmysql | Rejestr zmian |
|---|---|---|---|---|
| 4.x.x | libmysql | Niedostępne | --without-mysql to disable | MySQL enabled by default, MySQL client libraries are bundled |
| 5.0.x, 5.1.x, 5.2.x | libmysql | Niedostępne | --with-mysql=[DIR] | MySQL is no longer enabled by default, and the MySQL client libraries are no longer bundled |
| 5.3.x | libmysql | --with-mysql=mysqlnd | --with-mysql=[DIR] | mysqlnd is now available |
| 5.4.x | mysqlnd | --with-mysql | --with-mysql=[DIR] | mysqlnd is now the default |
Installation on Windows Systems
PHP 4
The PHP MySQL extension is compiled into PHP.
PHP 5.0.x, 5.1.x, 5.2.x
MySQL is no longer enabled by default, so the php_mysql.dll DLL must be enabled inside of php.ini. Also, PHP needs access to the MySQL client library. A file named libmysql.dll is included in the Windows PHP distribution and in order for PHP to talk to MySQL this file needs to be available to the Windows systems PATH. See the FAQ titled "How do I add my PHP directory to the PATH on Windows" for information on how to do this. Although copying libmysql.dll to the Windows system directory also works (because the system directory is by default in the system's PATH), it's not recommended.
As with enabling any PHP extension (such as php_mysql.dll), the PHP directive extension_dir should be set to the directory where the PHP extensions are located. See also the Manual Windows Installation Instructions. An example extension_dir value for PHP 5 is c:\php\ext
Informacja:
If when starting the web server an error similar to the following occurs: "Unable to load dynamic library './php_mysql.dll'", this is because php_mysql.dll and/or libmysql.dll cannot be found by the system.
PHP 5.3.0+
The MySQL Native Driver is enabled by default. Include php_mysql.dll, but libmysql.dll is no longer required or used.
MySQL Installation Notes
Crashes and startup problems of PHP may be encountered when loading this extension in conjunction with the recode extension. See the recode extension for more information.
Informacja:
If you need charsets other than latin (default), you have to install external (not bundled) libmysql with compiled charset support.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| mysql.allow_local_infile | "1" | PHP_INI_SYSTEM | |
| mysql.allow_persistent | "1" | PHP_INI_SYSTEM | |
| mysql.max_persistent | "-1" | PHP_INI_SYSTEM | |
| mysql.max_links | "-1" | PHP_INI_SYSTEM | |
| mysql.trace_mode | "0" | PHP_INI_ALL | Available since PHP 4.3.0. |
| mysql.default_port | NULL | PHP_INI_ALL | |
| mysql.default_socket | NULL | PHP_INI_ALL | Available since PHP 4.0.1. |
| mysql.default_host | NULL | PHP_INI_ALL | |
| mysql.default_user | NULL | PHP_INI_ALL | |
| mysql.default_password | NULL | PHP_INI_ALL | |
| mysql.connect_timeout | "60" | PHP_INI_ALL | PHP_INI_SYSTEM in PHP <= 4.3.2. Available since PHP 4.3.0. |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
mysql.allow_local_infileinteger -
Allow accessing, from PHP's perspective, local files with LOAD DATA statements
-
mysql.allow_persistentboolean -
Whether to allow persistent connections to MySQL.
-
mysql.max_persistentinteger -
The maximum number of persistent MySQL connections per process.
-
mysql.max_linksinteger -
The maximum number of MySQL connections per process, including persistent connections.
-
mysql.trace_modeboolean -
Trace mode. When mysql.trace_mode is enabled, warnings for table/index scans, non free result sets, and SQL-Errors will be displayed. (Introduced in PHP 4.3.0)
-
mysql.default_portstring -
The default TCP port number to use when connecting to the database server if no other port is specified. If no default is specified, the port will be obtained from the MYSQL_TCP_PORT environment variable, the mysql-tcp entry in /etc/services or the compile-time
MYSQL_PORTconstant, in that order. Win32 will only use theMYSQL_PORTconstant. -
mysql.default_socketstring -
The default socket name to use when connecting to a local database server if no other socket name is specified.
-
mysql.default_hoststring -
The default server host to use when connecting to the database server if no other host is specified. Doesn't apply in tryb bezpieczny SQL.
-
mysql.default_userstring -
The default user name to use when connecting to the database server if no other name is specified. Doesn't apply in tryb bezpieczny SQL.
-
mysql.default_passwordstring -
The default password to use when connecting to the database server if no other password is specified. Doesn't apply in tryb bezpieczny SQL.
-
mysql.connect_timeoutinteger -
Connect timeout in seconds. On Linux this timeout is also used for waiting for the first answer from the server.
Typy zasobów
Istnieją dwa typy zasobów używane w module MySQL. Pierwszy z nich to identyfikator połączenia do bazy danych. Drugi zasób przechowuje wynik zapytania.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
Since PHP 4.3.0 it is possible to specify additional client flags for the mysql_connect() and mysql_pconnect() functions. The following constants are defined:
| Constant | Description |
|---|---|
MYSQL_CLIENT_COMPRESS |
Use compression protocol |
MYSQL_CLIENT_IGNORE_SPACE |
Allow space after function names |
MYSQL_CLIENT_INTERACTIVE |
Allow interactive_timeout seconds (instead of wait_timeout ) of inactivity before closing the connection. |
MYSQL_CLIENT_SSL |
Use SSL encryption. This flag is only available with version 4.x of the MySQL client library or newer. Version 3.23.x is bundled both with PHP 4 and Windows binaries of PHP 5. |
The function mysql_fetch_array() uses a constant for the different types of result arrays. The following constants are defined:
| Constant | Description |
|---|---|
MYSQL_ASSOC |
Columns are returned into the array having the fieldname as the array index. |
MYSQL_BOTH |
Columns are returned into the array having both a numerical index and the fieldname as the array index. |
MYSQL_NUM |
Columns are returned into the array having a numerical index to the fields. This index starts with 0, the first field in the result. |
Przykłady
Spis treści
MySQL extension overview example
This simple example shows how to connect, execute a query, print resulting rows and disconnect from a MySQL database.
Przykład #1 MySQL extension overview example
<?php
// Connecting, selecting database
$link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password')
or die('Could not connect: ' . mysql_error());
echo 'Connected successfully';
mysql_select_db('my_database') or die('Could not select database');
// Performing SQL query
$query = 'SELECT * FROM my_table';
$result = mysql_query($query) or die('Query failed: ' . mysql_error());
// Printing results in HTML
echo "<table>\n";
while ($line = mysql_fetch_array($result, MYSQL_ASSOC)) {
echo "\t<tr>\n";
foreach ($line as $col_value) {
echo "\t\t<td>$col_value</td>\n";
}
echo "\t</tr>\n";
}
echo "</table>\n";
// Free resultset
mysql_free_result($result);
// Closing connection
mysql_close($link);
?>
MySQL Funkcje
Notatki
Informacja:
Most MySQL functions accept
link_identifieras the last optional parameter. If it is not provided, last opened connection is used. If it doesn't exist, connection is tried to establish with default parameters defined in php.ini. If it is not successful, functions returnFALSE.
mysql_affected_rows
(PHP 4, PHP 5)
mysql_affected_rows — Zwraca liczbę wierszy przetworzonych w poprzedniej operacji MySQL
Opis
$identyfikator_połączenia
] )
Pobiera liczbę wierszy przetworzonych w ostatnim zapytaniu INSERT, UPDATE, REPLACE
lub DELETE skojarzonym z identyfikator_połączenia.
Parametry
-
identyfikator_połączenia -
Połączenie MySQL. Jeśli identyfikator połączenia nie zostanie podany, użyte zostanie ostatnie połączenie otwarte przez mysql_connect(). Jeśli połączenie takie nie zostanie znalezione, funkcja spróbuje nawiązać połączenie tak, jakby wywołana została funkcja mysql_connect() bez argumentów. Jeśli żadne połączenie nie zostanie znalezione lub nawiązane, wygenerowany zostanie błąd poziomu
E_WARNING.
Zwracane wartości
Zwraca liczbę przetworzonych wierszy w przypadku sukcesu i -1 jeśli ostatnie zapytanie zawiedzie.
Jeżeli ostatnim zapytaniem było DELETE bez użycia klauzuli WHERE, wszystkie rekordy zostaną usunięte z tabeli, ale funkcja zwróci zero w wersjach MySQL starszych niż 4.1.2.
Podczas operacji UPDATE, MySQL nie aktualizuje kolumn w których nowa wartość jest identyczna z poprzednią. Możliwe jest zatem, że zwrócona przez mysql_affected_rows() liczba nie będzie odpowiadać liczbie wierszy pasujących do zapytania, ale tych, które zostały faktycznie zmienione.
Wyrażenie REPLACE najpierw skasuje rekord z tym samym kluczem głównym następnie wstawi nowy rekord. Ta funkcja zwraca liczbę skasowanych rekordów plus liczbę wstawionych rekordów.
Przykłady
Przykład #1 Przykład mysql_affected_rows()
<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
die('Nie można się połączyć: ' . mysql_error());
}
mysql_select_db('mydb');
/* to powinno zwrócić prawidłową liczbę usuniętych rekordów */
mysql_query('DELETE FROM mytable WHERE id < 10');
printf("Usuniętych rekordów: %d\n", mysql_affected_rows());
/* z klauzulą where, która nigdy nie jest prawdziwa, powinno zrwócic 0 */
mysql_query('DELETE FROM mytable WHERE 0');
printf("Usuniętych rekordów: %d\n", mysql_affected_rows());
?>
Powyższy przykład wyświetli coś podobnego do:
Usuniętych rekordów: 10 Usuniętych rekordów: 0
Przykład #2 Przykład mysql_affected_rows() używający transakcję
<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
die('Nie można się połączyć: ' . mysql_error());
}
mysql_select_db('mydb');
/* Uaktualnienie rekordów */
mysql_query("UPDATE mytable SET used=1 WHERE id < 10");
printf ("Zaktualizowanych rekordów: %d\n", mysql_affected_rows());
mysql_query("COMMIT");
?>
Powyższy przykład wyświetli coś podobnego do:
Zaktualizowanych rekordów: 10
Notatki
Informacja: Transakcje
Jeśli używasz transakcji musisz wywołać mysql_affected_rows() po Twoim zapytaniu INSERT, UPDATE lub DELETE, a nie po COMMIT.
Informacja: Instrukcja SELECT
Aby uzyskać liczbę wierszy zwróconych przez SELECT, można użyć use mysql_num_rows().
Informacja: Kaskadowe klucze obce
mysql_affected_rows() nie zwraca liczby wierszy przetworzonych pośrednio przez użycie klauzuli ON DELETE CASCADE i/lub ON UPDATE CASCADE w ograniczeniach kluczy obcych.
Zobacz też:
- mysql_num_rows() - Zwraca liczbę wierszy w wyniku
- mysql_info() - Pobiera informacje o ostatnim zapytaniu
mysql_client_encoding
(PHP 4 >= 4.3.0, PHP 5)
mysql_client_encoding — Zwraca nazwę zestawu znaków
Opis
$identyfikator_połączenia
] )Zwraca zmienną character_set z serwera MySQL.
Parametry
-
identyfikator_połączenia -
Połączenie MySQL. Jeśli identyfikator połączenia nie zostanie podany, użyte zostanie ostatnie połączenie otwarte przez mysql_connect(). Jeśli połączenie takie nie zostanie znalezione, funkcja spróbuje nawiązać połączenie tak, jakby wywołana została funkcja mysql_connect() bez argumentów. Jeśli żadne połączenie nie zostanie znalezione lub nawiązane, wygenerowany zostanie błąd poziomu
E_WARNING.
Zwracane wartości
Zwraca domyślny zestaw znaków dla bieżącego połączenia.
Przykłady
Przykład #1 Przykład użycia mysql_client_encoding()
<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
$charset = mysql_client_encoding($link);
echo "Obecny zestaw znaków to : $charset\n";
?>
Powyższy przykład wyświetli coś podobnego do:
Obecny zestaw znaków to: latin2
Zobacz też:
- mysql_real_escape_string() - Dodaje znaki unikowe w łańcuchu znaków do użycia w instrukcji SQL
mysql_close
(PHP 4, PHP 5)
mysql_close — Zamyka połączenie MySQL
Opis
$identyfikator_połączenia = NULL
] )
mysql_close() zamyka nie stałe połączenie do serwera MySQL,
które zostało skojarzone z podanym identyfikatorem połączenia. Jeśli
identyfikator_połączenia nie został określony, zostanie użyte
ostatnio używane połączenie.
Używanie mysql_close() nie jest zwykle konieczne, ponieważ nie stałe linki są automatycznie zamykane na końcu wykonywania skryptu. Patrz także zwalnianie zasobów.
Parametry
-
link_identifier -
The MySQL connection. If the link identifier is not specified, the last link opened by mysql_connect() is assumed. If no connection is found or established, an
E_WARNINGlevel error is generated.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Przykład mysql_close()
<?php
$link = mysql_connect('localhost', 'użytkownik_mysql', 'hasło_mysql');
if (!$link) {
die('Nie można się połączyć: ' . mysql_error());
}
echo 'Połączono poprawnie';
mysql_close($link);
?>
Powyższy przykład wyświetli:
Połączono poprawnie
Notatki
Informacja:
mysql_close() nie zamknie stałych połączeń stworzonych przez mysql_pconnect().
Zobacz też:
- mysql_connect() - Otwiera połączenie do serwera MySQL
- mysql_free_result() - Zwalnia pamięć zajmowaną przez wynik
mysql_connect
(PHP 4, PHP 5)
mysql_connect — Otwiera połączenie do serwera MySQL
Opis
$serwer = ini_get("mysql.default_host")
[, string $nazwa_użytkownika = ini_get("mysql.default_user")
[, string $hasło = ini_get("mysql.default_password")
[, bool $nowe_połączenie = false
[, int $flagi_klienta = 0
]]]]] )Otwiera lub ponownie używa połączenie do serwera MySQL.
Parametry
-
serwer -
Serwer MySQL. Może także zawierać numer portu np. "nazwa_serwera:port" lub ścieżkę do lokalnego gniazda np. ":/ścieżka/do/gniazda" dla lokalnego hosta.
Jeśli, dyrektywa PHP mysql.default_host jest nie zdefiniowana (domyślnie), wtedy domyślną wartością jest 'localhost:3306'. W tryb bezpieczny SQL, ten parametr jest ignorowany i zawsze jest używana wartość 'localhost:3306'.
-
nazwa_użytkownika -
Nazwa użytkownika. Domyślna watość jest definiowana przez mysql.default_user. W tryb bezpieczny SQL, parametr ten jest ignorowany i używana jest nazwa użytkownika, który jest właścicielem procesu serwera.
-
hasło -
Hasło. Domyślna wartość jest zdefiniowana przez mysql.default_password. W tryb bezpieczny SQL, ten parametr jest ignorowany i użyte jest puste hasło.
-
nowe_połączenie -
Jeśli, ponownie wywołamy mysql_connect() z tymi samymi argumentami, nie zostanie nawiązane nowe połączenie, lecz zamiast tego, zostanie zwrócony identyfikator obecnie otwartego połączenia. Parametr
nowe_połączeniemodyfikuje to zachowanie i sprawia, że mysql_connect() zawsze otwiera nowe połączenie, nawet jeśli mysql_connect() zostało wywołane wcześniej z tymi samymi parametrami. W tryb bezpieczny SQL, ten parametr jest ignorowany. -
flagi_klienta -
Parametr
flagi_klientamoże być kombinacją następujących stałych: 128 (włącza obsługę LOAD DATA LOCAL),MYSQL_CLIENT_SSL,MYSQL_CLIENT_COMPRESS,MYSQL_CLIENT_IGNORE_SPACElubMYSQL_CLIENT_INTERACTIVE. Przeczytaj sekcję o MySQL client constants w celu dalszych informacji. W tryb bezpieczny SQL, ten parametr jest ignorowany.
Zwracane wartości
Zwraca identyfikator połączenia MySQL w przypadku sukcesu, lub FALSE w przypadku niepowodzenia
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.3.0 |
Dodano parametr flagi_klienta.
|
| 4.2.0 |
Dodano parametr nowe_połączenie.
|
Przykłady
Przykład #1 Przykład mysql_connect()
<?php
$link = mysql_connect('localhost', 'użytkownik_mysql', 'hasło_mysql');
if (!$link) {
die('Nie można się połaczyć: ' . mysql_error());
}
echo 'Połączenie nawiązane';
mysql_close($link);
?>
Przykład #2 Przykład mysql_connect() z użyciem składni nazwa_hosta:port
<?php
// połączymy się do example.com i portu 3307
$link = mysql_connect('example.com:3307', 'użytkownik_mysql', 'hasło_mysql');
if (!$link) {
die('Nie można się połączyć: ' . mysql_error());
}
echo 'Połączenie nawiązane';
mysql_close($link);
// połączymy się do localhost na port 3307
$link = mysql_connect('127.0.0.1:3307', 'użytkownik_mysql', 'hasło_mysql');
if (!$link) {
die('Nie można się połączyć: ' . mysql_error());
}
echo 'Połączenie nawiązane';
mysql_close($link);
?>
Przykład #3 mysql_connect() przykład użycia składni ":/ścieżka/do/gniazda"
<?php
// połączymy się do lokalhost i gniazda np. /tmp/mysql.sock
//wariant 1: z pominięciem localhost
$link = mysql_connect(':/tmp/mysql', 'użytkownik_mysql', 'hasło_mysql');
if (!$link) {
die('Nie można się połączyć: ' . mysql_error());
}
echo 'Połączenie nawiązane';
mysql_close($link);
// wariant 2: z localhost
$link = mysql_connect('localhost:/tmp/mysql.sock', 'użytkownik_mysql', 'hasło_mysql');
if (!$link) {
die('Nie można się połączyć: ' . mysql_error());
}
echo 'Połączenie nawiązane';
mysql_close($link);
?>
Notatki
Informacja:
Ilekroć określasz serwer jako "localhost" lub "localhost:port", biblioteka kliencka MySQL nadpisze to i spróbuje połączyć się do lokalnego gniazda (nazwanego potokiem w Windows). Jeśli chcesz użyć TCP/IP, użyj "127.0.0.1" zamiast "localhost". Jeśli biblioteka kliencka MySQL próbuje połączyć się do niewłaściwego lokalnego gniazda, powinieneś ustawić prawidłową ścieżkę jako w Twojej konfiguracji PHP i zostawić puste pole serwer.
Informacja:
Połączenie do serwera zostanie zamknięte jak tylko wykonywanie skryptu zakończy się, chyba, że zostanie wcześniej zamknięte poprzez wyraźne wywołanie mysql_close().
Informacja:
Możesz zapobiec informacją o błędach w przypadku niepowodzenia za pomocą poprzedzenia nazwy funkcji @.
Informacja:
Błąd "Can't create TCP/IP socket (10106)" zwykle oznacza, że dyrektywa konfiguracyjna variables_order nie zawiera znaku E. Pod Windows, jeśli środowisko nie jest skopiowane zmienna środowiskowa SYSTEMROOT nie będzie dostępna i PHP będzie mieć problemy aby załadować Winsock.
Zobacz też:
- mysql_pconnect() - Otwiera stałe połączenie z serwerem MySQL
- mysql_close() - Zamyka połączenie MySQL
mysql_create_db
(PHP 4, PHP 5)
mysql_create_db — Tworzy bazę MySQL
Opis
$nazwa_bazy
[, resource $identyfikator_połączenia
] )mysql_create_db()tworzy nową bazę na serwerze skojarzonym z podanym identyfikatorem połączenia.
Parametry
-
nazwa_bazy -
Nazwa tworzonej bazy danych.
-
identyfikator_połączenia -
Połączenie MySQL. Jeśli identyfikator połączenia nie zostanie podany, użyte zostanie ostatnie połączenie otwarte przez mysql_connect(). Jeśli połączenie takie nie zostanie znalezione, funkcja spróbuje nawiązać połączenie tak, jakby wywołana została funkcja mysql_connect() bez argumentów. Jeśli żadne połączenie nie zostanie znalezione lub nawiązane, wygenerowany zostanie błąd poziomu
E_WARNING.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 mysql_create_db() przykład alternatywny
Stosowanie funkcji mysql_create_db() jest nie zalecane. Sugerowane jest wydawanie polecenia CREATE DATABASE przy użyciu funkcji mysql_query().
<?php
$link = mysql_connect('localhost', 'uzytkownik', 'haslo');
if (!$link) {
die('Nie można się połączyć: ' . mysql_error());
}
$sql = 'CREATE DATABASE my_db';
if (mysql_query($sql, $link)) {
echo "Baza my_db została pomyślnie utworzona\n";
} else {
echo 'Błąd podczas tworzenia bazy: ' . mysql_error() . "\n";
}
?>
Powyższy przykład wyświetli coś podobnego do:
Baza my_db została pomyślnie utworzona
Notatki
Informacja:
Dla zachowania zgodności z poprzednimi wersjami PHP możliwe jest używanie aliasów: mysql_createdb()
Informacja:
Funkcja ta nie będzie dostępna jeśli rozszerzenie MySQL zostało skompilowane z wersją 4.x biblioteki klienta MySQL.
Zobacz też:
- mysql_query() - Wysyła zapytanie do serwera MySQL
- mysql_select_db() - Wybiera bazę MySQL
mysql_data_seek
(PHP 4, PHP 5)
mysql_data_seek — Przesuwa wewnętrzny wskaźnik wyniku
Opis
$wynik
, int $numer_wiersza
)mysql_data_seek() przesuwa wewnętrzny wskaźnik wiersza wyniku operacji MySQL skojarzony z podanym identyfikatorem wyniku na podany numer wiersza. Następne wywołanie MySQLowej funkcji pobierającej, takiej jak mysql_fetch_assoc() zwróci ten wiersz.
row_number zaczyna się od 0. Parametr
row_number powinien być wartością z zakresu od 0 do
mysql_num_rows() - 1. Jednakże jeśli zbiór wyników
jest pusty (mysql_num_rows() == 0), przesunięcie na pozycję 0
zawiedzie i wygeneruje ostrzeżenie
E_WARNING,
mysql_data_seek() zwróci FALSE.
Parametry
-
wynik -
Wynik w postaci zmiennej typu resource, które jest przetwarzane. Wynik ten pochodzi z wywołania funkcji mysql_query().
-
row_number -
Pożądany numer wiersza dla nowego wskaźnika wyniku.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Przykład mysql_data_seek()
<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
die('Nie można się połączyć: ' . mysql_error());
}
$db_selected = mysql_select_db('sample_db');
if (!$db_selected) {
die('Nie można wybrać bazy: ' . mysql_error());
}
$query = 'SELECT last_name, first_name FROM friends';
$result = mysql_query($query);
if (!$result) {
die('Błędne zapytanie: ' . mysql_error());
}
/* pobieramy wiersze w odwrotnej kolejności */
for ($i = mysql_num_rows($result) - 1; $i >=0; $i--) {
if (!mysql_data_seek($result, $i)) {
echo "Nie można przejść do wiersza $i: " . mysql_error() . "\n";
continue;
}
if (!($row = mysql_fetch_assoc($result))) {
continue;
}
echo $row['last_name'] . ' ' . $row['first_name'] . "<br />\n";
}
mysql_free_result($result);
?>
Notatki
Informacja:
Funkcja mysql_data_seek() może być uzyta tylko w połączeniu z mysql_query(), a nie z mysql_unbuffered_query().
Zobacz też:
- mysql_query() - Wysyła zapytanie do serwera MySQL
- mysql_num_rows() - Zwraca liczbę wierszy w wyniku
- mysql_fetch_row() - Zapisuje wiersz wyniku w tablicy wyliczeniowej
- mysql_fetch_assoc() - Zapisuje wiersz wyniku w tablicy asocjacyjnej
- mysql_fetch_array() - Zapisuje wiersz wyniku w tablicy asocjacyjnej, numerycznej lub w obu
- mysql_fetch_object() - Zapisuje wiersz wyniku jako obiekt
mysql_db_name
(PHP 4, PHP 5)
mysql_db_name — Pobiera dane wynikowe
Opis
mysql_db_name() przyjmuje jako pierwszy parametr
wskaźnik wyniku zwrócony przez mysql_list_dbs().
Parametr wiersz działa jako indeks wyniku.
Jeśli wystąpi błąd, zwrócona zostanie wartość FALSE.
Użyj mysql_errno() i
mysql_error() by poznać przyczynę błędu.
Przykład #1 mysql_db_name
<?php
error_reporting(E_ALL);
mysql_connect('localhost', 'uzytkownik', 'haslo');
$db_list = mysql_list_dbs();
$i = 0;
$cnt = mysql_num_rows($db_list);
while ($i < $cnt) {
echo mysql_db_name($db_list, $i) . "\n";
$i++;
}
?>
Aby zachować zgodność z poprzednimi wersjami, można użyć również mysql_dbname().
mysql_db_query
(PHP 4, PHP 5)
mysql_db_query — Wybiera bazę danych MySQL i wykonuje na niej zapytanie
Opis
$baza
, string $zapytanie
[, resource $identyfikator_połączenia
] )mysql_db_query() wybiera bazę i wykonuje na niej zapytanie.
Ta funkcja jest PRZESTARZAŁA od PHP 5.3.0. Używanie tej funkcji nie jest zalecane.
Parametry
-
baza -
Nazwa bazy danych, która zostanie wybrana.
-
zapytanie -
Zapytanie do bazy MySQL.
Dane w zapytaniu powinny być poprzedzone poprawnymi znakami ucieczki.
-
identyfikator_połączenia -
Połączenie MySQL. Jeśli identyfikator połączenia nie zostanie podany, użyte zostanie ostatnie połączenie otwarte przez mysql_connect(). Jeśli połączenie takie nie zostanie znalezione, funkcja spróbuje nawiązać połączenie tak, jakby wywołana została funkcja mysql_connect() bez argumentów. Jeśli żadne połączenie nie zostanie znalezione lub nawiązane, wygenerowany zostanie błąd poziomu
E_WARNING.
Zwracane wartości
Zwraca dodatni identyfikator wyniku MySQL wskazujący na wynik zapytania,
lub FALSE w przypadku błędu. Wartość TRUE/FALSE jest także zwracana dla zapytań
INSERT/UPDATE/DELETE
informując o sukcesie lub błędzie.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.0 | Ta funkcja zwraca wyjątek E_DEPRECATED. |
| 4.0.6 | Nie zaleca się używania tej funkcji. W zamian korzystaj z mysql_select_db() lub mysql_query(). |
Przykłady
Przykład #1 Przykład mysql_db_query()
<?php
if (!$link = mysql_connect('host', 'uzytkownik', 'haslo')) {
echo 'Nie można nawiązać połączenia z bazą danych';
exit;
}
if (!mysql_select_db('nazwa_bazy', $link)) {
echo 'Nie można wybrać bazy danych';
exit;
}
$sql = 'SELECT foo FROM bar WHERE id = 42';
$result = mysql_query($sql, $link);
if (!$result) {
echo "Błąd bazy danych, nie można wykonać zapytania do bazy\n";
echo 'Błąd MySQL: ' . mysql_error();
exit;
}
while ($row = mysql_fetch_assoc($result)) {
echo $row['foo'];
}
mysql_free_result($result);
?>
Notatki
Informacja:
Zwróć uwagę, że ta funkcja NIE wybierze ponownie bazy danych, z którą byłeś połączony wcześniej. Innymi słowy, funkcji tej nie można użyć do wysłania zapytania w tle do innej bazy, w takim przypadku należy ręcznie przełączyć się z powrotem do pierwotnie wybranej bazy. Zamiast tego zaleca się stosowanie składni database.table lub mysql_select_db() w zapytaniach SQL.
Zobacz też:
- mysql_query() - Wysyła zapytanie do serwera MySQL
- mysql_select_db() - Wybiera bazę MySQL
mysql_drop_db
(PHP 4, PHP 5)
mysql_drop_db — Usuwa bazę MySQL
Opis
$nazwa_bazy
[, resource $
identyfikator_połączenia
] )
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
mysql_drop_db() usuwa całą bazę z serwera skojarzonego z podanym identyfikatorem połączenia.
Aby zachować zgodność z poprzednimi wersjami, można użyć również mysql_dropdb(). Jest to jednak niezalecane.
Informacja:
Stosowanie funkcji mysql_drop_db() jest niezalecane. Sugerowane jest wydawanie polecenia DROP DATABASE przy użyciu funkcji mysql_query().
Patrz także: mysql_create_db(), mysql_query().
mysql_errno
(PHP 4, PHP 5)
mysql_errno — Zwraca liczbową wartość kodu błędu z poprzedniej operacji MySQL
Opis
$identyfikator_połączenia
] )Zwraca numer błędu z ostatniej operacji MySQL.
Błędy, zwracane z serwera MySQL, nie powodują generowania ostrzeżeń. Zamiast tego, należy używać funkcji mysql_errno() do pobrania kodu błędu. Funkcja ta zwraca tylko kod błędu, wygenerowany przez ostatnio wywołaną funkcję MySQL (nie licząc mysql_error() i mysql_errno()), a więc kod błędu należy sprawdzać przed wywołaniem kolejnej funkcji MySQL.
Parametry
-
identyfikator_połączenia -
Połączenie MySQL. Jeśli identyfikator połączenia nie zostanie podany, użyte zostanie ostatnie połączenie otwarte przez mysql_connect(). Jeśli połączenie takie nie zostanie znalezione, funkcja spróbuje nawiązać połączenie tak, jakby wywołana została funkcja mysql_connect() bez argumentów. Jeśli żadne połączenie nie zostanie znalezione lub nawiązane, wygenerowany zostanie błąd poziomu
E_WARNING.
Zwracane wartości
Zwraca numer błędu ostatnio wywołanej funkcji MySQL, lub Returns the error number from the last MySQL function, or 0 (zero) jeśli żaden błąd nie wystąpił.
Przykłady
Przykład #1 Przykłady użycia mysql_errno()
<?php
$link = mysql_connect("localhost", "mysql_user", "mysql_password");
if (!mysql_select_db("nieistniejacabaza", $link)) {
echo mysql_errno($link) . ": " . mysql_error($link). "\n";
}
mysql_select_db("kossu", $link);
if (!mysql_query("SELECT * FROM nieistniejacatabela", $link)) {
echo mysql_errno($link) . ": " . mysql_error($link) . "\n";
}
?>
Powyższy przykład wyświetli coś podobnego do:
1049: Unknown database 'nieistniejacabaza' 1146: Table 'kossu.nieistniejacatabela' doesn't exist
Zobacz też:
- mysql_error() - Zwraca tekst komunikatu błędu z ostatniej operacji MySQL
- » Kody błędów MySQL
mysql_error
(PHP 4, PHP 5)
mysql_error — Zwraca tekst komunikatu błędu z ostatniej operacji MySQL
Opis
$
identyfikator_połączenia
] )Zwraca tekst komunikatu błędu z ostatnio użytej funkcji MySQL, lub '' (pusty łańcuch) jeśli wystąpi błąd.
Błędy pochodzące z klienta bazy MySQL już nie powodują wyświetlania ostrzeżeń. Zamiast tego, użyj mysql_error() by uzyskać komunikat błędu. Weź pod uwagę, że ta funkcja zwraca komunikat błędu z ostatnio użytej funkcji MySQL (wyłączając mysql_error() i mysql_errno()), dlatego jeśli jej używasz, upewnij się, by zrobić to przed użyciem następnej funkcji MySQL.
Przykład #1 Przykład użycia mysql_error
<?php
mysql_connect('localhost', 'uzytkownik', 'haslo');
mysql_select_db('niematakiejbazy');
echo mysql_errno() . ": " . mysql_error(). "\n";
mysql_select_db('takiejbazytezniema');
mysql_query('SELECT * FROM niematakiejtabeli');
echo mysql_errno() . ": " . mysql_error() . "\n";
?>
Powyższy przykład da następujący wynik:
1049: Unknown database 'niematakiejbazy' 1146: Table 'takiejbazytezniema.niematakiejtabeli' doesn't exist
Informacja:
Jeżeli jako opcjonalny argument zostanie podany identyfikator połączenia, to zostanie on wykorzystany do wyciągnięcia numeru błędu. Jeśli nie, wykorzystane zostanie ostatnio otwarte połączenie.
Patrz także: mysql_errno()
mysql_escape_string
(PHP 4 >= 4.0.3, PHP 5)
mysql_escape_string — Dodaje znaki unikowe na użytek mysql_query
Opis
$łańcuch_bez_znaków_unikowych
)
Ta funkcja wstawi znaki unikowe do
łańcuch_bez_znaków_unikowych, aby
bezpiecznym było umieszczenie go w mysql_query().
Informacja: mysql_escape_string() nie dotyczy znaków % i _. Funkcja ta działa identycznie jak mysql_real_escape_string(), z tym wyjątkiem, że mysql_real_escape_string() pobiera identyfikator połączenia i wstawia znaki unikowe zgodnie z bieżącym zestawem znaków. mysql_escape_string() nie pobiera identyfikatora połączenia i nie bierze pod uwagę bieżącego zestawu znaków.
Przykład #1 przykład użycia mysql_escape_string()
<?php
$item = "Zak's Laptop";
$escaped_item = mysql_escape_string($item);
printf ("Łańcuch ze znakami unikowymi: %s\n", $escaped_item);
?>
Powyższy przykład da następujący wynik:
Łańcuch ze znakami unikowymi: Zak\'s Laptop
Patrz także: mysql_real_escape_string(), addslashes() oraz dyrektywa magic_quotes_gpc.
mysql_fetch_array
(PHP 4, PHP 5)
mysql_fetch_array — Zapisuje wiersz wyniku w tablicy asocjacyjnej, numerycznej lub w obu
Opis
$wynik
[, int $
typ_wyniku
] )
Zwraca tablicę zawierającą pobrany wiersz, lub
FALSE jeżeli nie ma więcej wierszy w wynik.
mysql_fetch_array() jest rozszerzoną wersją mysql_fetch_row(). Oprócz zapisywania danych w indeksach numerycznych, zapisuje je też w indeksach przyporządkowujących (asocjacyjnych), używając nazw pól jako kluczy.
Jeżeli dwie lub więcej kolumn wyniku ma te same nazwy, ostatnia kolumna będzie brana pod uwagę. Dostęp do innych kolumn o tej samej nazwie jest możliwy jedynie przez indeksowanie numeryczne lub przez stworzenie aliasa. Po stworzeniu aliasa nie można już odwoływać się do danej kolumny używając jej prawdziwej nazwy (w tym przykładzie używając 'pole').
Przykład #1 Zapytanie z powtarzającymi się nazwami pól
select table1.field as foo table2.field as bar from table1, table2
Godne uwagi jest to, że użycie mysql_fetch_array() nie jest znacząco wolniejsze od użycia mysql_fetch_row(), a jest bardziej funkcjonalne.
Opcjonalny drugi argument result_type w
funkcji mysql_fetch_array() jest stałą i może
przyjmować następujące wartości: MYSQL_ASSOC, MYSQL_NUM i MYSQL_BOTH.
Tę funkcjonalność dodano w PHP 3.0.7. Wartością domyślną jest MYSQL_BOTH.
Używając MYSQL_BOTH otrzymasz tablicę indeksowaną zarówno asocjacyjnie jak i numerycznie. MYSQL_ASSOC dostarczy tablicy indeksowanej tylko asocjacyjnie (jak w mysql_fetch_assoc()), natomiast MYSQL_NUM indeksowanej tylko numerycznie (jak w mysql_fetch_row()).
Przykład #2 mysql_fetch_array z MYSQL_NUM
<?php
mysql_connect('localhost', 'uzytkownik', 'haslo') or
die('Nie można się połączyć: ' . mysql_error());
mysql_select_db('baza');
$result = mysql_query("SELECT id, nazwa FROM tabela");
while ($row = mysql_fetch_array($result, MYSQL_NUM)) {
printf ("ID: %s Nazwa: %s", $row[0], $row[1]);
}
mysql_free_result($result);
?>
Przykład #3 mysql_fetch_array z MYSQL_ASSOC
<?php
mysql_connect('localhost', 'uzytkownik', 'haslo') or
die('Nie można się połączyć: ' . mysql_error());
mysql_select_db('baza');
$result = mysql_query("SELECT id, nazwa FROM tabela");
while ($row = mysql_fetch_array($result, MYSQL_ASSOC)) {
printf ("ID: %s Nazwa: %s", $row["id"], $row["nazwa"]);
}
mysql_free_result($result);
?>
Przykład #4 mysql_fetch_array z MYSQL_BOTH
<?php
mysql_connect('localhost', 'uzytkownik', 'haslo') or
die('Nie można się połączyć: ' . mysql_error());
mysql_select_db('baza');
$result = mysql_query("SELECT id, nazwa FROM tabela");
while ($row = mysql_fetch_array($result, MYSQL_BOTH)) {
printf ("ID: %s Nazwa: %s", $row[0], $row["nazwa"]);
}
mysql_free_result($result);
?>
Patrz także: mysql_fetch_row(), mysql_fetch_assoc().
mysql_fetch_assoc
(PHP 4 >= 4.0.3, PHP 5)
mysql_fetch_assoc — Zapisuje wiersz wyniku w tablicy asocjacyjnej
Opis
$wynik
)
Zwraca tablicę zawierającą pobrany wiersz, lub
FALSE jeżeli nie ma więcej wierszy w wynik.
Użycie mysql_fetch_assoc() jest równoznaczne z wywołaniem mysql_fetch_array() podając jako drugi argument MYSQL_ASSOC. Zwraca jedynie tablicę asocjacyjną. Początkowo tak właśnie zachowywała się funkcja mysql_fetch_array(). Jeśli oprócz indeksowania asocjacyjnego potrzebujesz także numeryczne, użyj funkcji mysql_fetch_array().
Jeżeli dwie lub więcej kolumn wyniku ma te same nazwy, ostatnia kolumna będzie brana pod uwagę. Dostęp do innych kolumn o tej samej nazwie jest możliwy przy użyciu funkcji mysql_fetch_array(), która wprowadzi również indeksowanie numeryczne.
Godne uwagi jest to, że użycie mysql_fetch_assoc() nie jest znacząco wolniejsze od użycia mysql_fetch_row(), a jest bardziej funkcjonalne.
Przykład #1 mysql_fetch_assoc()
<?php
mysql_connect('localhost','uzytkownik','haslo');
mysql_select_db('baza');
$result = mysql_query('select * from tabela');
while ($row = mysql_fetch_assoc($result)) {
echo $row["id_uzytkownika"];
echo $row["pelna_nazwa"];
}
mysql_free_result($result);
?>
Patrz także: mysql_fetch_row(), mysql_fetch_array() i mysql_query().
mysql_fetch_field
(PHP 4, PHP 5)
mysql_fetch_field — Pobiera z wyniku informacje o kolumnie i zwraca jako obiekt
Opis
$wynik
[, int $
ofset_pola
] )Zwraca obiekt zawierający informacje o polu.
mysql_fetch_field() pozwala uzyskać informacje o polach w danym wyniku zapytania. Jeżeli ofset pola nie został podany, zwracane zostanie następne pole nie pobrane jeszcze przez mysql_fetch_field().
Właściwości obiektu:
- name - nazwa kolumny
- table - nazwa tabeli do której należy kolumna
- max_length - maksymalna długość kolumny
-
not_null - 1 jeżeli pole nie może być puste (
NULL) - primary_key - 1 jeżeli kolumna jest kluczem podstawowym
- unique_key - 1 jeżeli kolumna jest kluczem unikatowym
- multiple_key - 1 jeżeli kolumna jest kluczem nieunikatowym
- numeric - 1 jeżeli kolumna jest liczbowa
- blob - 1 jeżeli kolumna jest typu BLOOB
- type - typ kolumny
- unsigned - 1 jeżeli kolumna jest bez znaku (plus lub minus)
- zerofill - 1 jeżeli kolumna jest wypełniona zerami
Przykład #1 mysql_fetch_field()
<?php
mysql_connect('localhost','uzytkownik','haslo');
or die ('Nie można się połączyć');
mysql_select_db('baza');
$result = mysql_query('select * from tabela')
or die('Zapytanie zakończone niepowodzeniem');
/* pobieramy dane kolumny */
$i = 0;
while ($i < mysql_num_fields($result)) {
echo "Informacje o kolumnie $i:<br />\n";
$meta = mysql_fetch_field($result);
if (!$meta) {
echo "Informacje niedostępne<br />\n";
}
echo "<pre>
blob: $meta->blob
max_length: $meta->max_length
multiple_key: $meta->multiple_key
name: $meta->name
not_null: $meta->not_null
numeric: $meta->numeric
primary_key: $meta->primary_key
table: $meta->table
type: $meta->type
unique_key: $meta->unique_key
unsigned: $meta->unsigned
zerofill: $meta->zerofill
</pre>";
$i++;
}
mysql_free_result($result);
?>
Patrz także: mysql_field_seek().
mysql_fetch_lengths
(PHP 4, PHP 5)
mysql_fetch_lengths — Pobiera długość każdego pola w wierszu wyniku
Opis
$wynik
)
Zwraca tablicę zawierającą długość każdego pola z wiersza
ostatnio pobranego przez mysql_fetch_row(),
lub FALSE, jeżeli wystąpi błąd.
mysql_fetch_lengths() zapisuje w tablicy długości wszystkich pól z ostatniego wiersza pobranego przez funkcje mysql_fetch_row(), mysql_fetch_array() i mysql_fetch_object() zaczynając od ofsetu 0.
Patrz także: mysql_fetch_row().
mysql_fetch_object
(PHP 4, PHP 5)
mysql_fetch_object — Zapisuje wiersz wyniku jako obiekt
Opis
$wynik
)
Zwraca: obiekt, którego właściwości zawierają pobrany wiersz,
lub FALSE, jeżeli nie ma więcej wierszy.
Funkcja mysql_fetch_object() jest podobna do mysql_fetch_array() z jedną różnicą - zamiast tablicy zwracany jest obiekt. Oczywiście oznacza to, że dane dostępne są tylko przez podanie nazw pól, a nie przed podanie ofsetu (liczby nie są dopuszczalne jako nazwy właściwości).
<?php
/* poprawnie */
echo $wiersz->pole;
/* niepoprawnie */
echo $wiersz->0;
?>
Szybkość tej funkcji jest identyczna jak mysql_fetch_array() i prawie taka sama jak mysql_fetch_row() (różnica jest nieznaczna).
Przykład #1 mysql_fetch_object()
<?php
mysql_connect('localhost','uzytkownik','haslo');
mysql_select_db($db);
$result = mysql_query('select * from tabela');
while ($row = mysql_fetch_object($result)) {
echo $row->id_uzytkownika;
echo $row->pelna_nazwa;
}
mysql_free_result($result);
?>
Patrz także: mysql_fetch_array() i mysql_fetch_row().
mysql_fetch_row
(PHP 4, PHP 5)
mysql_fetch_row — Zapisuje wiersz wyniku w tablicy wyliczeniowej
Opis
$wynik
)Zwraca tablicę numeryczną, która odpowiada pobranemu wierszowi i przesuwa do przodu wewnętrzny wskaźnik danych.
Parametry
-
wynik -
Wynik w postaci zmiennej typu resource, które jest przetwarzane. Wynik ten pochodzi z wywołania funkcji mysql_query().
Zwracane wartości
Zwraca tablicę numeryczną, która odpowiada pobranemu wierszowi, lub
FALSE jeśli nie ma więcej wierszy.
mysql_fetch_row() pobiera jeden wiersz danych z wyniku skojarzonego z podanym identyfikatorem wyniku. Wiersz zwracany jest jako tablica. Komórki są umieszczone pod oddzielnymi ofsetami, zaczynając od 0.
Przykłady
Przykład #1 Pobieranie jednego wiersza za pomocą mysql_fetch_row()
<?php
$result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
if (!$result) {
echo 'Nie można uruchomić zapytania: ' . mysql_error();
exit;
}
$row = mysql_fetch_row($result);
echo $row[0]; // 42
echo $row[1]; // wartość kolumny email
?>
Notatki
Informacja: Ta funkcja ustala wartość pól NULL na
NULL.
Zobacz też:
- mysql_fetch_array() - Zapisuje wiersz wyniku w tablicy asocjacyjnej, numerycznej lub w obu
- mysql_fetch_assoc() - Zapisuje wiersz wyniku w tablicy asocjacyjnej
- mysql_fetch_object() - Zapisuje wiersz wyniku jako obiekt
- mysql_data_seek() - Przesuwa wewnętrzny wskaźnik wyniku
- mysql_fetch_lengths() - Pobiera długość każdego pola w wierszu wyniku
- mysql_result() - Zwraca dane wynikowe
mysql_field_flags
(PHP 4, PHP 5)
mysql_field_flags — Pobiera flagi dla danego pola w wyniku
Opis
$wynik
, int $ofset_pola
)mysql_field_flags() zwraca flagi podanego pola. Flagi są przedstawiane jako pojedyncze słowa oddzielone spacją tak, by można było je rodzielić za pomocą funkcji explode().
Następujące flagi są przedstawiane jeżeli wersja MySQLa jest na tyle aktualna by je obsłużyć: "not_null", "primary_key", "unique_key", "multiple_key", "blob", "unsigned", "zerofill", "binary", "enum", "auto_increment", "timestamp".
Aby zachować zgodność z poprzednimi wersjami, można użyć również mysql_fieldflags(). Jest to jednak niezalecane.
mysql_field_len
(PHP 4, PHP 5)
mysql_field_len — Zwraca długość danego pola
Opis
$wynik
, int $ofset_pola
)mysql_field_len() zwraca długość danego pola.
Aby zachować zgodność z poprzednimi wersjami, można użyć również mysql_fieldlen(). Jest to jednak niezalecane.
mysql_field_name
(PHP 4, PHP 5)
mysql_field_name — Podaje nazwę danego pola w wyniku
Opis
$wynik
, int $indeks_pola
)
mysql_field_name() zwraca nazwę danego pola.
wynik musi być poprawnym identyfikatorem
wyniku, a indeks_pola powinien zawierać
liczbowy indeks pola.
Informacja:
indeks_polaliczy się od 0.Indeksem trzeciego pola będzie liczba 2, czwartego 3 i tak dalej...
Przykład #1 mysql_field_name()
<?php
/* Tabela składa się z trzech pól:
* id_uzytkownika
* nazwa_uzytkownika
* haslo
*/
$link = mysql_connect('localhost', 'uzytkownik', 'haslo');
mysql_select_db($dbname, $link)
or die("Nie można otworzyć bazy $dbname");
$res = mysql_query("select * from users", $link);
echo mysql_field_name($res, 0) . "\n";
echo mysql_field_name($res, 2);
?>
Powyższy przykład da następujący wynik:
id_uzytkownika haslo
Aby zachować zgodność z poprzednimi wersjami, można użyć również mysql_fieldname(). Jest to jednak niezalecane.
mysql_field_seek
(PHP 4, PHP 5)
mysql_field_seek — Przesuwa wskaźnik wyniku do wybranego pola
Opis
$wynik
, int $ofset_pola
)Przesuwa się na wybrane pole. Jeżeli kolejne wywołanie mysql_fetch_field() nie będzie zawierać indeksu pola, wtedy zwrócone zostanie to pole.
Patrz także: mysql_fetch_field().
mysql_field_table
(PHP 4, PHP 5)
mysql_field_table — Pobiera nazwę tabeli w której znajduje się dane pole
Opis
$wynik
, int $ofset_pola
)Zwraca nazwę tabeli w której znajduje się dane pole.
Parametry
-
wynik -
Wynik w postaci zmiennej typu resource, które jest przetwarzane. Wynik ten pochodzi z wywołania funkcji mysql_query().
-
przesunięcie_pola -
Liczbowe przesunięcie pola.
przesunięcie_polazaczyna się od wartości 0. Jeśliprzesunięcie_polanie istnieje, wygenerowane zostanie ostrzeżenie poziomuE_WARNING.
Zwracane wartości
Zwraca nazwę tabeli w przypadku powodzenia.
Przykłady
Przykład #1 Przykład użycia mysql_field_table()
<?php
$query = "SELECT konto.*, panstwo.* FROM konto, panstwo WHERE konto.nazwa = 'Polska' AND konto.panstwo_id = panstwo.id";
// Pobiera wynik z bazy danych
$result = mysql_query($query);
// Wyświetla nazwę tablicy, a następnie nazwę pola
for ($i = 0; $i < mysql_num_fields($result); ++$i) {
$table = mysql_field_table($result, $i);
$field = mysql_field_name($result, $i);
echo "$table: $field\n";
}
?>
Notatki
Informacja:
Dla zachowania zgodności z poprzednimi wersjami PHP możliwe jest używanie aliasów: mysql_fieldtable()
mysql_field_type
(PHP 4, PHP 5)
mysql_field_type — Pobiera typ podanego pola
Opis
$wynik
, int $ofset_pola
)Funkcja mysql_field_type() jest podobna do mysql_field_name(). Argumenty są identyczne, ale zwracany jest typ pola. Będzie to jeden z "int", "real", "string", "blob" lub innych opisanych w dokumentacji » MySQL.
Przykład #1 Typy pól MySQL
<?php
mysql_connect('localhost','uzytkownik','haslo');
mysql_select_db('baza');
$result = mysql_query('SELECT * FROM tabela');
$fields = mysql_num_fields($result);
$rows = mysql_num_rows($result);
$table = mysql_field_table($result, 0);
echo "Tabela '".$table."' ma ".$fields." pól i ".$rows." wierszy\n";
echo "Tabela ma następujące pola:\n";
for ($i=0; $i < $fields; $i++) {
$type = mysql_field_type($result, $i);
$name = mysql_field_name($result, $i);
$len = mysql_field_len($result, $i);
$flags = mysql_field_flags($result, $i);
echo $type." ".$name." ".$len." ".$flags."\n";
$i++;
}
mysql_free_result($result);
mysql_close();
?>
Powyższy przykład da następujący wynik:
Tabela 'tabela' ma 4 pól i 1 wierszy Tabela ma następujące pola: string name 64 not_null primary_key binary int ret 1 not_null string dl 128 not_null string type 9 not_null enum
Aby zachować zgodność z poprzednimi wersjami, można użyć również mysql_fieldtype(). Jest to jednak niezalecane.
mysql_free_result
(PHP 4, PHP 5)
mysql_free_result — Zwalnia pamięć zajmowaną przez wynik
Opis
$wynik
)mysql_free_result() zwolni całą pamięć przydzieloną podanemu wskaźnikowi wyniku.
mysql_free_result() używa się tylko w wypadkach obawy zajęcia zbyt dużej ilości pamięci przez zapytania zwracające duże ilości danych. Cała pamięć przydzielona wynikowi skojarzonemu z podanym identyfikatorem wyniku będzie automatycznie zwolniona.
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Aby zachować zgodność z poprzednimi wersjami, można użyć również mysql_freeresult(). Jest to jednak niezalecane.
mysql_get_client_info
(PHP 4 >= 4.0.5, PHP 5)
mysql_get_client_info — Pobiera informacje o kliencie MySQL
Opis
mysql_get_client_info() zwraca ciąg znaków zawierający wersję bibliotek klienta MySQL.
Przykład #1 mysql_get_client_info
<?php
printf ("MySQL client info: %s\n", mysql_get_client_info());
?>
Powyższy przykład da następujący wynik:
MySQL client info: 3.23.39
Patrz także: mysql_get_host_info(), mysql_get_proto_info() i mysql_get_server_info().
mysql_get_host_info
(PHP 4 >= 4.0.5, PHP 5)
mysql_get_host_info — Pobiera informacje o hoście MySQL
Opis
$identyfikator_połączenia
] )
mysql_get_host_info() zwraca ciąg znaków opisujący
typ połączenia wykorzystywany przez
identyfikator_połączenia, włączając to nazwę
serwera. Jeżeli
identyfikator_połączenia nie zostanie podany,
wykorzystane zostanie ostatnio otwarte połączenie.
Przykład #1 mysql_get_host_info
<?php
mysql_connect('localhost', 'uzytkownik', 'haslo') or
die('Nie można się połączyć');
printf ("MySQL host info: %s\n", mysql_get_host_info());
?>
Powyższy przykład da następujący wynik:
MySQL host info: Localhost via UNIX socket
Patrz także: mysql_get_client_info(), mysql_get_proto_info() i mysql_get_server_info().
mysql_get_proto_info
(PHP 4 >= 4.0.5, PHP 5)
mysql_get_proto_info — Pobiera informacje o protokole MySQL
Opis
$identyfikator_połączenia
] )
mysql_get_proto_info() zwraca wersję protokołu,
używanego przez
identyfikator_połączenia. Jeżeli
identyfikator_połączenia nie zostanie podany,
wykorzystane zostanie ostatnio otwarte połączenie.
Przykład #1 mysql_get_proto_info
<?php
mysql_connect('localhost', 'uzytkownik', 'haslo') or
die('Nie można się połączyć');
printf ("MySQL protocol version: %s\n", mysql_get_proto_info());
?>
Powyższy przykład da następujący wynik:
MySQL protocol version : 10
Patrz także: mysql_get_client_info(), mysql_get_host_info() i mysql_get_server_info().
mysql_get_server_info
(PHP 4 >= 4.0.5, PHP 5)
mysql_get_server_info — Pobiera informacje o serwerze MySQL
Opis
$identyfikator_połączenia
] )
mysql_get_server_info() zwraca wersję serwera,
używanego przez
identyfikator_połączenia. Jeżeli
identyfikator_połączenia nie zostanie podany,
wykorzystane zostanie ostatnio otwarte połączenie.
mysql_get_server_info() dodano w PHP 4.0.5.
Przykład #1 mysql_get_server_info
<?php
mysql_connect('localhost', 'uzytkownik', 'haslo') or
die('Nie można się połączyć');
printf ("MySQL server version: %s\n", mysql_get_server_info());
?>
Powyższy przykład da następujący wynik:
MySQL server version: 4.0.1-alpha
Patrz także: mysql_get_client_info(), mysql_get_host_info() i mysql_get_proto_info().
mysql_info
(PHP 4 >= 4.3.0, PHP 5)
mysql_info — Pobiera informacje o ostatnim zapytaniu
Opis
$
identyfikator_połączenia
] )
mysql_info() zwraca szczegółowe informacje o ostatnim
zapytaniu wykonanym przy użyciu podanego identyfikatora_połączenia.
Jeśli identyfikator_połączenia nie zostanie podany,
domyślnie przyjmowane jest ostatnio otwarte połączenie.
mysql_info() zwraca wartość typu string
dla poleceń wymienionych poniżej. Dla wszystkich innych zwracana jest
wartość FALSE. Format zwracanej wartości zależy od polecenia.
Przykład #1 Formaty zwracanych wartości
INSERT INTO ... SELECT ... String format: Records: 23 Duplicates: 0 Warnings: 0 INSERT INTO ... VALUES (...),(...),(...)... String format: Records: 37 Duplicates: 0 Warnings: 0 LOAD DATA INFILE ... String format: Records: 42 Deleted: 0 Skipped: 0 Warnings: 0 ALTER TABLE String format: Records: 60 Duplicates: 0 Warnings: 0 UPDATE String format: Rows matched: 65 Changed: 65 Warnings: 0
Informacja:
Dla poleceń typu INSERT ... VALUES, mysql_info() zwraca wartość różną od
FALSE, tylko jeśli w zapytaniu podanych zostało kilka wartości.
Patrz także: mysql_affected_rows()
mysql_insert_id
(PHP 4, PHP 5)
mysql_insert_id — Podaje numer ID wygenerowany podczas ostatniej operacji INSERT
Opis
$
identyfikator_połączenia
] )
mysql_insert_id() zwraca ID wygenerowane dla
pola z własnością AUTO_INCREMENT. Funkcja zwróci ID wygenerowane
automatycznie przez ostatnią operację INSERT używającą podanego
identyfikatora_połączenia. Jeżeli
identyfikator_połączenia nie został podany,
wykorzystywane jest ostatnio otwarte połączenie.
mysql_insert_id() zwróci 0 jeśli ostatnie zapytanie nie generowało wartości AUTO_INCREMENT. Jeśli chcesz przechować zwrócony przez tę funkcję wynik, upewnij się, że wywołujesz ją zaraz po zapytaniu generującym nową wartość.
Informacja:
Funkcja MySQL LAST_INSERT_ID() zawsze zawiera ostatnio wygenerowane ID, a zwracana wartośc nie jest czyszczona pomiędzy kolejnymi zapytaniami.
mysql_insert_id() konwertuje typ wartości otrzymanej od natywnej funkcji MySQL C API mysql_insert_id() na typ long (czyli int w PHP). Jeśli kolumna AUTO_INCREMENT jest typu BIGINT, wartość zwracana przez mysql_insert_id() będzie niepoprawna. Należy w zapytaniu SQL użyć wewnętrznej funkcji MySQL LAST_INSERT_ID().
Przykład #1 Przykład użycia mysql_insert_id
<?php
mysql_connect('localhost', 'uzytkownik', 'haslo') or
die('Nie można się połączyć');
mysql_select_db('baza');
mysql_query("INSERT INTO mytable (product) values ('kossu')");
printf ("Ostatnio dodany rekord ma id %d\n", mysql_insert_id());
?>
Patrz także: mysql_query().
mysql_list_dbs
(PHP 4, PHP 5)
mysql_list_dbs — Pobiera nazwy baz dostępnych na serwerze MySQL
Opis
$
identyfikator_połączenia
] )mysql_list_dbs() zwróci wynik zawierający nazwy baz dostępnych na serwerze skojarzonym z identyfikatorem połączenia. Żeby uzyskać nazwy za wskaźnika wyniku należy użyć funkcji mysql_tablename() lub innej operującej na tablicach wyników.
Przykład #1 mysql_list_dbs()
<?php
$link = mysql_connect ('localhost','uzytkownik','haslo');
$db_list = mysql_list_dbs($link);
while ($row = mysql_fetch_object($db_list)) {
echo $row->Database . "\n";
}
?>
Powyższy przykład da następujący wynik:
baza1 baza2 baza3 ...
Informacja:
Powyższy kod będzie równie dobrze działał z funkcją mysql_fetch_row() lub innymi podobnymi.
Aby zachować zgodność z poprzednimi wersjami, można użyć również mysql_listdbs(). Jest to jednak niezalecane.
Patrz także: mysql_db_name().
mysql_list_fields
(PHP 4, PHP 5)
mysql_list_fields — Pobiera informacje o polach tabeli MySQL
Opis
$baza
, string $tabela
[, resource $
identyfikator_połączenia
] )mysql_list_fields() pobiera informacje o danej tabeli. Argumentami są nazwa bazy i nazwa tabeli. Zwracany jest wskaźnik wyniku, który może zostać użyty z funkcjami mysql_field_flags(), mysql_field_len(), mysql_field_name() i mysql_field_type().
Przykład #1 mysql_list_fields()
<?php
$link = mysql_connect ('localhost','uzytkownik','haslo');
$fields = mysql_list_fields('baza', 'tabela', $link);
$columns = mysql_num_fields($fields);
for ($i = 0; $i < $columns; $i++) {
echo mysql_field_name($fields, $i) . "\n";
}
?>
Powyższy przykład da następujący wynik:
pole1 pole2 pole3 ...
Aby zachować zgodność z poprzednimi wersjami, można użyć również mysql_listfields(). Jest to jednak niezalecane.
mysql_list_processes
(PHP 4 >= 4.3.0, PHP 5)
mysql_list_processes — Zwraca listę procesów MySQL
Opis
$
identyfikator_połączenia
] )mysql_list_processes() zwraca wskaźnik wyniku zawierającego opis aktualnych wątków serwera.
Przykład #1 przykład użycia mysql_list_processes()
<?php
$link = mysql_connect('localhost', 'uzytkownik', 'haslo');
$result = mysql_list_processes($link);
while ($row = mysql_fetch_row($result)){
printf("%s %s %s %s %s\n", $row["Id"], $row["Host"], $row["db"],
$row["Command"], $row["Time"]);
}
mysql_free_result ($result);
?>
Powyższy przykład da następujący wynik:
1 localhost test Processlist 0 4 localhost mysql sleep 5
Patrz także: mysql_thread_id()
mysql_list_tables
(PHP 4, PHP 5)
mysql_list_tables — Pobiera listę tabel z bazy MySQL
Opis
$baza
[, resource $
identyfikator_połączenia
] )mysql_list_tables() przyjmuje jako argument nazwę bazy i zwraca wskaźnik wyniku podobnie jak funkcja mysql_query(). Żeby uzyskać nazwy tabel za wskaźnika wyniku należy użyć funkcji mysql_tablename() lub innej operującej na tablicach wyników.
Aby zachować zgodność z poprzednimi wersjami, można użyć również mysql_listtables(). Jest to jednak niezalecane.
Przykład #1 Przykład użycia mysql_list_tables
<?php
mysql_connect('localhost', 'uzytkownik', 'haslo') or
die('Nie można się połączyć');
mysql_select_db('baza');
$result = mysql_list_tables();
while (($row = mysql_fetch_row($result))
printf ("Tabela: %s\n", $row[0]);
mysql_free_result($result);
?>
Patrz także: mysql_list_dbs(), mysql_tablename().
mysql_num_fields
(PHP 4, PHP 5)
mysql_num_fields — Zwraca liczbę pól w wyniku
Opis
$wynik
)mysql_num_fields() zwraca liczbę pól w wyniku.
Patrz także: mysql_select_db(), mysql_query(), mysql_fetch_field(), mysql_num_rows().
Aby zachować zgodność z poprzednimi wersjami, można użyć również mysql_numfields().
mysql_num_rows
(PHP 4, PHP 5)
mysql_num_rows — Zwraca liczbę wierszy w wyniku
Opis
$wynik
)mysql_num_rows() zwraca liczbę wierszy w wyniku. Tę funkcję stosuje się tylko do operacji SELECT. Aby pobrać ilość wierszy przetworzonych w operacjach INSERT, UPDATE lub DELETE należy użyć funkcji mysql_affected_rows().
Przykład #1 mysql_num_rows()
<?php
$link = mysql_connect ('serwer','uzytkownik','haslo');
mysql_select_db('baza', $link);
$result = mysql_query('SELECT * FROM tabela', $link);
$num_rows = mysql_num_rows($result);
echo "$num_rows wierszy\n";
?>
Informacja:
Jeśli funkcja mysql_num_rows() jest używana w połączeniu z mysql_unbuffered_query(), poprawna wartość zostanie zwrócona dopiero po odebraniu wszystkich wierszy wyniku.
Patrz także: mysql_affected_rows(), mysql_connect(), mysql_data_seek(), mysql_select_db() i mysql_query().
Aby zachować zgodność z poprzednimi wersjami, można użyć również mysql_numrows(). Jest to jednak niezalecane.
mysql_pconnect
(PHP 4, PHP 5)
mysql_pconnect — Otwiera stałe połączenie z serwerem MySQL
Opis
$
serwer
[, string $użytkownik
[, string $hasło
]]] )
Zwraca identyfikator połączenia w przypadku powodzenia, lub
FALSE jeśli wystąpi błąd.
mysql_connect() nawiązuje połączenie z serwerem
MySQL. Jeśli nie podano argumentów, przyjmowane są następujące
wartości domyślne: host:port =
'localhost:3306', użytkownik = nazwa użytkownika
będącego właścicielem procesu serwera, hasło =
puste hasło.
Argument host może również zawierać
numer portu, np. "host:port" lub ścieżkę do gniaza np.
":/sciezka/do/gniazda" dla localhosta.
Informacja:
Obsługę ":port" dodano w PHP 3.0B4.
Obsługę ":/sciezka/do/gniazda" dodano w PHP 3.0.10.
mysql_pconnect() zachowuje się prawie jak mysql_connect() z dwoma zasadniczymi różnicami.
Pierwsza, podczas łączenia funkcja najpierw spróbuje znaleźć połączenie (stałe) już otwarte dla tego samego hosta, użytkownika i hasła. Jeżeli je znajdzie, jego identyfikator zostanie zwrócony zamiast otwierania nowego połączenia.
Druga, połączenie z serwerem SQL nie zostanie zamknięte po zakończeniu wykonywania skryptu. Zamiast tego połączenie pozostanie otwarte do późniejszego użycia (mysql_close() nie zamyka połączeń nawiązanych za pomocą mysql_pconnect()).
Dlatego też ten typ połączeń nazywany jest 'stałym'.
Informacja:
Trzeba zaznaczyć, że stałe połączenia działają jedynie z PHP pracującym jako moduł. Przeczytaj rozdział Stałe połączenia z bazami danych by dowiedzieć się więcej.
Używanie stałych połączeń może wymagać dostrojenia konfiguracji Apache'a i MySQLa, aby nie przekroczyć limitu jednoczesnych połączeń dozwolonych przez MySQL.
mysql_ping
(PHP 4 >= 4.3.0, PHP 5)
mysql_ping — Sprawdza połączenie z serwerem, lub nawiązuje połączenie, jeśli go nie było
Opis
$identyfikator_połączenia
] )Sprawdza czy połączenie z serwerem działa poprawnie. Jeśli zostało zamknięte, następuje próba ponownego połączenia. Funkcja ta, w skryptach które pozostają długi czas w bezczynności, może służyć do sprawdzenia czy serwer zamknął połączenie i, jeśli zajdzie potrzeba, nawiązania go ponownie.
Informacja:
Od wersji MySQL 5.0.13 automatyczne ponawianie połączenia jest wyłączone.
Parametry
-
identyfikator_połączenia -
Połączenie MySQL. Jeśli identyfikator połączenia nie zostanie podany, użyte zostanie ostatnie połączenie otwarte przez mysql_connect(). Jeśli połączenie takie nie zostanie znalezione, funkcja spróbuje nawiązać połączenie tak, jakby wywołana została funkcja mysql_connect() bez argumentów. Jeśli żadne połączenie nie zostanie znalezione lub nawiązane, wygenerowany zostanie błąd poziomu
E_WARNING.
Zwracane wartości
Zwraca TRUE jeśli połączenie z serwerem działa poprawnie, w przeciwnym
przypadku zwraca FALSE.
Przykłady
Przykład #1 Przykład użycia mysql_ping()
<?php
set_time_limit(0);
$conn = mysql_connect('localhost', 'mysqluser', 'mypass');
$db = mysql_select_db('mydb');
/* Zakładamy, że wykonanie zapytania zajmie dużo czasu */
$result = mysql_query($sql);
if (!$result) {
echo 'Wykonanie zapytania #1 nie powiodło się, zamykanie.';
exit;
}
/* Upewniamy się, że połączenie jest aktywne, w przeciwnym wypadku ponawiamy je */
if (!mysql_ping($conn)) {
echo 'Połączenie zerwane, zamykanie po zapytaniu #1';
exit;
}
mysql_free_result($result);
/* Jeśli połączenie jest aktywne wykonujemy następne zapytanie */
$result2 = mysql_query($sql2);
?>
Zobacz też:
- mysql_thread_id() - Zwraca id bieżącego wątku
- mysql_list_processes() - Zwraca listę procesów MySQL
mysql_query
(PHP 4, PHP 5)
mysql_query — Wysyła zapytanie do serwera MySQL
Opis
$zapytanie
[, resource $identyfikator_połączenia
[, int $typ_wyniku
]] )
mysql_query() wysyła zapytanie do aktywnej
bazy na serwerze skojarzonym z podanym identyfikatorem połączenia.
Jeżeli identyfikator_połączenia nie został podany,
wykorzystywane jest ostatnio otwarte połączenie. Jeżeli żadne
połączenie nie jest otwarte, podjęta zostanie próba ustanowienia
go, poprzez wywołanie mysql_connect() bez argumentów.
Opcjonalny argument result_mode może przyjmować
wartość MYSQL_USE_RESULT lub MYSQL_STORE_RESULT. Domyślnie używana jest
wartość MYSQL_STORE_RESULT, zatem wynik jest buforowany. Odpowiednikiem
użycia drugiej opcji jest funkcja mysql_unbuffered_query().
Informacja:
Zapytanie nie powinno kończyć się znakiem średnika.
mysql_query() zwraca identyfikator wyniku (lub FALSE
w przypadku niepowodzenia) jedynie dla zapytań typu SELECT, SHOW, EXPLAIN
i DESCRIBE.
Dla innych zapytań SQL mysql_query() zwraca TRUE
lub FALSE informując czy zapytanie zakończyło się sukcesem czy też nie.
Jeśli nie została zwrócona wartość FALSE to znaczy, że zapytanie było
prawidłowe i może być wykonane przez serwer. Nie mówi natomiast nic o
liczbie przetworzonych lub zwróconych wierszy. Jest również możliwe, że
zapytanie zostanie wykonane poprawnie, nie przetwarzając lub
zwracając żadnych wierszy.
Następujące zapytanie jest niepoprawne składniowo, dlatego
mysql_query() zwróci FALSE:
Przykład #1 mysql_query()
<?php
$result = mysql_query("SELECT * WHERE 1=1")
or die("Zapytanie niepoprawne");
?>
Następujące zapytanie jest niepoprawne semantycznie, jeżeli
my_col nie jest kolumną w tabeli
my_tbl, dlatego mysql_query()
zwróci FALSE:
Przykład #2 mysql_query()
<?php
$result = mysql_query("SELECT kolumna FROM tabela")
or die("Zapytanie niepoprawne");
?>
mysql_query() zwróci FALSE również wtedy, gdy
nie będzie praw dostępu do tabel wyszczególnionych w zapytaniu.
Przyjmując, że zapytanie się powiodło, można użyć mysql_num_rows() by uzyskać informację o liczbie wierszy zwróconych w instrukcji SELECT, lub mysql_affected_rows() w celu uzyskania liczby wierszy przetworzonych przez instrukcje DELETE, INSERT, REPLACE i UPDATE.
Jedynie po operacjach SELECT, SHOW, EXPLAIN i DESCRIBE mysql_query() zwróci identyfikator wyniku, który można przekazać do funkcji mysql_fetch_array() lub innych funkcji operujących na tablicach wyników. Po wykonaniu operacji na wyniku, można zwolnić zasoby przez niego wykorzystywane wywołując mysql_free_result(). Po zakończeniu działania skryptu pamięć i tak będzie automatycznie zwolniona.
Patrz także: mysql_num_rows(), mysql_affected_rows(), mysql_unbuffered_query(), mysql_free_result(), mysql_fetch_array(), mysql_fetch_row(), mysql_fetch_assoc(), mysql_result(), mysql_select_db() i mysql_connect().
mysql_real_escape_string
(PHP 4 >= 4.3.0, PHP 5)
mysql_real_escape_string — Dodaje znaki unikowe w łańcuchu znaków do użycia w instrukcji SQL
Opis
$łańcuch_bez_znaków_unikowych
[, resource $identyfikator_połączeniar
] )
Dodaje znaki unikowe do łańcucha_bez_znaków_unikowych,
mając na uwadze aktualnie używany w połączeniu zestaw znaków by tak przygotowanego łańcucha
można bezpiecznie użyc w funkcji mysql_query(). Jeśli dopisywane
dane mają postać binarną wymagane jest użycie tej funkcji.
mysql_real_escape_string() wywołuje funkcję biblioteki MySQL mysql_real_escape_string, która dodaje lewe ukośniki (backslash) do następujących znaków: \x00, \n, \r, \, ', " and \x1a.
Użycie tej funkcji jest wymagane zawsze (poza kilkoma wyjątkami) przed wysłaniem zapytania do bazy danych aby zabezpieczyć dane.
Parametry
-
łańcuch_bez_znaków_unikowych -
Łańcuch, do którego zostaną dodane znaki unikowe.
-
identyfikator_połączenia -
Połączenie MySQL. Jeśli identyfikator połączenia nie zostanie podany, użyte zostanie ostatnie połączenie otwarte przez mysql_connect(). Jeśli połączenie takie nie zostanie znalezione, funkcja spróbuje nawiązać połączenie tak, jakby wywołana została funkcja mysql_connect() bez argumentów. Jeśli żadne połączenie nie zostanie znalezione lub nawiązane, wygenerowany zostanie błąd poziomu
E_WARNING.
Zwracane wartości
Zwraca łańcuch ze znakami unikowymi lub FALSE w przypadku błędu.
Przykłady
Przykład #1 Przykład użycia mysql_real_escape_string()
<?php
// Connect
$link = mysql_connect('host', 'uzytkownik', 'haslo')
OR die(mysql_error());
// Zapytanie
$query = sprintf("SELECT * FROM uzytkownicy WHERE uzytkownik='%s' AND haslo='%s'",
mysql_real_escape_string($uzytkownik),
mysql_real_escape_string($haslo));
?>
Przykład #2 Przykład ataku SQL Injection
<?php
// Nie sprawdziliśmy zmiennej $_POST['password'], która może zawierać wszystko czego chciał użytkownik! Na przykład:
$_POST['username'] = 'aidan';
$_POST['password'] = "' OR ''='";
// Zapytanie pobierające pasujących użytkowników
$query = "SELECT * FROM users WHERE user='{$_POST['username']}' AND password='{$_POST['password']}'";
mysql_query($query);
// Oznacza to, że zapytanie ma postać:
echo $query;
?>
Zapytanie wysłane do bazy danych:
SELECT * FROM users WHERE user='aidan' AND password='' OR ''=''
Zapytanie to pozwala zalogować się każdemu bez znajomości poprawnego hasła.
Notatki
Informacja:
Przed użyciem mysql_real_escape_string() należy otworzyć połączenie z MySQL, w przeciwnym razie zostanie wygenerowany błąd poziomu E_WARNING i zwrócona zostanie wartość
FALSE. Jeśliidentyfikator_połączenianie został zdefiniowany, zostanie użyte ostatnie połączenie do serwera MySQL.
Informacja:
Jeśli opcja magic_quotes_gpc została włączona, najpierw na danych należy użyć stripslashes(). Użycie tej funkcji samej spowoduje, że do danych zostaną dodane podwójne znaki unikowe.
Informacja:
Jeśli funkcja ta nie zostanie użyta na danych, zapytanie będzie podatne na ataki SQL Injection Attacks.
Informacja: mysql_real_escape_string() nie dodaje znaków unikowych do % i _. Te maski są stosowane w zapytaniach MySQL w połączeniu z LIKE, GRANT lub REVOKE.
Zobacz też:
- mysql_client_encoding() - Zwraca nazwę zestawu znaków
- addslashes() - Quote string with slashes
- stripslashes() - Un-quotes a quoted string
- The magic_quotes_gpc directive
- The magic_quotes_runtime directive
mysql_result
(PHP 4, PHP 5)
mysql_result — Zwraca dane wynikowe
Opis
mysql_result() zwraca zawartość jednej komórki
z wyniku. Jako argument pole
można podać ofset, nazwę pola lub nazwę tabeli z nazwą pola (tabela.pole).
Jeżeli nazwa kolumny została zastąpiona synonimem ('select foo as bar
from...'), należy użyć tej nazwy zamiast rzeczywistej.
Przy pracy z dużymi wynikami, powinno się rozważyć użycie jednej z funkcji pobierających cały wiersz (patrz niżej). Jako, że funkcje te zwracają zawartość kilku komórek w jednym wywołaniu, są one ZNACZNIE szybsze niż mysql_result(). Podanie przesunięcia (offset) w argumencie pole jest znacznie szybsze niż podanie nazwy pola lub konstrukcji tabela.pole.
Wywołania mysql_result() nie powinny być mieszane z wywołaniami innych funkcji operujących na wyniku.
Zalecane wydajniejsze alternatywy: mysql_fetch_row(), mysql_fetch_array() i mysql_fetch_object().
mysql_select_db
(PHP 4, PHP 5)
mysql_select_db — Wybiera bazę MySQL
Opis
$nazwa_bazy
[, resource $identyfikator_połączenia
] )Ustawia aktywną bazę danych na serwerze określonym przez podany identyfikator połączenia. Kolejne wywołania funkcji mysql_query() będą dotyczyły aktywnej bazy danych.
Parametry
-
nazwa_bazy -
Nazwa wybieranej bazy danych.
-
identyfikator_połączenia -
Połączenie MySQL. Jeśli identyfikator połączenia nie zostanie podany, użyte zostanie ostatnie połączenie otwarte przez mysql_connect(). Jeśli połączenie takie nie zostanie znalezione, funkcja spróbuje nawiązać połączenie tak, jakby wywołana została funkcja mysql_connect() bez argumentów. Jeśli żadne połączenie nie zostanie znalezione lub nawiązane, wygenerowany zostanie błąd poziomu
E_WARNING.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Przykład użycia mysql_select_db()
<?php
$link = mysql_connect('localhost', 'uzytkownik', 'haslo');
if (!$link) {
die('Nie połączono : ' . mysql_error());
}
// Ustaw foo jako aktualną bazę danych
$db_selected = mysql_select_db('foo', $link);
if (!$db_selected) {
die ('Nie można ustawić foo : ' . mysql_error());
}
?>
Notatki
Informacja:
Dla zachowania zgodności z poprzednimi wersjami PHP możliwe jest używanie aliasów: mysql_selectdb()
Zobacz też:
- mysql_connect() - Otwiera połączenie do serwera MySQL
- mysql_pconnect() - Otwiera stałe połączenie z serwerem MySQL
- mysql_query() - Wysyła zapytanie do serwera MySQL
mysql_set_charset
(PHP 5 >= 5.2.3)
mysql_set_charset — Sets the client character set
Opis
$charset
[, resource $link_identifier = NULL
] )Sets the default character set for the current connection.
Parametry
-
charset -
A valid character set name.
-
identyfikator_połączenia -
Połączenie MySQL. Jeśli identyfikator połączenia nie zostanie podany, użyte zostanie ostatnie połączenie otwarte przez mysql_connect(). Jeśli połączenie takie nie zostanie znalezione, funkcja spróbuje nawiązać połączenie tak, jakby wywołana została funkcja mysql_connect() bez argumentów. Jeśli żadne połączenie nie zostanie znalezione lub nawiązane, wygenerowany zostanie błąd poziomu
E_WARNING.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Notatki
Informacja:
This function requires MySQL 5.0.7 or later.
Informacja:
This is the preferred way to change the charset. Using mysql_query() to execute SET NAMES .. is not recommended.
Zobacz też:
- mysql_client_encoding() - Zwraca nazwę zestawu znaków
- » List of character sets that MySQL supports
mysql_stat
(PHP 4 >= 4.3.0, PHP 5)
mysql_stat — Pobiera aktualny stan systemu
Opis
$identyfikator_połączenia
] )mysql_stat() zwraca aktualny stan serwera.
Informacja:
mysql_stat() w chwili obecnej zwraca jedynie czas pracy serwera, liczbę wątków, zapytań, otwartych tabel, oraz liczbę zapytań na sekundę. Pełną listę parametrów opisujących stan można uzyskać wydając komendę SQL: SHOW STATUS.
Przykład #1 przykład użycia mysql_stat()
<?php
$link = mysql_connect('localhost', 'uzytkownik', 'haslo');
printf("%s\n", mysql_stat($link));
?>
Powyższy przykład da następujący wynik:
Uptime: 5380 Threads: 1 Questions: 1321299 Slow queries: 1 Opens: 26 Flush tables: 1 Open tables: 17 Queries per second avg: 245.595
mysql_tablename
(PHP 4, PHP 5)
mysql_tablename — Zwraca nazwę tabeli
Opis
$wynik
, int $i
)mysql_tablename() przyjmuje jako parametry wskaźnik wyniku zwrócony przez mysql_list_tables() oraz indeks, zwracając nazwę tabeli. Liczbę tabel zwróconych w wyniku można określić używając funkcji mysql_num_rows().
Przykład #1 Przykład użycia mysql_tablename()
<?php
mysql_connect('localhost', 'uzytkownik', 'haslo');
$result = mysql_list_tables('baza');
for ($i = 0; $i < mysql_num_rows($result); $i++)
printf ("Tabela: %s\n", mysql_tablename($result, $i));
mysql_free_result($result);
?>
Patrz także: mysql_list_tables().
mysql_thread_id
(PHP 4 >= 4.3.0, PHP 5)
mysql_thread_id — Zwraca id bieżącego wątku
Opis
$identyfikator_połączenia
] )mysql_thread_id() zwraca id bieżącego wątku. Jeśli połączenie zostało przerwane i nawiązane ponownie przy użyciu funkcji mysql_ping(), to id wątku się zmieni. Oznacza to, że nie powinno się pobierać id wątku i zapisywać do późniejszego użycia, lecz pobierać zawsze, gdy jest potrzebny.
Przykład #1 przykład użycia mysql_list_processes()
<?php
$link = mysql_connect('localhost', 'uzytkownik', 'haslo');
$thread_id = mysql_thread_id($link);
if ($thread_id){
printf ("id bieżącego wątku: %d\n", $thread_id);
}
?>
Powyższy przykład da następujący wynik:
id bieżącego wątku: 73
Patrz także: mysql_ping(), mysql_list_processes().
mysql_unbuffered_query
(PHP 4 >= 4.0.6, PHP 5)
mysql_unbuffered_query — Wysyła zapytanie do serwera MySQL nie pobierając i nie buforując wyniku
Opis
$zapytanie
[, resource $identyfikator_połączenia
] )
mysql_unbuffered_query() wysyła
zapytanie SQL do serwera MySQL, nie pobierając
i nie buforując wyników zapytań, w przeciwieństwie do
mysql_query().
To oszczędza znaczną ilość pamięci w zapytaniach SQL, które
generują duże zbiory wynikowe. Można pracować na zbiorze wynikowym
natychmiast po pobraniu pierwszego rekordu. Nie trzeba czekać, aż
zapytanie SQL zostanie w bazie danych wykonane do końca.
Aby posługiwać się funkcją mysql_unbuffered_query()
z kilkoma połączeniami do baz danych, należy podawać opcjonalny parametr
identyfikator_połączenia określający, które
połączenie ma zostać wykorzystane.
Parametry
-
zapytanie -
Zapytanie SQL do wykonania
Dane w zapytaniu powinny być poprzedzone poprawnymi znakami ucieczki.
-
identyfikator_połączenia -
Połączenie MySQL. Jeśli identyfikator połączenia nie zostanie podany, użyte zostanie ostatnie połączenie otwarte przez mysql_connect(). Jeśli połączenie takie nie zostanie znalezione, funkcja spróbuje nawiązać połączenie tak, jakby wywołana została funkcja mysql_connect() bez argumentów. Jeśli żadne połączenie nie zostanie znalezione lub nawiązane, wygenerowany zostanie błąd poziomu
E_WARNING.
Zwracane wartości
Dla wyrażeń SELECT, SHOW, DESCRIBE lub EXPLAIN,
mysql_unbuffered_query()
zwraca zasób w przypadku sukcesu lub FALSE gdy
nastąpi niepowodzenie.
Dla innych typów wyrażeń SQL, UPDATE, DELETE, DROP, etc,
mysql_unbuffered_query() zwróci TRUE w przypadku
powodzenia lub FALSE gdy nastąpi błąd.
Notatki
Informacja:
Oprócz korzyści, funkcja mysql_unbuffered_query() wprowadza pewne ograniczenia: nie można użyć funkcji mysql_num_rows() i mysql_data_seek() na zbiorze wynikowym, zwróconym przez mysql_unbuffered_query(). Trzeba także pobrać wszystkie wiersze ze zbioru wynikowego niebuforowanego zapytania SQL przed wysłaniem kolejnego.
Spis treści
- mysql_affected_rows — Zwraca liczbę wierszy przetworzonych w poprzedniej operacji MySQL
- mysql_client_encoding — Zwraca nazwę zestawu znaków
- mysql_close — Zamyka połączenie MySQL
- mysql_connect — Otwiera połączenie do serwera MySQL
- mysql_create_db — Tworzy bazę MySQL
- mysql_data_seek — Przesuwa wewnętrzny wskaźnik wyniku
- mysql_db_name — Pobiera dane wynikowe
- mysql_db_query — Wybiera bazę danych MySQL i wykonuje na niej zapytanie
- mysql_drop_db — Usuwa bazę MySQL
- mysql_errno — Zwraca liczbową wartość kodu błędu z poprzedniej operacji MySQL
- mysql_error — Zwraca tekst komunikatu błędu z ostatniej operacji MySQL
- mysql_escape_string — Dodaje znaki unikowe na użytek mysql_query
- mysql_fetch_array — Zapisuje wiersz wyniku w tablicy asocjacyjnej, numerycznej lub w obu
- mysql_fetch_assoc — Zapisuje wiersz wyniku w tablicy asocjacyjnej
- mysql_fetch_field — Pobiera z wyniku informacje o kolumnie i zwraca jako obiekt
- mysql_fetch_lengths — Pobiera długość każdego pola w wierszu wyniku
- mysql_fetch_object — Zapisuje wiersz wyniku jako obiekt
- mysql_fetch_row — Zapisuje wiersz wyniku w tablicy wyliczeniowej
- mysql_field_flags — Pobiera flagi dla danego pola w wyniku
- mysql_field_len — Zwraca długość danego pola
- mysql_field_name — Podaje nazwę danego pola w wyniku
- mysql_field_seek — Przesuwa wskaźnik wyniku do wybranego pola
- mysql_field_table — Pobiera nazwę tabeli w której znajduje się dane pole
- mysql_field_type — Pobiera typ podanego pola
- mysql_free_result — Zwalnia pamięć zajmowaną przez wynik
- mysql_get_client_info — Pobiera informacje o kliencie MySQL
- mysql_get_host_info — Pobiera informacje o hoście MySQL
- mysql_get_proto_info — Pobiera informacje o protokole MySQL
- mysql_get_server_info — Pobiera informacje o serwerze MySQL
- mysql_info — Pobiera informacje o ostatnim zapytaniu
- mysql_insert_id — Podaje numer ID wygenerowany podczas ostatniej operacji INSERT
- mysql_list_dbs — Pobiera nazwy baz dostępnych na serwerze MySQL
- mysql_list_fields — Pobiera informacje o polach tabeli MySQL
- mysql_list_processes — Zwraca listę procesów MySQL
- mysql_list_tables — Pobiera listę tabel z bazy MySQL
- mysql_num_fields — Zwraca liczbę pól w wyniku
- mysql_num_rows — Zwraca liczbę wierszy w wyniku
- mysql_pconnect — Otwiera stałe połączenie z serwerem MySQL
- mysql_ping — Sprawdza połączenie z serwerem, lub nawiązuje połączenie, jeśli go nie było
- mysql_query — Wysyła zapytanie do serwera MySQL
- mysql_real_escape_string — Dodaje znaki unikowe w łańcuchu znaków do użycia w instrukcji SQL
- mysql_result — Zwraca dane wynikowe
- mysql_select_db — Wybiera bazę MySQL
- mysql_set_charset — Sets the client character set
- mysql_stat — Pobiera aktualny stan systemu
- mysql_tablename — Zwraca nazwę tabeli
- mysql_thread_id — Zwraca id bieżącego wątku
- mysql_unbuffered_query — Wysyła zapytanie do serwera MySQL nie pobierając i nie buforując wyniku
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Przykłady
- MySQL Funkcje
- mysql_affected_rows — Zwraca liczbę wierszy przetworzonych w poprzedniej operacji MySQL
- mysql_client_encoding — Zwraca nazwę zestawu znaków
- mysql_close — Zamyka połączenie MySQL
- mysql_connect — Otwiera połączenie do serwera MySQL
- mysql_create_db — Tworzy bazę MySQL
- mysql_data_seek — Przesuwa wewnętrzny wskaźnik wyniku
- mysql_db_name — Pobiera dane wynikowe
- mysql_db_query — Wybiera bazę danych MySQL i wykonuje na niej zapytanie
- mysql_drop_db — Usuwa bazę MySQL
- mysql_errno — Zwraca liczbową wartość kodu błędu z poprzedniej operacji MySQL
- mysql_error — Zwraca tekst komunikatu błędu z ostatniej operacji MySQL
- mysql_escape_string — Dodaje znaki unikowe na użytek mysql_query
- mysql_fetch_array — Zapisuje wiersz wyniku w tablicy asocjacyjnej, numerycznej lub w obu
- mysql_fetch_assoc — Zapisuje wiersz wyniku w tablicy asocjacyjnej
- mysql_fetch_field — Pobiera z wyniku informacje o kolumnie i zwraca jako obiekt
- mysql_fetch_lengths — Pobiera długość każdego pola w wierszu wyniku
- mysql_fetch_object — Zapisuje wiersz wyniku jako obiekt
- mysql_fetch_row — Zapisuje wiersz wyniku w tablicy wyliczeniowej
- mysql_field_flags — Pobiera flagi dla danego pola w wyniku
- mysql_field_len — Zwraca długość danego pola
- mysql_field_name — Podaje nazwę danego pola w wyniku
- mysql_field_seek — Przesuwa wskaźnik wyniku do wybranego pola
- mysql_field_table — Pobiera nazwę tabeli w której znajduje się dane pole
- mysql_field_type — Pobiera typ podanego pola
- mysql_free_result — Zwalnia pamięć zajmowaną przez wynik
- mysql_get_client_info — Pobiera informacje o kliencie MySQL
- mysql_get_host_info — Pobiera informacje o hoście MySQL
- mysql_get_proto_info — Pobiera informacje o protokole MySQL
- mysql_get_server_info — Pobiera informacje o serwerze MySQL
- mysql_info — Pobiera informacje o ostatnim zapytaniu
- mysql_insert_id — Podaje numer ID wygenerowany podczas ostatniej operacji INSERT
- mysql_list_dbs — Pobiera nazwy baz dostępnych na serwerze MySQL
- mysql_list_fields — Pobiera informacje o polach tabeli MySQL
- mysql_list_processes — Zwraca listę procesów MySQL
- mysql_list_tables — Pobiera listę tabel z bazy MySQL
- mysql_num_fields — Zwraca liczbę pól w wyniku
- mysql_num_rows — Zwraca liczbę wierszy w wyniku
- mysql_pconnect — Otwiera stałe połączenie z serwerem MySQL
- mysql_ping — Sprawdza połączenie z serwerem, lub nawiązuje połączenie, jeśli go nie było
- mysql_query — Wysyła zapytanie do serwera MySQL
- mysql_real_escape_string — Dodaje znaki unikowe w łańcuchu znaków do użycia w instrukcji SQL
- mysql_result — Zwraca dane wynikowe
- mysql_select_db — Wybiera bazę MySQL
- mysql_set_charset — Sets the client character set
- mysql_stat — Pobiera aktualny stan systemu
- mysql_tablename — Zwraca nazwę tabeli
- mysql_thread_id — Zwraca id bieżącego wątku
- mysql_unbuffered_query — Wysyła zapytanie do serwera MySQL nie pobierając i nie buforując wyniku
MySQL Improved Extension
Wstęp
The mysqli extension allows you to access the functionality provided by MySQL 4.1 and above. More information about the MySQL Database server can be found at » http://www.mysql.com/
An overview of software available for using MySQL from PHP can be found at Overview
Documentation for MySQL can be found at » http://dev.mysql.com/doc/.
Parts of this documentation included from MySQL manual with permissions of Oracle Corporation.
Examples
All examples in the mysqli documentation use the world database. The world database can be found at » http://downloads.mysql.com/docs/world.sql.gz
Overview
This section provides an introduction to the options available to you when developing a PHP application that needs to interact with a MySQL database.
What is an API?
An Application Programming Interface, or API, defines the classes, methods, functions and variables that your application will need to call in order to carry out its desired task. In the case of PHP applications that need to communicate with databases the necessary APIs are usually exposed via PHP extensions.
APIs can be procedural or object-oriented. With a procedural API you call functions to carry out tasks, with the object-oriented API you instantiate classes and then call methods on the resulting objects. Of the two the latter is usually the preferred interface, as it is more modern and leads to better organised code.
When writing PHP applications that need to connect to the MySQL server there are several API options available. This document discusses what is available and how to select the best solution for your application.
What is a Connector?
In the MySQL documentation, the term connector refers to a piece of software that allows your application to connect to the MySQL database server. MySQL provides connectors for a variety of languages, including PHP.
If your PHP application needs to communicate with a database server you will need to write PHP code to perform such activities as connecting to the database server, querying the database and other database-related functions. Software is required to provide the API that your PHP application will use, and also handle the communication between your application and the database server, possibly using other intermediate libraries where necessary. This software is known generically as a connector, as it allows your application to connect to a database server.
What is a Driver?
A driver is a piece of software designed to communicate with a specific type of database server. The driver may also call a library, such as the MySQL Client Library or the MySQL Native Driver. These libraries implement the low-level protocol used to communicate with the MySQL database server.
By way of an example, the PHP Data Objects (PDO) database abstraction layer may use one of several database-specific drivers. One of the drivers it has available is the PDO MYSQL driver, which allows it to interface with the MySQL server.
Sometimes people use the terms connector and driver interchangeably, this can be confusing. In the MySQL-related documentation the term "driver" is reserved for software that provides the database-specific part of a connector package.
What is an Extension?
In the PHP documentation you will come across another term - extension. The PHP code consists of a core, with optional extensions to the core functionality. PHP's MySQL-related extensions, such as the mysqli extension, and the mysql extension, are implemented using the PHP extension framework.
An extension typically exposes an API to the PHP programmer, to allow its facilities to be used programmatically. However, some extensions which use the PHP extension framework do not expose an API to the PHP programmer.
The PDO MySQL driver extension, for example, does not expose an API to the PHP programmer, but provides an interface to the PDO layer above it.
The terms API and extension should not be taken to mean the same thing, as an extension may not necessarily expose an API to the programmer.
What are the main PHP API offerings for using MySQL?
There are three main API options when considering connecting to a MySQL database server:
-
PHP's MySQL Extension
-
PHP's mysqli Extension
-
PHP Data Objects (PDO)
Each has its own advantages and disadvantages. The following discussion aims to give a brief introduction to the key aspects of each API.
What is PHP's MySQL Extension?
This is the original extension designed to allow you to develop PHP applications that interact with a MySQL database. The mysql extension provides a procedural interface and is intended for use only with MySQL versions older than 4.1.3. This extension can be used with versions of MySQL 4.1.3 or newer, but not all of the latest MySQL server features will be available.
Informacja:
If you are using MySQL versions 4.1.3 or later it is strongly recommended that you use the mysqli extension instead.
The mysql extension source code is located in the PHP extension directory ext/mysql.
For further information on the mysql extension, see Mysql.
What is PHP's mysqli Extension?
The mysqli extension, or as it is sometimes known, the MySQL improved extension, was developed to take advantage of new features found in MySQL systems versions 4.1.3 and newer. The mysqli extension is included with PHP versions 5 and later.
The mysqli extension has a number of benefits, the key enhancements over the mysql extension being:
-
Object-oriented interface
-
Support for Prepared Statements
-
Support for Multiple Statements
-
Support for Transactions
-
Enhanced debugging capabilities
-
Embedded server support
Informacja:
If you are using MySQL versions 4.1.3 or later it is strongly recommended that you use this extension.
As well as the object-oriented interface the extension also provides a procedural interface.
The mysqli extension is built using the PHP extension framework, its source code is located in the directory ext/mysqli.
For further information on the mysqli extension, see Mysqli.
What is PDO?
PHP Data Objects, or PDO, is a database abstraction layer specifically for PHP applications. PDO provides a consistent API for your PHP application regardless of the type of database server your application will connect to. In theory, if you are using the PDO API, you could switch the database server you used, from say Firebird to MySQL, and only need to make minor changes to your PHP code.
Other examples of database abstraction layers include JDBC for Java applications and DBI for Perl.
While PDO has its advantages, such as a clean, simple, portable API, its main disadvantage is that it doesn't allow you to use all of the advanced features that are available in the latest versions of MySQL server. For example, PDO does not allow you to use MySQL's support for Multiple Statements.
PDO is implemented using the PHP extension framework, its source code is located in the directory ext/pdo.
For further information on PDO, see the PDO.
What is the PDO MYSQL driver?
The PDO MYSQL driver is not an API as such, at least from the PHP programmer's perspective. In fact the PDO MYSQL driver sits in the layer below PDO itself and provides MySQL-specific functionality. The programmer still calls the PDO API, but PDO uses the PDO MYSQL driver to carry out communication with the MySQL server.
The PDO MYSQL driver is one of several available PDO drivers. Other PDO drivers available include those for the Firebird and PostgreSQL database servers.
The PDO MYSQL driver is implemented using the PHP extension framework. Its source code is located in the directory ext/pdo_mysql. It does not expose an API to the PHP programmer.
For further information on the PDO MYSQL driver, see MySQL (PDO).
What is PHP's MySQL Native Driver?
In order to communicate with the MySQL database server the mysql extension, mysqli and the PDO MYSQL driver each use a low-level library that implements the required protocol. In the past, the only available library was the MySQL Client Library, otherwise known as libmysql.
However, the interface presented by libmysql was not optimized for communication with PHP applications, as libmysql was originally designed with C applications in mind. For this reason the MySQL Native Driver, mysqlnd, was developed as an alternative to libmysql for PHP applications.
The mysql extension, the mysqli extension and the PDO MySQL driver can each be individually configured to use either libmysql or mysqlnd. As mysqlnd is designed specifically to be utilised in the PHP system it has numerous memory and speed enhancements over libmysql. You are strongly encouraged to take advantage of these improvements.
Informacja:
The MySQL Native Driver can only be used with MySQL server versions 4.1.3 and later.
The MySQL Native Driver is implemented using the PHP extension framework. The source code is located in ext/mysqlnd. It does not expose an API to the PHP programmer.
Comparison of Features
The following table compares the functionality of the three main methods of connecting to MySQL from PHP:
| PHP's mysqli Extension | PDO (Using PDO MySQL Driver and MySQL Native Driver) | PHP's MySQL Extension | |
|---|---|---|---|
| PHP version introduced | 5.0 | 5.0 | Prior to 3.0 |
| Included with PHP 5.x | yes | yes | Yes |
| MySQL development status | Active development | Active development as of PHP 5.3 | Maintenance only |
| Recommended by MySQL for new projects | Yes - preferred option | Yes | No |
| API supports Charsets | Yes | Yes | No |
| API supports server-side Prepared Statements | Yes | Yes | No |
| API supports client-side Prepared Statements | No | Yes | No |
| API supports Stored Procedures | Yes | Yes | No |
| API supports Multiple Statements | Yes | Most | No |
| Supports all MySQL 4.1+ functionality | Yes | Most | No |
Quick start guide
Spis treści
- Dual procedural and object-oriented interface
- Connections
- Executing statements
- Prepared Statements
- Stored Procedures
- Multiple Statements
- API support for transactions
- Metadata
This quick start guide will help with choosing and gaining familiarity with the PHP MySQL API.
This quick start gives an overview on the mysqli extension. Code examples are provided for all major aspects of the API. Database concepts are explained to the degree needed for presenting concepts specific to MySQL.
Required: A familiarity with the PHP programming language, the SQL language, and basic knowledge of the MySQL server.
Dual procedural and object-oriented interface
The mysqli extension features a dual interface. It supports the procedural and object-oriented programming paradigm.
Users migrating from the old mysql extension may prefer the procedural interface. The procedural interface is similar to that of the old mysql extension. In many cases, the function names differ only by prefix. Some mysqli functions take a connection handle as their first argument, whereas matching functions in the old mysql interface take it as an optional last argument.
Przykład #1 Easy migration from the old mysql extension
<?php
$mysqli = mysqli_connect("example.com", "user", "password", "database");
$res = mysqli_query($mysqli, "SELECT 'Please, do not use ' AS _msg FROM DUAL");
$row = mysqli_fetch_assoc($res);
echo $row['_msg'];
$mysql = mysql_connect("localhost", "root", "");
mysql_select_db("test");
$res = mysql_query("SELECT 'the mysql extension for new developments.' AS _msg FROM DUAL", $mysql);
$row = mysql_fetch_assoc($res);
echo $row['_msg'];
?>
Powyższy przykład wyświetli:
Please, do not use the mysql extension for new developments.
The object-oriented interface
In addition to the classical procedural interface, users can choose to use the object-oriented interface. The documentation is organized using the object-oriented interface. The object-oriented interface shows functions grouped by their purpose, making it easier to get started. The reference section gives examples for both syntax variants.
There are no significant performance differences between the two interfaces. Users can base their choice on personal preference.
Przykład #2 Object-oriented and procedural interface
<?php
$mysqli = mysqli_connect("example.com", "user", "password", "database");
if (mysqli_connect_errno($mysqli)) {
echo "Failed to connect to MySQL: " . mysqli_connect_error();
}
$res = mysqli_query($mysqli, "SELECT 'A world full of ' AS _msg FROM DUAL");
$row = mysqli_fetch_assoc($res);
echo $row['_msg'];
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
echo "Failed to connect to MySQL: " . $mysqli->connect_error;
}
$res = $mysqli->query("SELECT 'choices to please everybody,' AS _msg FROM DUAL");
$row = $res->fetch_assoc();
echo $row['_msg'];
?>
Powyższy przykład wyświetli:
A world full of choices to please everybody.
The object oriented interface is used for the quickstart because the reference section is organized that way.
Mixing styles
It is possible to switch between styles at any time. Mixing both styles is not recommended for code clarity and coding style reasons.
Przykład #3 Bad coding style
<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
echo "Failed to connect to MySQL: " . $mysqli->connect_error;
}
$res = mysqli_query($mysqli, "SELECT 'Possible but bad style.' AS _msg FROM DUAL");
if (!$res) {
echo "Failed to run query: (" . $mysqli->errno . ") " . $mysqli->error;
}
if ($row = $res->fetch_assoc()) {
echo $row['_msg'];
}
?>
Powyższy przykład wyświetli:
Possible but bad style.
See also
Connections
The MySQL server supports the use of different transport layers for connections. Connections use TCP/IP, Unix domain sockets or Windows named pipes.
The hostname localhost has a special meaning. It is bound to the use of Unix domain sockets. It is not possible to open a TCP/IP connection using the hostname localhost you must use 127.0.0.1 instead.
Przykład #1 Special meaning of localhost
<?php
$mysqli = new mysqli("localhost", "user", "password", "database");
if ($mysqli->connect_errno) {
echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}
echo $mysqli->host_info . "\n";
$mysqli = new mysqli("127.0.0.1", "user", "password", "database", 3306);
if ($mysqli->connect_errno) {
echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}
echo $mysqli->host_info . "\n";
?>
Powyższy przykład wyświetli:
Localhost via UNIX socket 127.0.0.1 via TCP/IP
Connection parameter defaults
Depending on the connection function used, assorted parameters can be omitted. If a parameter is not provided, then the extension attempts to use the default values that are set in the PHP configuration file.
Przykład #2 Setting defaults
mysqli.default_host=192.168.2.27 mysqli.default_user=root mysqli.default_pw="" mysqli.default_port=3306 mysqli.default_socket=/tmp/mysql.sock
The resulting parameter values are then passed to the client library that is used by the extension. If the client library detects empty or unset parameters, then it may default to the library built-in values.
Built-in connection library defaults
If the host value is unset or empty, then the client library will default to a Unix socket connection on localhost. If socket is unset or empty, and a Unix socket connection is requested, then a connection to the default socket on /tmp/mysql.sock is attempted.
On Windows systems, the host name . is interpreted by the client library as an attempt to open a Windows named pipe based connection. In this case the socket parameter is interpreted as the pipe name. If not given or empty, then the socket (pipe name) defaults to \\.\pipe\MySQL.
If neither a Unix domain socket based not a Windows named pipe based connection is to be be established and the port parameter value is unset, the library will default to port 3306.
The mysqlnd library and the MySQL Client Library (libmysql) implement the same logic for determining defaults.
Connection options
Connection options are available to, for example, set init commands which are executed upon connect, or for requesting use of a certain charset. Connection options must be set before a network connection is established.
For setting a connection option, the connect operation has to be performed in three steps: creating a connection handle with mysqli_init(), setting the requested options using mysqli_options(), and establishing the network connection with mysqli_real_connect().
Connection pooling
The mysqli extension supports persistent database connections, which are a special kind of pooled connections. By default, every database connection opened by a script is either explicitly closed by the user during runtime or released automatically at the end of the script. A persistent connection is not. Instead it is put into a pool for later reuse, if a connection to the same server using the same username, password, socket, port and default database is opened. Reuse saves connection overhead.
Every PHP process is using its own mysqli connection pool. Depending on the web server deployment model, a PHP process may serve one or multiple requests. Therefore, a pooled connection may be used by one or more scripts subsequently.
Persistent connection
If a unused persistent connection for a given combination of host, username, password, socket, port and default database can not be found in the connection pool, then mysqli opens a new connection. The use of persistent connections can be enabled and disabled using the PHP directive mysqli.allow_persistent. The total number of connections opened by a script can be limited with mysqli.max_links. The maximum number of persistent connections per PHP process can be restricted with mysqli.max_persistent. Please note, that the web server may spawn many PHP processes.
A common complain about persistent connections is that their state is not reset before reuse. For example, open and unfinished transactions are not automatically rolled back. But also, authorization changes which happened in the time between putting the connection into the pool and reusing it are not reflected. This may be seen as an unwanted side-effect. On the contrary, the name persistent may be understood as a promise that the state is persisted.
The mysqli extension supports both interpretations of a persistent connection: state persisted, and state reset before reuse. The default is reset. Before a persistent connection is reused, the mysqli extension implicitly calls mysqli_change_user() to reset the state. The persistent connection appears to the user as if it was just opened. No artifacts from previous usages are visible.
The mysqli_change_user() function is an expensive operation.
For best performance, users may want to recompile the extension with the
compile flag MYSQLI_NO_CHANGE_USER_ON_PCONNECT being set.
It is left to the user to choose between safe behavior and best performance. Both are valid optimization goals. For ease of use, the safe behavior has been made the default at the expense of maximum performance.
See also
Executing statements
Statements can be executed with the mysqli_query(), mysqli_real_query() and mysqli_multi_query() functions. The mysqli_query() function is the most common, and combines the executing statement with a buffered fetch of its result set, if any, in one call. Calling mysqli_query() is identical to calling mysqli_real_query() followed by mysqli_store_result().
The mysqli_multi_query() function is used with multiple statements.
Przykład #1 Bad coding style
<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}
if (!$mysqli->query("DROP TABLE IF EXISTS test") ||
!$mysqli->query("CREATE TABLE test(id INT)") ||
!$mysqli->query("INSERT INTO test(id) VALUES (1)")) {
echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
?>
Buffered result sets
After statement execution results can be retrieved at once to be buffered by the client or by read row by row. Client-side result set buffering allows the server to free resources associated with the statement results as early as possible. Generally speaking, clients are slow consuming result sets. Therefore, it is recommended to use buffered result sets. mysqli_query() combines statement execution and result set buffering.
PHP applications can navigate freely through buffered results. Navigation is fast because the result sets are held in client memory. Please, keep in mind that it is often easier to scale by client than it is to scale the server.
Przykład #2 Navigation through buffered results
<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}
if (!$mysqli->query("DROP TABLE IF EXISTS test") ||
!$mysqli->query("CREATE TABLE test(id INT)") ||
!$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)")) {
echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
$res = $mysqli->query("SELECT id FROM test ORDER BY id ASC");
echo "Reverse order...\n";
for ($row_no = $res->num_rows - 1; $row_no >= 0; $row_no--) {
$res->data_seek($row_no);
$row = $res->fetch_assoc();
echo " id = " . $row['id'] . "\n";
}
echo "Result set order...\n";
$res->data_seek(0);
while ($row = $res->fetch_assoc()) {
echo " id = " . $row['id'] . "\n";
}
?>
Powyższy przykład wyświetli:
Reverse order... id = 3 id = 2 id = 1 Result set order... id = 1 id = 2 id = 3
Unbuffered result sets
If client memory is a short resource and freeing server resources as early as possible to keep server load low is not needed, unbuffered results can be used. Scrolling through unbuffered results is not possible before all rows have been read.
Przykład #3 Navigation through buffered results
<?php
$mysqli->real_query("SELECT id FROM test ORDER BY id ASC");
$res = $mysqli->use_result();
echo "Result set order...\n";
while ($row = $res->fetch_assoc()) {
echo " id = " . $row['id'] . "\n";
}
?>
Result set values data types
The mysqli_query(), mysqli_real_query() and mysqli_multi_query() functions are used to execute non-prepared statements. At the level of the MySQL Client Server Protocol, the command COM_QUERY and the text protocol are used for statement execution. With the text protocol, the MySQL server converts all data of a result sets into strings before sending. This conversion is done regardless of the SQL result set column data type. The mysql client libraries receive all column values as strings. No further client-side casting is done to convert columns back to their native types. Instead, all values are provided as PHP strings.
Przykład #4 Text protocol returns strings by default
<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}
if (!$mysqli->query("DROP TABLE IF EXISTS test") ||
!$mysqli->query("CREATE TABLE test(id INT, label CHAR(1))") ||
!$mysqli->query("INSERT INTO test(id, label) VALUES (1, 'a')")) {
echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
$res = $mysqli->query("SELECT id, label FROM test WHERE id = 1");
$row = $res->fetch_assoc();
printf("id = %s (%s)\n", $row['id'], gettype($row['id']));
printf("label = %s (%s)\n", $row['label'], gettype($row['label']));
?>
Powyższy przykład wyświetli:
id = 1 (string) label = a (string)
It is possible to convert integer and float columns back to PHP numbers by setting the
MYSQLI_OPT_INT_AND_FLOAT_NATIVE connection option,
if using the mysqlnd library. If set, the mysqlnd library will
check the result set meta data column types and convert numeric SQL columns
to PHP numbers, if the PHP data type value range allows for it.
This way, for example, SQL INT columns are returned as integers.
Przykład #5 Native data types with mysqlnd and connection option
<?php
$mysqli = mysqli_init();
$mysqli->options(MYSQLI_OPT_INT_AND_FLOAT_NATIVE, 1);
$mysqli->real_connect("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}
if (!$mysqli->query("DROP TABLE IF EXISTS test") ||
!$mysqli->query("CREATE TABLE test(id INT, label CHAR(1))") ||
!$mysqli->query("INSERT INTO test(id, label) VALUES (1, 'a')")) {
echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
$res = $mysqli->query("SELECT id, label FROM test WHERE id = 1");
$row = $res->fetch_assoc();
printf("id = %s (%s)\n", $row['id'], gettype($row['id']));
printf("label = %s (%s)\n", $row['label'], gettype($row['label']));
?>
Powyższy przykład wyświetli:
id = 1 (integer) label = a (string)
See also
Prepared Statements
The MySQL database supports prepared statements. A prepared statement or a parameterized statement is used to execute the same statement repeatedly with high efficiency.
Basic workflow
The prepared statement execution consists of two stages: prepare and execute. At the prepare stage a statement template is send to the database server. The server performs a syntax check and initializes server internal resources for later use.
The MySQL server supports using anonymous, positional placeholder with ?.
Przykład #1 First stage: prepare
<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}
/* Non-prepared statement */
if (!$mysqli->query("DROP TABLE IF EXISTS test") || !$mysqli->query("CREATE TABLE test(id INT)")) {
echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
/* Prepared statement, stage 1: prepare */
if (!($stmt = $mysqli->prepare("INSERT INTO test(id) VALUES (?)"))) {
echo "Prepare failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
?>
Prepare is followed by execute. During execute the client binds parameter values and sends them to the server. The server creates a statement from the statement template and the bound values to execute it using the previously created internal resources.
Przykład #2 Second stage: bind and execute
<?php
/* Prepared statement, stage 2: bind and execute */
$id = 1;
if (!$stmt->bind_param("i", $id)) {
echo "Binding parameters failed: (" . $stmt->errno . ") " . $stmt->error;
}
if (!$stmt->execute()) {
echo "Execute failed: (" . $stmt->errno . ") " . $stmt->error;
}
?>
Repeated execution
A prepared statement can be executed repeatedly. Upon every execution the current value of the bound variable is evaluated and send to the server. The statement is not parsed again. The statement template is not transferred to the server again.
Przykład #3 INSERT prepared once, executed multiple times
<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}
/* Non-prepared statement */
if (!$mysqli->query("DROP TABLE IF EXISTS test") || !$mysqli->query("CREATE TABLE test(id INT)")) {
echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
/* Prepared statement, stage 1: prepare */
if (!($stmt = $mysqli->prepare("INSERT INTO test(id) VALUES (?)"))) {
echo "Prepare failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
/* Prepared statement, stage 2: bind and execute */
$id = 1;
if (!$stmt->bind_param("i", $id)) {
echo "Binding parameters failed: (" . $stmt->errno . ") " . $stmt->error;
}
if (!$stmt->execute()) {
echo "Execute failed: (" . $stmt->errno . ") " . $stmt->error;
}
/* Prepared statement: repeated execution, only data transferred from client to server */
for ($id = 2; $id < 5; $id++) {
if (!$stmt->execute()) {
echo "Execute failed: (" . $stmt->errno . ") " . $stmt->error;
}
}
/* explicit close recommended */
$stmt->close();
/* Non-prepared statement */
$res = $mysqli->query("SELECT id FROM test");
var_dump($res->fetch_all());
?>
Powyższy przykład wyświetli:
array(4) {
[0]=>
array(1) {
[0]=>
string(1) "1"
}
[1]=>
array(1) {
[0]=>
string(1) "2"
}
[2]=>
array(1) {
[0]=>
string(1) "3"
}
[3]=>
array(1) {
[0]=>
string(1) "4"
}
}
Every prepared statement occupies server resources. Statements should be closed explicitly immediately after use. If not done explicitly, the statement will be closed when the statement handle is freed by PHP.
Using a prepared statement is not always the most efficient way of executing a statement. A prepared statement executed only once causes more client-server round-trips than a non-prepared statement. This is why the SELECT is not run as a prepared statement above.
Also, consider the use of the MySQL multi-INSERT SQL syntax for INSERTs. For the example, multi-INSERT requires less round-trips between the server and client than the prepared statement shown above.
Przykład #4 Less round trips using multi-INSERT SQL
<?php
if (!$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3), (4)")) {
echo "Multi-INSERT failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
?>
Result set values data types
The MySQL Client Server Protocol defines a different data transfer protocol for prepared statements and non-prepared statements. Prepared statements are using the so called binary protocol. The MySQL server sends result set data "as is" in binary format. Results are not serialized into strings before sending. The client libraries do not receive strings only. Instead, they will receive binary data and try to convert the values into appropriate PHP data types. For example, results from an SQL INT column will be provided as PHP integer variables.
Przykład #5 Native datatypes
<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}
if (!$mysqli->query("DROP TABLE IF EXISTS test") ||
!$mysqli->query("CREATE TABLE test(id INT, label CHAR(1))") ||
!$mysqli->query("INSERT INTO test(id, label) VALUES (1, 'a')")) {
echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
$stmt = $mysqli->prepare("SELECT id, label FROM test WHERE id = 1");
$stmt->execute();
$res = $stmt->get_result();
$row = $res->fetch_assoc();
printf("id = %s (%s)\n", $row['id'], gettype($row['id']));
printf("label = %s (%s)\n", $row['label'], gettype($row['label']));
?>
Powyższy przykład wyświetli:
id = 1 (integer) label = a (string)
This behavior differs from non-prepared statements. By default, non-prepared statements return all results as strings. This default can be changed using a connection option. If the connection option is used, there are no differences.
Fetching results using bound variables
Results from prepared statements can either be retrieved by binding output variables, or by requesting a mysqli_result object.
Output variables must be bound after statement execution. One variable must be bound for every column of the statements result set.
Przykład #6 Output variable binding
<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}
if (!$mysqli->query("DROP TABLE IF EXISTS test") ||
!$mysqli->query("CREATE TABLE test(id INT, label CHAR(1))") ||
!$mysqli->query("INSERT INTO test(id, label) VALUES (1, 'a')")) {
echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
if (!($stmt = $mysqli->prepare("SELECT id, label FROM test"))) {
echo "Prepare failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
if (!$stmt->execute()) {
echo "Execute failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
$out_id = NULL;
$out_label = NULL;
if (!$stmt->bind_result($out_id, $out_label)) {
echo "Binding output parameters failed: (" . $stmt->errno . ") " . $stmt->error;
}
while ($stmt->fetch()) {
printf("id = %s (%s), label = %s (%s)\n", $out_id, gettype($out_id), $out_label, gettype($out_label));
}
?>
Powyższy przykład wyświetli:
id = 1 (integer), label = a (string)
Prepared statements return unbuffered result sets by default. The results of the statement are not implicitly fetched and transferred from the server to the client for client-side buffering. The result set takes server resources until all results have been fetched by the client. Thus it is recommended to consume results timely. If a client fails to fetch all results or the client closes the statement before having fetched all data, the data has to be fetched implicitly by mysqli.
It is also possible to buffer the results of a prepared statement using mysqli_stmt_store_result().
Fetching results using mysqli_result interface
Instead of using bound results, results can also be retrieved through the mysqli_result interface. mysqli_stmt_get_result() returns a buffered result set.
Przykład #7 Using mysqli_result to fetch results
<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}
if (!$mysqli->query("DROP TABLE IF EXISTS test") ||
!$mysqli->query("CREATE TABLE test(id INT, label CHAR(1))") ||
!$mysqli->query("INSERT INTO test(id, label) VALUES (1, 'a')")) {
echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
if (!($stmt = $mysqli->prepare("SELECT id, label FROM test ORDER BY id ASC"))) {
echo "Prepare failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
if (!$stmt->execute()) {
echo "Execute failed: (" . $stmt->errno . ") " . $stmt->error;
}
if (!($res = $stmt->get_result())) {
echo "Getting result set failed: (" . $stmt->errno . ") " . $stmt->error;
}
var_dump($res->fetch_all());
?>
Powyższy przykład wyświetli:
array(1) {
[0]=>
array(2) {
[0]=>
int(1)
[1]=>
string(1) "a"
}
}
Using the mysqli_result interface offers the additional benefit of flexible client-side result set navigation.
Przykład #8 Buffered result set for flexible read out
<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}
if (!$mysqli->query("DROP TABLE IF EXISTS test") ||
!$mysqli->query("CREATE TABLE test(id INT, label CHAR(1))") ||
!$mysqli->query("INSERT INTO test(id, label) VALUES (1, 'a'), (2, 'b'), (3, 'c')")) {
echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
if (!($stmt = $mysqli->prepare("SELECT id, label FROM test"))) {
echo "Prepare failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
if (!$stmt->execute()) {
echo "Execute failed: (" . $stmt->errno . ") " . $stmt->error;
}
if (!($res = $stmt->get_result())) {
echo "Getting result set failed: (" . $stmt->errno . ") " . $stmt->error;
}
for ($row_no = ($res->num_rows - 1); $row_no >= 0; $row_no--) {
$res->data_seek($row_no);
var_dump($res->fetch_assoc());
}
$res->close();
?>
Powyższy przykład wyświetli:
array(2) {
["id"]=>
int(3)
["label"]=>
string(1) "c"
}
array(2) {
["id"]=>
int(2)
["label"]=>
string(1) "b"
}
array(2) {
["id"]=>
int(1)
["label"]=>
string(1) "a"
}
Escaping and SQL injection
Bound variables will be escaped automatically by the server. The server inserts their escaped values at the appropriate places into the statement template before execution. A hint must be provided to the server for the type of bound variable, to create an appropriate conversion. See the mysqli_stmt_bind_param() function for more information.
The automatic escaping of values within the server is sometimes considered a security feature to prevent SQL injection. The same degree of security can be achieved with non-prepared statements, if input values are escaped correctly.
Client-side prepared statement emulation
The API does not include emulation for client-side prepared statement emulation.
Quick prepared - non-prepared statement comparison
The table below compares server-side prepared and non-prepared statements.
| Prepared Statement | Non-prepared statement | |
|---|---|---|
| Client-server round trips, SELECT, single execution | 2 | 1 |
| Statement string transferred from client to server | 1 | 1 |
| Client-server round trips, SELECT, repeated (n) execution | 1 + n | n |
| Statement string transferred from client to server | 1 template, n times bound parameter, if any | n times together with parameter, if any |
| Input parameter binding API | Yes, automatic input escaping | No, manual input escaping |
| Output variable binding API | Yes | No |
| Supports use of mysqli_result API | Yes, use mysqli_stmt_get_result() | Yes |
| Buffered result sets | Yes, use mysqli_stmt_get_result() or binding with mysqli_stmt_store_result() | Yes, default of mysqli_query() |
| Unbuffered result sets | Yes, use output binding API | Yes, use mysqli_real_query() with mysqli_use_result() |
| MySQL Client Server protocol data transfer flavor | Binary protocol | Text protocol |
| Result set values SQL data types | Preserved when fetching | Converted to string or preserved when fetching |
| Supports all SQL statements | Recent MySQL versions support most but not all | Yes |
See also
Stored Procedures
The MySQL database supports stored procedures. A stored procedure is a subroutine stored in the database catalog. Applications can call and execute the stored procedure. The CALL SQL statement is used to execute a stored procedure.
Parameter
Stored procedures can have IN, INOUT and OUT parameters, depending on the MySQL version. The mysqli interface has no special notion for the different kinds of parameters.
IN parameter
Input parameters are provided with the CALL statement. Please, make sure values are escaped correctly.
Przykład #1 Calling a stored procedure
<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}
if (!$mysqli->query("DROP TABLE IF EXISTS test") || !$mysqli->query("CREATE TABLE test(id INT)")) {
echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
if (!$mysqli->query("DROP PROCEDURE IF EXISTS p") ||
!$mysqli->query("CREATE PROCEDURE p(IN id_val INT) BEGIN INSERT INTO test(id) VALUES(id_val); END;")) {
echo "Stored procedure creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
if (!$mysqli->query("CALL p(1)")) {
echo "CALL failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
if (!($res = $mysqli->query("SELECT id FROM test"))) {
echo "SELECT failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
var_dump($res->fetch_assoc());
?>
Powyższy przykład wyświetli:
array(1) {
["id"]=>
string(1) "1"
}
INOUT/OUT parameter
The values of INOUT/OUT parameters are accessed using session variables.
Przykład #2 Using session variables
<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}
if (!$mysqli->query("DROP PROCEDURE IF EXISTS p") ||
!$mysqli->query('CREATE PROCEDURE p(OUT msg VARCHAR(50)) BEGIN SELECT "Hi!" INTO msg; END;')) {
echo "Stored procedure creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
if (!$mysqli->query("SET @msg = ''") || !$mysqli->query("CALL p(@msg)")) {
echo "CALL failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
if (!($res = $mysqli->query("SELECT @msg as _p_out"))) {
echo "Fetch failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
$row = $res->fetch_assoc();
echo $row['_p_out'];
?>
Powyższy przykład wyświetli:
Hi!
Application and framework developers may be able to provide a more convenient API using a mix of session variables and databased catalog inspection. However, please note the possible performance impact of a custom solution based on catalog inspection.
Handling result sets
Stored procedures can return result sets. Result sets returned from a stored procedure cannot be fetched correctly using mysqli_query(). The mysqli_query() function combines statement execution and fetching the first result set into a buffered result set, if any. However, there are additional stored procedure result sets hidden from the user which cause mysqli_query() to fail returning the user expected result sets.
Result sets returned from a stored procedure are fetched using mysqli_real_query() or mysqli_multi_query(). Both functions allow fetching any number of result sets returned by a statement, such as CALL. Failing to fetch all result sets returned by a stored procedure causes an error.
Przykład #3 Fetching results from stored procedures
<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}
if (!$mysqli->query("DROP TABLE IF EXISTS test") ||
!$mysqli->query("CREATE TABLE test(id INT)") ||
!$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)")) {
echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
if (!$mysqli->query("DROP PROCEDURE IF EXISTS p") ||
!$mysqli->query('CREATE PROCEDURE p() READS SQL DATA BEGIN SELECT id FROM test; SELECT id + 1 FROM test; END;')) {
echo "Stored procedure creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
if (!$mysqli->multi_query("CALL p()")) {
echo "CALL failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
do {
if ($res = $mysqli->store_result()) {
printf("---\n");
var_dump($res->fetch_all());
$res->free();
} else {
if ($mysqli->errno) {
echo "Store failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
}
} while ($mysqli->more_results() && $mysqli->next_result());
?>
Powyższy przykład wyświetli:
---
array(3) {
[0]=>
array(1) {
[0]=>
string(1) "1"
}
[1]=>
array(1) {
[0]=>
string(1) "2"
}
[2]=>
array(1) {
[0]=>
string(1) "3"
}
}
---
array(3) {
[0]=>
array(1) {
[0]=>
string(1) "2"
}
[1]=>
array(1) {
[0]=>
string(1) "3"
}
[2]=>
array(1) {
[0]=>
string(1) "4"
}
}
Use of prepared statements
No special handling is required when using the prepared statement interface for fetching results from the same stored procedure as above. The prepared statement and non-prepared statement interfaces are similar. Please note, that not every MYSQL server version may support preparing the CALL SQL statement.
Przykład #4 Stored Procedures and Prepared Statements
<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}
if (!$mysqli->query("DROP TABLE IF EXISTS test") ||
!$mysqli->query("CREATE TABLE test(id INT)") ||
!$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)")) {
echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
if (!$mysqli->query("DROP PROCEDURE IF EXISTS p") ||
!$mysqli->query('CREATE PROCEDURE p() READS SQL DATA BEGIN SELECT id FROM test; SELECT id + 1 FROM test; END;')) {
echo "Stored procedure creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
if (!($stmt = $mysqli->prepare("CALL p()"))) {
echo "Prepare failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
if (!$stmt->execute()) {
echo "Execute failed: (" . $stmt->errno . ") " . $stmt->error;
}
do {
if ($res = $stmt->get_result()) {
printf("---\n");
var_dump(mysqli_fetch_all($res));
mysqli_free_result($res);
} else {
if ($stmt->errno) {
echo "Store failed: (" . $stmt->errno . ") " . $stmt->error;
}
}
} while ($stmt->more_results() && $stmt->next_result());
?>
Of course, use of the bind API for fetching is supported as well.
Przykład #5 Stored Procedures and Prepared Statements using bind API
<?php
if (!($stmt = $mysqli->prepare("CALL p()"))) {
echo "Prepare failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
if (!$stmt->execute()) {
echo "Execute failed: (" . $stmt->errno . ") " . $stmt->error;
}
do {
$id_out = NULL;
if (!$stmt->bind_result($id_out)) {
echo "Bind failed: (" . $stmt->errno . ") " . $stmt->error;
}
while ($stmt->fetch()) {
echo "id = $id_out\n";
}
} while ($stmt->more_results() && $stmt->next_result());
?>
See also
- mysqli::query()
- mysqli::multi_query()
- mysqli_result::next-result()
- mysqli_result::more-results()
Multiple Statements
MySQL optionally allows having multiple statements in one statement string. Sending multiple statements at once reduces client-server round trips but requires special handling.
Multiple statements or multi queries must be executed with mysqli_multi_query(). The individual statements of the statement string are separated by semicolon. Then, all result sets returned by the executed statements must be fetched.
The MySQL server allows having statements that do return result sets and statements that do not return result sets in one multiple statement.
Przykład #1 Multiple Statements
<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}
if (!$mysqli->query("DROP TABLE IF EXISTS test") || !$mysqli->query("CREATE TABLE test(id INT)")) {
echo "Table creation failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
$sql = "SELECT COUNT(*) AS _num FROM test; ";
$sql.= "INSERT INTO test(id) VALUES (1); ";
$sql.= "SELECT COUNT(*) AS _num FROM test; ";
if (!$mysqli->multi_query($sql)) {
echo "Multi query failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
do {
if ($res = $mysqli->store_result()) {
var_dump($res->fetch_all(MYSQLI_ASSOC));
$res->free();
}
} while ($mysqli->more_results() && $mysqli->next_result());
?>
Powyższy przykład wyświetli:
array(1) {
[0]=>
array(1) {
["_num"]=>
string(1) "0"
}
}
array(1) {
[0]=>
array(1) {
["_num"]=>
string(1) "1"
}
}
Security considerations
The API functions mysqli_query() and mysqli_real_query() do not set a connection flag necessary for activating multi queries in the server. An extra API call is used for multiple statements to reduce the likeliness of accidental SQL injection attacks. An attacker may try to add statements such as ; DROP DATABASE mysql or ; SELECT SLEEP(999). If the attacker succeeds in adding SQL to the statement string but mysqli_multi_query is not used, the server will not execute the second, injected and malicious SQL statement.
Przykład #2 SQL Injection
<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
$res = $mysqli->query("SELECT 1; DROP TABLE mysql.user");
if (!$res) {
echo "Error executing query: (" . $mysqli->errno . ") " . $mysqli->error;
}
?>
Powyższy przykład wyświetli:
Error executing query: (1064) You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 'DROP TABLE mysql.user' at line 1
Prepared statements
Use of the multiple statement with prepared statements is not supported.
See also
- mysqli::query()
- mysqli::multi_query()
- mysqli_result::next-result()
- mysqli_result::more-results()
API support for transactions
The MySQL server supports transactions depending on the storage engine used. Since MySQL 5.5, the default storage engine is InnoDB. InnoDB has full ACID transaction support.
Transactions can either be controlled using SQL or API calls. It is recommended to use API calls for enabling and disabling the auto commit mode and for committing and rolling back transactions.
Przykład #1 Setting auto commit mode with SQL and through the API
<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}
/* Recommended: using API to control transactional settings */
$mysqli->autocommit(false);
/* Won't be monitored and recognized by the replication and the load balancing plugin */
if (!$mysqli->query('SET AUTOCOMMIT = 0')) {
echo "Query failed: (" . $mysqli->errno . ") " . $mysqli->error;
}
?>
Optional feature packages, such as the replication and load balancing plugin, can easily monitor API calls. The replication plugin offers transaction aware load balancing, if transactions are controlled with API calls. Transaction aware load balancing is not available if SQL statements are used for setting auto commit mode, committing or rolling back a transaction.
Przykład #2 Commit and rollback
<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
$mysqli->autocommit(false);
$mysqli->query("INSERT INTO test(id) VALUES (1)");
$mysqli->rollback();
$mysqli->query("INSERT INTO test(id) VALUES (2)");
$mysqli->commit();
?>
Please note, that the MySQL server cannot roll back all statements. Some statements cause am implicit commit.
See also
- mysqli::autocommit()
- mysqli_result::commit()
- mysqli_result::rollback()
Metadata
A MySQL result set contains metadata. The metadata describes the columns found in the result set. All metadata send by MySQL is accessible through the mysqli interface. The extension performs no or negligible changes to the information it receives. Differences between MySQL server versions are not aligned.
Meta data is access through the mysqli_result interface.
Przykład #1 Accessing result set meta data
<?php
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}
$res = $mysqli->query("SELECT 1 AS _one, 'Hello' AS _two FROM DUAL");
var_dump($res->fetch_fields());
?>
Powyższy przykład wyświetli:
array(2) {
[0]=>
object(stdClass)#3 (13) {
["name"]=>
string(4) "_one"
["orgname"]=>
string(0) ""
["table"]=>
string(0) ""
["orgtable"]=>
string(0) ""
["def"]=>
string(0) ""
["db"]=>
string(0) ""
["catalog"]=>
string(3) "def"
["max_length"]=>
int(1)
["length"]=>
int(1)
["charsetnr"]=>
int(63)
["flags"]=>
int(32897)
["type"]=>
int(8)
["decimals"]=>
int(0)
}
[1]=>
object(stdClass)#4 (13) {
["name"]=>
string(4) "_two"
["orgname"]=>
string(0) ""
["table"]=>
string(0) ""
["orgtable"]=>
string(0) ""
["def"]=>
string(0) ""
["db"]=>
string(0) ""
["catalog"]=>
string(3) "def"
["max_length"]=>
int(5)
["length"]=>
int(5)
["charsetnr"]=>
int(8)
["flags"]=>
int(1)
["type"]=>
int(253)
["decimals"]=>
int(31)
}
}
Prepared statements
Meta data of result sets created using prepared statements are accessed the same way. A suitable mysqli_result handle is returned by mysqli_stmt_result_metadata().
Przykład #2 Prepared statements metadata
<?php
$stmt = $mysqli->prepare("SELECT 1 AS _one, 'Hello' AS _two FROM DUAL");
$stmt->execute();
$res = $stmt->result_metadata();
var_dump($res->fetch_fields());
?>
See also
Instalacja/Konfiguracja
Spis treści
Wymagania
In order to have these functions available, you must compile PHP with support for the mysqli extension.
Informacja:
The mysqli extension is designed to work with MySQL version 4.1.13 or newer, or 5.0.7 or newer. For previous versions, please see the MySQL extension documentation.
Instalacja
By zainstalować rozszerzenie mysqli dla PHP należy użyć opcji konfiguracyjnej --with-mysqli=mysql_config_path/mysql_config , gdzie mysql_config_path wskazuje na ścieżkę dostępu do programu mysql_config, który występuje w wersjach MySQL powyżej 4.1.
Jeśli chcesz zainstalować rozszerzenie mysql razem z rozszerzeniem mysqli musisz użyć tej samej biblioteki klienckiej w celu uniknięcia konfliktów.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Wartość domyślna | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| mysqli.allow_persistent | "1" | PHP_INI_SYSTEM | Dostępna od PHP 5.3.0. |
| mysqli.max_persistent | "-1" | PHP_INI_SYSTEM | Dostępna od PHP 5.3.0. |
| mysqli.max_links | "-1" | PHP_INI_SYSTEM | Dostępna od PHP 5.0.0. |
| mysqli.default_port | "3306" | PHP_INI_ALL | Dostępna od PHP 5.0.0. |
| mysqli.default_socket | NULL | PHP_INI_ALL | Dostępna od PHP 5.0.0. |
| mysqli.default_host | NULL | PHP_INI_ALL | Dostępna od PHP 5.0.0. |
| mysqli.default_user | NULL | PHP_INI_ALL | Dostępna od PHP 5.0.0. |
| mysqli.default_pw | NULL | PHP_INI_ALL | Dostępna od PHP 5.0.0. |
| mysqli.reconnect | "0" | PHP_INI_SYSTEM | Dostępna od PHP 4.3.5. |
| mysqli.allow_local_infile | "1" | PHP_INI_SYSTEM | Dostępna od PHP 5.2.4. |
| mysqli.cache_size | "2000" | PHP_INI_SYSTEM | Dostępna od PHP 5.3.0. |
Aby dowiedzieć się więcej o powyższych definicjach i stałych PHP_INI_*, zobacz rozdział poświęcony zmianom konfiguracji.
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
mysqli.allow_persistentinteger -
Włącza możliwość tworzenia połączeń stałych za pomocą mysqli_connect().
-
mysqli.max_persistentinteger -
Maksymalna liczba połączeń stałych, które można utworzyć. Wartość 0 ustawia nieograniczoną liczbę połączeń stałych.
-
mysqli.max_linksinteger -
Maksymalna liczba połączeń MySQL na proces.
-
mysqli.default_portstring -
Domyślny port TCP używany podczas połączenia do serwera bazy danych, jeśli nie podano innego portu. Jeżeli ta wartość nie zostanie ustawiona, numer portu zostanie pobrany ze zmiennej środowiskowej MYSQL_TCP_PORT, wpisu mysql-tcp w pliku /etc/services lub stałej MYSQL_PORT podanej podczas kompilacji (dokładnie w takim porządku). Systemy Windows używają tylko stałej MYSQL_PORT
-
mysqli.default_socketstring -
Domyślna nazwa gniazda używanego podczas połączenia do lokalnego serwera bazy danych, jeśli nie została podana inna wartość.
-
mysqli.default_hoststring -
Domyślna nazwa hosta używana podczas połączenia do serwera bazy danych, jeśli nie została podana inna wartość. Nie działa w trybie bezpiecznym.
-
mysqli.default_userstring -
Domyślna nazwa użytkownika używana podczas połączenia do serwera bazy danych, jeśli nie została podana inna nazwa. Nie działa w trybie bezpiecznym.
-
mysqli.default_pwstring -
Domyślne hasło używane podczas połączenia do serwera bazy danych, jeśli nie zostało podane inne hasło. Nie działa w trybie bezpiecznym.
-
mysqli.reconnectinteger -
Automatycznie ponownie nawiązuje połączenie, jeśli zostanie zerwane.
-
mysqli.allow_local_infileinteger -
-
mysqli.cache_sizeinteger -
Dostępna tylko z mysqlnd.
Użytkownicy nie mogą ustawić MYSQL_OPT_READ_TIMEOUT przez wywołanie API, ani w konfiguracji wykonawczej. Proszę zwrócić uwagę na to, że jeśli ustawienie było możliwe, to są różnice w interpretacji przez libmysql i przez potoki wartości MYSQL_OPT_READ_TIMEOUT.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
The mysqli Extension and Persistent Connections
Persistent connection support was introduced in PHP 5.3 for the mysqli extension. Support was already present in PDO MYSQL and ext/mysql. The idea behind persistent connections is that a connection between a client process and a database can be reused by a client process, rather than being created and destroyed multiple times. This reduces the overhead of creating fresh connections every time one is required, as unused connections are cached and ready to be reused.
Unlike the mysql extension, mysqli does not provide a separate function for opening persistent connections. To open a persistent connection you must prepend p: to the hostname when connecting.
The problem with persistent connections is that they can be left in unpredictable states by clients. For example, a table lock might be activated before a client terminates unexpectedly. A new client process reusing this persistent connection will get the connection "as is". Any cleanup would need to be done by the new client process before it could make good use of the persistent connection, increasing the burden on the programmer.
The persistent connection of the mysqli extension however provides built-in cleanup handling code. The cleanup carried out by mysqli includes:
-
Rollback active transactions
-
Close and drop temporary tables
-
Unlock tables
-
Reset session variables
-
Close prepared statements (always happens with PHP)
-
Close handler
-
Release locks acquired with GET_LOCK()
This ensures that persistent connections are in a clean state on return from the connection pool, before the client process uses them.
The mysqli extension does this cleanup by automatically calling the C-API function mysql_change_user().
The automatic cleanup feature has advantages and disadvantages though. The advantage is that the programmer no longer needs to worry about adding cleanup code, as it is called automatically. However, the disadvantage is that the code could potentially be a little slower, as the code to perform the cleanup needs to run each time a connection is returned from the connection pool.
It is possible to switch off the automatic cleanup code, by compiling
PHP with
MYSQLI_NO_CHANGE_USER_ON_PCONNECT
defined.
Informacja:
The mysqli extension supports persistent connections when using either MySQL Native Driver or MySQL Client Library.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
-
MYSQLI_READ_DEFAULT_GROUP -
Read options from the named group from my.cnf or the file specified with
MYSQLI_READ_DEFAULT_FILE -
MYSQLI_READ_DEFAULT_FILE -
Read options from the named option file instead of from my.cnf
-
MYSQLI_OPT_CONNECT_TIMEOUT -
Connect timeout in seconds
-
MYSQLI_OPT_LOCAL_INFILE -
Enables command LOAD LOCAL INFILE
-
MYSQLI_INIT_COMMAND -
Command to execute when connecting to MySQL server. Will automatically be re-executed when reconnecting.
-
MYSQLI_CLIENT_SSL -
Use SSL (encrypted protocol). This option should not be set by application programs; it is set internally in the MySQL client library
-
MYSQLI_CLIENT_COMPRESS -
Use compression protocol
-
MYSQLI_CLIENT_INTERACTIVE -
Allow interactive_timeout seconds (instead of wait_timeout seconds) of inactivity before closing the connection. The client's session wait_timeout variable will be set to the value of the session interactive_timeout variable.
-
MYSQLI_CLIENT_IGNORE_SPACE -
Allow spaces after function names. Makes all functions names reserved words.
-
MYSQLI_CLIENT_NO_SCHEMA -
Don't allow the db_name.tbl_name.col_name syntax.
-
MYSQLI_CLIENT_MULTI_QUERIES -
Allows multiple semicolon-delimited queries in a single mysqli_query() call.
-
MYSQLI_STORE_RESULT -
For using buffered resultsets
-
MYSQLI_USE_RESULT -
For using unbuffered resultsets
-
MYSQLI_ASSOC -
Columns are returned into the array having the fieldname as the array index.
-
MYSQLI_NUM -
Columns are returned into the array having an enumerated index.
-
MYSQLI_BOTH -
Columns are returned into the array having both a numerical index and the fieldname as the associative index.
-
MYSQLI_NOT_NULL_FLAG -
Indicates that a field is defined as NOT NULL
-
MYSQLI_PRI_KEY_FLAG -
Field is part of a primary index
-
MYSQLI_UNIQUE_KEY_FLAG -
Field is part of a unique index.
-
MYSQLI_MULTIPLE_KEY_FLAG -
Field is part of an index.
-
MYSQLI_BLOB_FLAG -
Field is defined as BLOB
-
MYSQLI_UNSIGNED_FLAG -
Field is defined as UNSIGNED
-
MYSQLI_ZEROFILL_FLAG -
Field is defined as ZEROFILL
-
MYSQLI_AUTO_INCREMENT_FLAG -
Field is defined as AUTO_INCREMENT
-
MYSQLI_TIMESTAMP_FLAG -
Field is defined as TIMESTAMP
-
MYSQLI_SET_FLAG -
Field is defined as SET
-
MYSQLI_NUM_FLAG -
Field is defined as NUMERIC
-
MYSQLI_PART_KEY_FLAG -
Field is part of an multi-index
-
MYSQLI_GROUP_FLAG -
Field is part of GROUP BY
-
MYSQLI_TYPE_DECIMAL -
Field is defined as DECIMAL
-
MYSQLI_TYPE_NEWDECIMAL -
Precision math DECIMAL or NUMERIC field (MySQL 5.0.3 and up)
-
MYSQLI_TYPE_BIT -
Field is defined as BIT (MySQL 5.0.3 and up)
-
MYSQLI_TYPE_TINY -
Field is defined as TINYINT
-
MYSQLI_TYPE_SHORT -
Field is defined as SMALLINT
-
MYSQLI_TYPE_LONG -
Field is defined as INT
-
MYSQLI_TYPE_FLOAT -
Field is defined as FLOAT
-
MYSQLI_TYPE_DOUBLE -
Field is defined as DOUBLE
-
MYSQLI_TYPE_NULL -
Field is defined as DEFAULT NULL
-
MYSQLI_TYPE_TIMESTAMP -
Field is defined as TIMESTAMP
-
MYSQLI_TYPE_LONGLONG -
Field is defined as BIGINT
-
MYSQLI_TYPE_INT24 -
Field is defined as MEDIUMINT
-
MYSQLI_TYPE_DATE -
Field is defined as DATE
-
MYSQLI_TYPE_TIME -
Field is defined as TIME
-
MYSQLI_TYPE_DATETIME -
Field is defined as DATETIME
-
MYSQLI_TYPE_YEAR -
Field is defined as YEAR
-
MYSQLI_TYPE_NEWDATE -
Field is defined as DATE
-
MYSQLI_TYPE_INTERVAL -
Field is defined as INTERVAL
-
MYSQLI_TYPE_ENUM -
Field is defined as ENUM
-
MYSQLI_TYPE_SET -
Field is defined as SET
-
MYSQLI_TYPE_TINY_BLOB -
Field is defined as TINYBLOB
-
MYSQLI_TYPE_MEDIUM_BLOB -
Field is defined as MEDIUMBLOB
-
MYSQLI_TYPE_LONG_BLOB -
Field is defined as LONGBLOB
-
MYSQLI_TYPE_BLOB -
Field is defined as BLOB
-
MYSQLI_TYPE_VAR_STRING -
Field is defined as VARCHAR
-
MYSQLI_TYPE_STRING -
Field is defined as STRING
-
MYSQLI_TYPE_CHAR -
Field is defined as CHAR
-
MYSQLI_TYPE_GEOMETRY -
Field is defined as GEOMETRY
-
MYSQLI_NEED_DATA -
More data available for bind variable
-
MYSQLI_NO_DATA -
No more data available for bind variable
-
MYSQLI_DATA_TRUNCATED -
Data truncation occurred. Available since PHP 5.1.0 and MySQL 5.0.5.
-
MYSQLI_ENUM_FLAG -
Field is defined as ENUM. Available since PHP 5.3.0.
-
MYSQLI_CURSOR_TYPE_FOR_UPDATE -
-
MYSQLI_CURSOR_TYPE_NO_CURSOR -
-
MYSQLI_CURSOR_TYPE_READ_ONLY -
-
MYSQLI_CURSOR_TYPE_SCROLLABLE -
-
MYSQLI_STMT_ATTR_CURSOR_TYPE -
-
MYSQLI_STMT_ATTR_PREFETCH_ROWS -
-
MYSQLI_STMT_ATTR_UPDATE_MAX_LENGTH -
-
MYSQLI_SET_CHARSET_NAME -
-
MYSQLI_REPORT_INDEX -
Report if no index or bad index was used in a query.
-
MYSQLI_REPORT_ERROR -
Report errors from mysqli function calls.
-
MYSQLI_REPORT_STRICT -
Throw a mysqli_sql_exception for errors instead of warnings.
-
MYSQLI_REPORT_ALL -
Set all options on (report all).
-
MYSQLI_REPORT_OFF -
Turns reporting off.
-
MYSQLI_DEBUG_TRACE_ENABLED -
Is set to 1 if mysqli_debug() functionality is enabled.
-
MYSQLI_SERVER_QUERY_NO_GOOD_INDEX_USED -
-
MYSQLI_SERVER_QUERY_NO_INDEX_USED -
-
MYSQLI_REFRESH_GRANT -
Refreshes the grant tables.
-
MYSQLI_REFRESH_LOG -
Flushes the logs, like executing the FLUSH LOGS SQL statement.
-
MYSQLI_REFRESH_TABLES -
Flushes the table cache, like executing the FLUSH TABLES SQL statement.
-
MYSQLI_REFRESH_HOSTS -
Flushes the host cache, like executing the FLUSH HOSTS SQL statement.
-
MYSQLI_REFRESH_STATUS -
Reset the status variables, like executing the FLUSH STATUS SQL statement.
-
MYSQLI_REFRESH_THREADS -
Flushes the thread cache.
-
MYSQLI_REFRESH_SLAVE -
On a slave replication server: resets the master server information, and restarts the slave. Like executing the RESET SLAVE SQL statement.
-
MYSQLI_REFRESH_MASTER -
On a master replication server: removes the binary log files listed in the binary log index, and truncates the index file. Like executing the RESET MASTER SQL statement.
Notes
Some implementation notes:
-
Support was added for MYSQL_TYPE_GEOMETRY to the MySQLi extension in PHP 5.3.
-
Note there are different internal implementations within libmysql and mysqlnd for handling columns of type MYSQL_TYPE_GEOMETRY. Generally speaking, mysqlnd will allocate significantly less memory. For example, if there is a POINT column in a result set, libmysql may pre-allocate up to 4GB of RAM although less than 50 bytes are needed for holding a POINT column in memory. Memory allocation is much lower, less than 50 bytes, if using mysqlnd.
The MySQLi Extension Function Summary
| mysqli Class | |||
|---|---|---|---|
| OOP Interface | Procedural Interface | Alias (Do not use) | Description |
| Properties | |||
| $mysqli::affected_rows | mysqli_affected_rows() | N/A | Gets the number of affected rows in a previous MySQL operation |
| $mysqli::client_info | mysqli_get_client_info() | N/A | Returns the MySQL client version as a string |
| $mysqli::client_version | mysqli_get_client_version() | N/A | Returns MySQL client version info as an integer |
| $mysqli::connect_errno | mysqli_connect_errno() | N/A | Returns the error code from last connect call |
| $mysqli::connect_error | mysqli_connect_error() | N/A | Returns a string description of the last connect error |
| $mysqli::errno | mysqli_errno() | N/A | Returns the error code for the most recent function call |
| $mysqli::error | mysqli_error() | N/A | Returns a string description of the last error |
| $mysqli::field_count | mysqli_field_count() | N/A | Returns the number of columns for the most recent query |
| $mysqli::host_info | mysqli_get_host_info() | N/A | Returns a string representing the type of connection used |
| $mysqli::protocol_version | mysqli_get_proto_info() | N/A | Returns the version of the MySQL protocol used |
| $mysqli::server_info | mysqli_get_server_info() | N/A | Returns the version of the MySQL server |
| $mysqli::server_version | mysqli_get_server_version() | N/A | Returns the version of the MySQL server as an integer |
| $mysqli::info | mysqli_info() | N/A | Retrieves information about the most recently executed query |
| $mysqli::insert_id | mysqli_insert_id() | N/A | Returns the auto generated id used in the last query |
| $mysqli::sqlstate | mysqli_sqlstate() | N/A | Returns the SQLSTATE error from previous MySQL operation |
| $mysqli::warning_count | mysqli_warning_count() | N/A | Returns the number of warnings from the last query for the given link |
| Methods | |||
| mysqli::autocommit() | mysqli_autocommit() | N/A | Turns on or off auto-commiting database modifications |
| mysqli::change_user() | mysqli_change_user() | N/A | Changes the user of the specified database connection |
| mysqli::character_set_name(), mysqli::client_encoding | mysqli_character_set_name() | mysqli_client_encoding() | Returns the default character set for the database connection |
| mysqli::close() | mysqli_close() | N/A | Closes a previously opened database connection |
| mysqli::commit() | mysqli_commit() | N/A | Commits the current transaction |
| mysqli::__construct() | mysqli_connect() | N/A | Open a new connection to the MySQL server [Note: static (i.e. class) method] |
| mysqli::debug() | mysqli_debug() | N/A | Performs debugging operations |
| mysqli::dump_debug_info() | mysqli_dump_debug_info() | N/A | Dump debugging information into the log |
| mysqli::get_charset() | mysqli_get_charset() | N/A | Returns a character set object |
| mysqli::get_connection_stats() | mysqli_get_connection_stats() | N/A | Returns client connection statistics. Dostępna tylko z mysqlnd. |
| mysqli::get_client_info() | mysqli_get_client_info() | N/A | Returns the MySQL client version as a string |
| mysqli::get_client_stats() | mysqli_get_client_stats() | N/A | Returns client per-process statistics. Dostępna tylko z mysqlnd. |
| mysqli::get_cache_stats() | mysqli_get_cache_stats() | N/A | Returns client Zval cache statistics. Dostępna tylko z mysqlnd. |
| mysqli::get_server_info() | mysqli_get_server_info() | N/A | NOT DOCUMENTED |
| mysqli::get_warnings() | mysqli_get_warnings() | N/A | NOT DOCUMENTED |
| mysqli::init() | mysqli_init() | N/A | Initializes MySQLi and returns a resource for use with mysqli_real_connect. [Not called on an object, as it returns a $mysqli object.] |
| mysqli::kill() | mysqli_kill() | N/A | Asks the server to kill a MySQL thread |
| mysqli::more_results() | mysqli_more_results() | N/A | Check if there are any more query results from a multi query |
| mysqli::multi_query() | mysqli_multi_query() | N/A | Performs a query on the database |
| mysqli::next_result() | mysqli_next_result() | N/A | Prepare next result from multi_query |
| mysqli::options() | mysqli_options() | mysqli_set_opt() | Set options |
| mysqli::ping() | mysqli_ping() | N/A | Pings a server connection, or tries to reconnect if the connection has gone down |
| mysqli::prepare() | mysqli_prepare() | N/A | Prepare an SQL statement for execution |
| mysqli::query() | mysqli_query() | N/A | Performs a query on the database |
| mysqli::real_connect() | mysqli_real_connect() | N/A | Opens a connection to a mysql server |
| mysqli::real_escape_string(), mysqli::escape_string() | mysqli_real_escape_string() | mysqli_escape_string() | Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection |
| mysqli::real_query() | mysqli_real_query() | N/A | Execute an SQL query |
| mysqli::refresh() | mysqli_refresh() | N/A | Flushes tables or caches, or resets the replication server information |
| mysqli::rollback() | mysqli_rollback() | N/A | Rolls back current transaction |
| mysqli::select_db() | mysqli_select_db() | N/A | Selects the default database for database queries |
| mysqli::set_charset() | mysqli_set_charset() | N/A | Sets the default client character set |
| mysqli::set_local_infile_default() | mysqli_set_local_infile_default() | N/A | Unsets user defined handler for load local infile command |
| mysqli::set_local_infile_handler() | mysqli_set_local_infile_handler() | N/A | Set callback function for LOAD DATA LOCAL INFILE command |
| mysqli::ssl_set() | mysqli_ssl_set() | N/A | Used for establishing secure connections using SSL |
| mysqli::stat() | mysqli_stat() | N/A | Gets the current system status |
| mysqli::stmt_init() | mysqli_stmt_init() | N/A | Initializes a statement and returns an object for use with mysqli_stmt_prepare |
| mysqli::store_result() | mysqli_store_result() | N/A | Transfers a result set from the last query |
| mysqli::thread_id() | mysqli_thread_id() | N/A | Returns the thread ID for the current connection |
| mysqli::thread_safe() | mysqli_thread_safe() | N/A | Returns whether thread safety is given or not |
| mysqli::use_result() | mysqli_use_result() | N/A | Initiate a result set retrieval |
| MySQL_STMT | |||
|---|---|---|---|
| OOP Interface | Procedural Interface | Alias (Do not use) | Description |
| Properties | |||
| $mysqli_stmt::affected_rows | mysqli_stmt_affected_rows() | N/A | Returns the total number of rows changed, deleted, or inserted by the last executed statement |
| $mysqli_stmt::errno | mysqli_stmt_errno() | N/A | Returns the error code for the most recent statement call |
| $mysqli_stmt::error | mysqli_stmt_error() | N/A | Returns a string description for last statement error |
| $mysqli_stmt::field_count | mysqli_stmt_field_count() | N/A | Returns the number of field in the given statement - not documented |
| $mysqli_stmt::insert_id | mysqli_stmt_insert_id() | N/A | Get the ID generated from the previous INSERT operation |
| $mysqli_stmt::num_rows | mysqli_stmt_num_rows() | N/A | Return the number of rows in statements result set |
| $mysqli_stmt::param_count | mysqli_stmt_param_count() | mysqli_param_count() | Returns the number of parameter for the given statement |
| $mysqli_stmt::sqlstate | mysqli_stmt_sqlstate() | N/A | Returns SQLSTATE error from previous statement operation |
| Methods | |||
| mysqli_stmt::attr_get() | mysqli_stmt_attr_get() | N/A | Used to get the current value of a statement attribute |
| mysqli_stmt::attr_set() | mysqli_stmt_attr_set() | N/A | Used to modify the behavior of a prepared statement |
| mysqli_stmt::bind_param() | mysqli_stmt_bind_param() | mysqli_bind_param() | Binds variables to a prepared statement as parameters |
| mysqli_stmt::bind_result() | mysqli_stmt_bind_result() | mysqli_bind_result() | Binds variables to a prepared statement for result storage |
| mysqli_stmt::close() | mysqli_stmt_close() | N/A | Closes a prepared statement |
| mysqli_stmt::data_seek() | mysqli_stmt_data_seek() | N/A | Seeks to an arbitrary row in statement result set |
| mysqli_stmt::execute() | mysqli_stmt_execute() | mysqli_execute() | Executes a prepared Query |
| mysqli_stmt::fetch() | mysqli_stmt_fetch() | mysqli_fetch() | Fetch results from a prepared statement into the bound variables |
| mysqli_stmt::free_result() | mysqli_stmt_free_result() | N/A | Frees stored result memory for the given statement handle |
| mysqli_stmt::get_result() | mysqli_stmt_get_result() | N/A | Gets a result set from a prepared statement. Dostępna tylko z mysqlnd. |
| mysqli_stmt::get_warnings() | mysqli_stmt_get_warnings() | N/A | NOT DOCUMENTED |
| $mysqli_stmt::more_results() | mysqli_stmt_more_results() | N/A | NOT DOCUMENTED Dostępna tylko z mysqlnd. |
| $mysqli_stmt::next_result() | mysqli_stmt_next_result() | N/A | NOT DOCUMENTED Dostępna tylko z mysqlnd. |
| mysqli_stmt::num_rows() | mysqli_stmt_num_rows() | N/A | See also property $mysqli_stmt::num_rows |
| mysqli_stmt::prepare() | mysqli_stmt_prepare() | N/A | Prepare an SQL statement for execution |
| mysqli_stmt::reset() | mysqli_stmt_reset() | N/A | Resets a prepared statement |
| mysqli_stmt::result_metadata() | mysqli_stmt_result_metadata() | mysqli_get_metadata() | Returns result set metadata from a prepared statement |
| mysqli_stmt::send_long_data() | mysqli_stmt_send_long_data() | mysqli_send_long_data() | Send data in blocks |
| mysqli_stmt::store_result() | mysqli_stmt_store_result() | N/A | Transfers a result set from a prepared statement |
| mysqli_result | |||
|---|---|---|---|
| OOP Interface | Procedural Interface | Alias (Do not use) | Description |
| Properties | |||
| $mysqli_result::current_field | mysqli_field_tell() | N/A | Get current field offset of a result pointer |
| $mysqli_result::field_count | mysqli_num_fields() | N/A | Get the number of fields in a result |
| $mysqli_result::lengths | mysqli_fetch_lengths() | N/A | Returns the lengths of the columns of the current row in the result set |
| $mysqli_result::num_rows | mysqli_num_rows() | N/A | Gets the number of rows in a result |
| Methods | |||
| mysqli_result::data_seek() | mysqli_data_seek() | N/A | Adjusts the result pointer to an arbitary row in the result |
| mysqli_result::fetch_all() | mysqli_fetch_all() | N/A | Fetches all result rows and returns the result set as an associative array, a numeric array, or both. Dostępna tylko z mysqlnd. |
| mysqli_result::fetch_array() | mysqli_fetch_array() | N/A | Fetch a result row as an associative, a numeric array, or both |
| mysqli_result::fetch_assoc() | mysqli_fetch_assoc() | N/A | Fetch a result row as an associative array |
| mysqli_result::fetch_field_direct() | mysqli_fetch_field_direct() | N/A | Fetch meta-data for a single field |
| mysqli_result::fetch_field() | mysqli_fetch_field() | N/A | Returns the next field in the result set |
| mysqli_result::fetch_fields() | mysqli_fetch_fields() | N/A | Returns an array of objects representing the fields in a result set |
| mysqli_result::fetch_object() | mysqli_fetch_object() | N/A | Returns the current row of a result set as an object |
| mysqli_result::fetch_row() | mysqli_fetch_row() | N/A | Get a result row as an enumerated array |
| mysqli_result::field_seek() | mysqli_field_seek() | N/A | Set result pointer to a specified field offset |
| mysqli_result::free(), mysqli_result::close, mysqli_result::free_result | mysqli_free_result() | N/A | Frees the memory associated with a result |
| MySQL_Driver | |||
|---|---|---|---|
| OOP Interface | Procedural Interface | Alias (Do not use) | Description |
| Properties | |||
| N/A | |||
| Methods | |||
| mysqli_driver::embedded_server_end() | mysqli_embedded_server_end() | N/A | NOT DOCUMENTED |
| mysqli_driver::embedded_server_start() | mysqli_embedded_server_start() | N/A | NOT DOCUMENTED |
Informacja:
Alias functions are provided for backward compatibility purposes only. Do not use them in new projects.
The mysqli class
(PHP 5)
Wstęp
Represents a connection between PHP and a MySQL database.
Krótki opis klasy
$host
[, string $username
[, string $passwd
[, string $dbname
[, int $port
[, string $socket
[, int $flags
]]]]]]] )mysqli::$affected_rows
mysqli_affected_rows
(PHP 5)
mysqli::$affected_rows -- mysqli_affected_rows — Gets the number of affected rows in a previous MySQL operation
Opis
Styl obiektowy
Styl proceduralny
Returns the number of rows affected by the last INSERT, UPDATE, REPLACE or DELETE query.
For SELECT statements mysqli_affected_rows() works like mysqli_num_rows().
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
An integer greater than zero indicates the number of rows affected or retrieved. Zero indicates that no records where updated for an UPDATE statement, no rows matched the WHERE clause in the query or that no query has yet been executed. -1 indicates that the query returned an error.
Informacja:
If the number of affected rows is greater than maximal int value, the number of affected rows will be returned as a string.
Przykłady
Przykład #1 $mysqli->affected_rows example
Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* Insert rows */
$mysqli->query("CREATE TABLE Language SELECT * from CountryLanguage");
printf("Affected rows (INSERT): %d\n", $mysqli->affected_rows);
$mysqli->query("ALTER TABLE Language ADD Status int default 0");
/* update rows */
$mysqli->query("UPDATE Language SET Status=1 WHERE Percentage > 50");
printf("Affected rows (UPDATE): %d\n", $mysqli->affected_rows);
/* delete rows */
$mysqli->query("DELETE FROM Language WHERE Percentage < 50");
printf("Affected rows (DELETE): %d\n", $mysqli->affected_rows);
/* select all rows */
$result = $mysqli->query("SELECT CountryCode FROM Language");
printf("Affected rows (SELECT): %d\n", $mysqli->affected_rows);
$result->close();
/* Delete table Language */
$mysqli->query("DROP TABLE Language");
/* close connection */
$mysqli->close();
?>
Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
if (!$link) {
printf("Can't connect to localhost. Error: %s\n", mysqli_connect_error());
exit();
}
/* Insert rows */
mysqli_query($link, "CREATE TABLE Language SELECT * from CountryLanguage");
printf("Affected rows (INSERT): %d\n", mysqli_affected_rows($link));
mysqli_query($link, "ALTER TABLE Language ADD Status int default 0");
/* update rows */
mysqli_query($link, "UPDATE Language SET Status=1 WHERE Percentage > 50");
printf("Affected rows (UPDATE): %d\n", mysqli_affected_rows($link));
/* delete rows */
mysqli_query($link, "DELETE FROM Language WHERE Percentage < 50");
printf("Affected rows (DELETE): %d\n", mysqli_affected_rows($link));
/* select all rows */
$result = mysqli_query($link, "SELECT CountryCode FROM Language");
printf("Affected rows (SELECT): %d\n", mysqli_affected_rows($link));
mysqli_free_result($result);
/* Delete table Language */
mysqli_query($link, "DROP TABLE Language");
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Affected rows (INSERT): 984 Affected rows (UPDATE): 168 Affected rows (DELETE): 815 Affected rows (SELECT): 169
Zobacz też:
- mysqli_num_rows() - Gets the number of rows in a result
- mysqli_info() - Retrieves information about the most recently executed query
mysqli::autocommit
mysqli_autocommit
(PHP 5)
mysqli::autocommit -- mysqli_autocommit — Turns on or off auto-commiting database modifications
Opis
Styl obiektowy
$mode
)Styl proceduralny
Turns on or off auto-commit mode on queries for the database connection.
To determine the current state of autocommit use the SQL command SELECT @@autocommit.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
-
mode -
Whether to turn on auto-commit or not.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Notatki
Informacja:
This function doesn't work with non transactional table types (like MyISAM or ISAM).
Przykłady
Przykład #1 mysqli::autocommit() example
Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* turn autocommit on */
$mysqli->autocommit(TRUE);
if ($result = $mysqli->query("SELECT @@autocommit")) {
$row = $result->fetch_row();
printf("Autocommit is %s\n", $row[0]);
$result->free();
}
/* close connection */
$mysqli->close();
?>
Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
if (!$link) {
printf("Can't connect to localhost. Error: %s\n", mysqli_connect_error());
exit();
}
/* turn autocommit on */
mysqli_autocommit($link, TRUE);
if ($result = mysqli_query($link, "SELECT @@autocommit")) {
$row = mysqli_fetch_row($result);
printf("Autocommit is %s\n", $row[0]);
mysqli_free_result($result);
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Autocommit is 1
Zobacz też:
- mysqli_commit() - Commits the current transaction
- mysqli_rollback() - Rolls back current transaction
mysqli::change_user
mysqli_change_user
(PHP 5)
mysqli::change_user -- mysqli_change_user — Changes the user of the specified database connection
Opis
Styl obiektowy
$user
, string $password
, string $database
)Styl proceduralny
Changes the user of the specified database connection and sets the current database.
In order to successfully change users a valid username and
password parameters must be provided and that user must have
sufficient permissions to access the desired database. If for any reason authorization
fails, the current user authentication will remain.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
-
user -
The MySQL user name.
-
password -
The MySQL password.
-
database -
The database to change to.
If desired, the
NULLvalue may be passed resulting in only changing the user and not selecting a database. To select a database in this case use the mysqli_select_db() function.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Notatki
Informacja:
Using this command will always cause the current database connection to behave as if was a completely new database connection, regardless of if the operation was completed successfully. This reset includes performing a rollback on any active transactions, closing all temporary tables, and unlocking all locked tables.
Przykłady
Przykład #1 mysqli::change_user() example
Styl obiektowy
<?php
/* connect database test */
$mysqli = new mysqli("localhost", "my_user", "my_password", "test");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* Set Variable a */
$mysqli->query("SET @a:=1");
/* reset all and select a new database */
$mysqli->change_user("my_user", "my_password", "world");
if ($result = $mysqli->query("SELECT DATABASE()")) {
$row = $result->fetch_row();
printf("Default database: %s\n", $row[0]);
$result->close();
}
if ($result = $mysqli->query("SELECT @a")) {
$row = $result->fetch_row();
if ($row[0] === NULL) {
printf("Value of variable a is NULL\n");
}
$result->close();
}
/* close connection */
$mysqli->close();
?>
Styl proceduralny
<?php
/* connect database test */
$link = mysqli_connect("localhost", "my_user", "my_password", "test");
/* check connection */
if (!$link) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* Set Variable a */
mysqli_query($link, "SET @a:=1");
/* reset all and select a new database */
mysqli_change_user($link, "my_user", "my_password", "world");
if ($result = mysqli_query($link, "SELECT DATABASE()")) {
$row = mysqli_fetch_row($result);
printf("Default database: %s\n", $row[0]);
mysqli_free_result($result);
}
if ($result = mysqli_query($link, "SELECT @a")) {
$row = mysqli_fetch_row($result);
if ($row[0] === NULL) {
printf("Value of variable a is NULL\n");
}
mysqli_free_result($result);
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Default database: world Value of variable a is NULL
Zobacz też:
- mysqli_connect() - Alias dla mysqli::__construct
- mysqli_select_db() - Selects the default database for database queries
mysqli::character_set_name
mysqli_character_set_name
(PHP 5)
mysqli::character_set_name -- mysqli_character_set_name — Returns the default character set for the database connection
Opis
Styl obiektowy
Styl proceduralny
Returns the current character set for the database connection.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
The default character set for the current connection
Przykłady
Przykład #1 mysqli::character_set_name() example
Styl obiektowy
<?php
/* Open a connection */
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* Print current character set */
$charset = $mysqli->character_set_name();
printf ("Current character set is %s\n", $charset);
$mysqli->close();
?>
Styl proceduralny
<?php
/* Open a connection */
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (!$link) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* Print current character set */
$charset = mysqli_character_set_name($link);
printf ("Current character set is %s\n",$charset);
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Current character set is latin1_swedish_ci
Zobacz też:
- mysqli_client_encoding() - Alias of mysqli_character_set_name
- mysqli_real_escape_string() - Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection
mysqli::$client_info
mysqli_get_client_info
(PHP 5)
mysqli::$client_info -- mysqli_get_client_info — Returns the MySQL client version as a string
Opis
Styl obiektowy
Styl proceduralny
Returns a string that represents the MySQL client library version.
Zwracane wartości
A string that represents the MySQL client library version
Przykłady
Przykład #1 mysqli_get_client_info
<?php
/* We don't need a connection to determine
the version of mysql client library */
printf("Client library version: %s\n", mysqli_get_client_info());
?>
Zobacz też:
- mysqli_get_client_version() - Get MySQL client info
- mysqli_get_server_info() - Returns the version of the MySQL server
- mysqli_get_server_version() - Returns the version of the MySQL server as an integer
mysqli::$client_version
mysqli_get_client_version
(PHP 5)
mysqli::$client_version -- mysqli_get_client_version — Get MySQL client info
Opis
Styl obiektowy
Styl proceduralny
Returns client version number as an integer.
Zwracane wartości
A number that represents the MySQL client library version in format: main_version*10000 + minor_version *100 + sub_version. For example, 4.1.0 is returned as 40100.
This is useful to quickly determine the version of the client library to know if some capability exists.
Przykłady
Przykład #1 mysqli_get_client_version
<?php
/* We don't need a connection to determine
the version of mysql client library */
printf("Client library version: %d\n", mysqli_get_client_version());
?>
Zobacz też:
- mysqli_get_client_info() - Returns the MySQL client version as a string
- mysqli_get_server_info() - Returns the version of the MySQL server
- mysqli_get_server_version() - Returns the version of the MySQL server as an integer
mysqli::close
mysqli_close
(PHP 5)
mysqli::close -- mysqli_close — Closes a previously opened database connection
Opis
Styl obiektowy
Styl proceduralny
Closes a previously opened database connection.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
See mysqli_connect().
Zobacz też:
- mysqli_connect() - Alias dla mysqli::__construct
- mysqli_init() - Initializes MySQLi and returns a resource for use with mysqli_real_connect()
- mysqli_real_connect() - Opens a connection to a mysql server
mysqli::commit
mysqli_commit
(PHP 5)
mysqli::commit -- mysqli_commit — Commits the current transaction
Opis
Styl obiektowy
Styl proceduralny
Commits the current transaction for the database connection.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 mysqli::commit() example
Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$mysqli->query("CREATE TABLE Language LIKE CountryLanguage");
/* set autocommit to off */
$mysqli->autocommit(FALSE);
/* Insert some values */
$mysqli->query("INSERT INTO Language VALUES ('DEU', 'Bavarian', 'F', 11.2)");
$mysqli->query("INSERT INTO Language VALUES ('DEU', 'Swabian', 'F', 9.4)");
/* commit transaction */
$mysqli->commit();
/* drop table */
$mysqli->query("DROP TABLE Language");
/* close connection */
$mysqli->close();
?>
Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "test");
/* check connection */
if (!$link) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* set autocommit to off */
mysqli_autocommit($link, FALSE);
mysqli_query($link, "CREATE TABLE Language LIKE CountryLanguage");
/* Insert some values */
mysqli_query($link, "INSERT INTO Language VALUES ('DEU', 'Bavarian', 'F', 11.2)");
mysqli_query($link, "INSERT INTO Language VALUES ('DEU', 'Swabian', 'F', 9.4)");
/* commit transaction */
mysqli_commit($link);
/* close connection */
mysqli_close($link);
?>
Zobacz też:
- mysqli_autocommit() - Turns on or off auto-commiting database modifications
- mysqli_rollback() - Rolls back current transaction
mysqli::$connect_errno
mysqli_connect_errno
(PHP 5)
mysqli::$connect_errno -- mysqli_connect_errno — Returns the error code from last connect call
Opis
Styl obiektowy
Styl proceduralny
Returns the last error code number from the last call to mysqli_connect().
Informacja:
Client error message numbers are listed in the MySQL errmsg.h header file, server error message numbers are listed in mysqld_error.h. In the MySQL source distribution you can find a complete list of error messages and error numbers in the file Docs/mysqld_error.txt.
Zwracane wartości
An error code value for the last call to mysqli_connect(), if it failed. zero means no error occurred.
Przykłady
Przykład #1 $mysqli->connect_errno example
Styl obiektowy
<?php
$mysqli = @new mysqli('localhost', 'fake_user', 'my_password', 'my_db');
if ($mysqli->connect_errno) {
die('Connect Error: ' . $mysqli->connect_errno);
}
?>
Styl proceduralny
<?php
$link = @mysqli_connect('localhost', 'fake_user', 'my_password', 'my_db');
if (!$link) {
die('Connect Error: ' . mysqli_connect_errno());
}
?>
Powyższe przykłady wyświetlą:
Connect Error: 1045
Zobacz też:
- mysqli_connect() - Alias dla mysqli::__construct
- mysqli_connect_error() - Returns a string description of the last connect error
- mysqli_errno() - Returns the error code for the most recent function call
- mysqli_error() - Returns a string description of the last error
- mysqli_sqlstate() - Returns the SQLSTATE error from previous MySQL operation
mysqli::$connect_error
mysqli_connect_error
(PHP 5)
mysqli::$connect_error -- mysqli_connect_error — Returns a string description of the last connect error
Opis
Styl obiektowy
Styl proceduralny
Returns the last error message string from the last call to mysqli_connect().
Zwracane wartości
A string that describes the error. NULL is returned if no error occurred.
Przykłady
Przykład #1 $mysqli->connect_error example
Styl obiektowy
<?php
$mysqli = @new mysqli('localhost', 'fake_user', 'my_password', 'my_db');
// Works as of PHP 5.2.9 and 5.3.0.
if ($mysqli->connect_error) {
die('Connect Error: ' . $mysqli->connect_error);
}
?>
Styl proceduralny
<?php
$link = @mysqli_connect('localhost', 'fake_user', 'my_password', 'my_db');
if (!$link) {
die('Connect Error: ' . mysqli_connect_error());
}
?>
Powyższe przykłady wyświetlą:
Connect Error: Access denied for user 'fake_user'@'localhost' (using password: YES)
Notatki
The mysqli->connect_error property only works properly as of PHP versions 5.2.9 and 5.3.0. Use the mysqli_connect_error() function if compatibility with earlier PHP versions is required.
Zobacz też:
- mysqli_connect() - Alias dla mysqli::__construct
- mysqli_connect_errno() - Returns the error code from last connect call
- mysqli_errno() - Returns the error code for the most recent function call
- mysqli_error() - Returns a string description of the last error
- mysqli_sqlstate() - Returns the SQLSTATE error from previous MySQL operation
mysqli::__construct
mysqli_connect
(PHP 5)
mysqli::__construct -- mysqli_connect — Open a new connection to the MySQL server
Opis
Styl obiektowy
$host = ini_get("mysqli.default_host")
[, string $username = ini_get("mysqli.default_user")
[, string $passwd = ini_get("mysqli.default_pw")
[, string $dbname = ""
[, int $port = ini_get("mysqli.default_port")
[, string $socket = ini_get("mysqli.default_socket")
]]]]]] )Styl proceduralny
$host = ini_get("mysqli.default_host")
[, string $username = ini_get("mysqli.default_user")
[, string $passwd = ini_get("mysqli.default_pw")
[, string $dbname = ""
[, int $port = ini_get("mysqli.default_port")
[, string $socket = ini_get("mysqli.default_socket")
]]]]]] )Opens a connection to the MySQL Server running on.
Parametry
-
host -
Can be either a host name or an IP address. Passing the
NULLvalue or the string "localhost" to this parameter, the local host is assumed. When possible, pipes will be used instead of the TCP/IP protocol.Prepending host by p: opens a persistent connection. mysqli_change_user() is automatically called on connections opened from the connection pool.
-
username -
The MySQL user name.
-
passwd -
If not provided or
NULL, the MySQL server will attempt to authenticate the user against those user records which have no password only. This allows one username to be used with different permissions (depending on if a password as provided or not). -
dbname -
If provided will specify the default database to be used when performing queries.
-
port -
Specifies the port number to attempt to connect to the MySQL server.
-
socket -
Specifies the socket or named pipe that should be used.
Informacja:
Specifying the
socketparameter will not explicitly determine the type of connection to be used when connecting to the MySQL server. How the connection is made to the MySQL database is determined by thehostparameter.
Zwracane wartości
Returns an object which represents the connection to a MySQL Server.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.0 | Added the ability of persistent connections. |
Przykłady
Przykład #1 mysqli::__construct() example
Styl obiektowy
<?php
$mysqli = new mysqli('localhost', 'my_user', 'my_password', 'my_db');
/*
* This is the "official" OO way to do it,
* BUT $connect_error was broken until PHP 5.2.9 and 5.3.0.
*/
if ($mysqli->connect_error) {
die('Connect Error (' . $mysqli->connect_errno . ') '
. $mysqli->connect_error);
}
/*
* Use this instead of $connect_error if you need to ensure
* compatibility with PHP versions prior to 5.2.9 and 5.3.0.
*/
if (mysqli_connect_error()) {
die('Connect Error (' . mysqli_connect_errno() . ') '
. mysqli_connect_error());
}
echo 'Success... ' . $mysqli->host_info . "\n";
$mysqli->close();
?>
Styl obiektowy when extending mysqli class
<?php
class foo_mysqli extends mysqli {
public function __construct($host, $user, $pass, $db) {
parent::__construct($host, $user, $pass, $db);
if (mysqli_connect_error()) {
die('Connect Error (' . mysqli_connect_errno() . ') '
. mysqli_connect_error());
}
}
}
$db = new foo_mysqli('localhost', 'my_user', 'my_password', 'my_db');
echo 'Success... ' . $db->host_info . "\n";
$db->close();
?>
Styl proceduralny
<?php
$link = mysqli_connect('localhost', 'my_user', 'my_password', 'my_db');
if (!$link) {
die('Connect Error (' . mysqli_connect_errno() . ') '
. mysqli_connect_error());
}
echo 'Success... ' . mysqli_get_host_info($link) . "\n";
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Success... MySQL host info: localhost via TCP/IP
Notatki
Informacja:
MySQLnd zawsze przyjmuje domyślne kodowanie znaków serwera. To kodowanie jest przesyłane podczas połączenia hand-shake/authentication, którego używa mysqlnd.
Libmysql używa domyślnego kodowania znaków ustawionego w pliku my.cnf lub przez jawne wywołanie funkcji mysqli_options() przed wywołaniem mysqli_real_connect(), ale po wywołaniu mysqli_init().
Informacja:
OO syntax only: If a connection fails an object is still returned. To check if the connection failed then use either the mysqli_connect_error() function or the mysqli->connect_error property as in the preceding examples.
Informacja:
If it is necessary to set options, such as the connection timeout, mysqli_real_connect() must be used instead.
Informacja:
Calling the constructor with no parameters is the same as calling mysqli_init().
Informacja:
Error "Can't create TCP/IP socket (10106)" usually means that the variables_order configure directive doesn't contain character E. On Windows, if the environment is not copied the SYSTEMROOT environment variable won't be available and PHP will have problems loading Winsock.
Zobacz też:
- mysqli_real_connect() - Opens a connection to a mysql server
- mysqli_options() - Set options
- mysqli_connect_errno() - Returns the error code from last connect call
- mysqli_connect_error() - Returns a string description of the last connect error
- mysqli_close() - Closes a previously opened database connection
mysqli::debug
mysqli_debug
(PHP 5)
mysqli::debug -- mysqli_debug — Performs debugging operations
Opis
Styl obiektowy
$message
)Styl proceduralny
$message
)Performs debugging operations using the Fred Fish debugging library.
Parametry
-
message -
A string representing the debugging operation to perform
Zwracane wartości
Returns TRUE.
Notatki
Informacja:
To use the mysqli_debug() function you must compile the MySQL client library to support debugging.
Przykłady
Przykład #1 Generating a Trace File
<?php
/* Create a trace file in '/tmp/client.trace' on the local (client) machine: */
mysqli_debug("d:t:o,/tmp/client.trace");
?>
Zobacz też:
- mysqli_dump_debug_info() - Dump debugging information into the log
- mysqli_report() - Enables or disables internal report functions
mysqli::disable_reads_from_master
mysqli_disable_reads_from_master
(PHP 5)
mysqli::disable_reads_from_master -- mysqli_disable_reads_from_master — Disable reads from master
Opis
Styl obiektowy
Styl proceduralny
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Ta funkcja jest PRZESTARZAŁA i zostanie USUNIĘTA od PHP 5.3.0.
mysqli::dump_debug_info
mysqli_dump_debug_info
(PHP 5)
mysqli::dump_debug_info -- mysqli_dump_debug_info — Dump debugging information into the log
Opis
Styl obiektowy
Styl proceduralny
This function is designed to be executed by an user with the SUPER privilege and is used to dump debugging information into the log for the MySQL Server relating to the connection.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
mysqli::$errno
mysqli_errno
(PHP 5)
mysqli::$errno -- mysqli_errno — Returns the error code for the most recent function call
Opis
Styl obiektowy
Styl proceduralny
Returns the last error code for the most recent MySQLi function call that can succeed or fail.
Client error message numbers are listed in the MySQL errmsg.h header file, server error message numbers are listed in mysqld_error.h. In the MySQL source distribution you can find a complete list of error messages and error numbers in the file Docs/mysqld_error.txt.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
An error code value for the last call, if it failed. zero means no error occurred.
Przykłady
Przykład #1 $mysqli->errno example
Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
if (!$mysqli->query("SET a=1")) {
printf("Errorcode: %d\n", $mysqli->errno);
}
/* close connection */
$mysqli->close();
?>
Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
if (!mysqli_query($link, "SET a=1")) {
printf("Errorcode: %d\n", mysqli_errno($link));
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Errorcode: 1193
Zobacz też:
- mysqli_connect_errno() - Returns the error code from last connect call
- mysqli_connect_error() - Returns a string description of the last connect error
- mysqli_error() - Returns a string description of the last error
- mysqli_sqlstate() - Returns the SQLSTATE error from previous MySQL operation
mysqli::$error_list
mysqli_error_list
(PHP 5 >= 5.4.0)
mysqli::$error_list -- mysqli_error_list — Returns a list of errors from the last command executed
Opis
Styl obiektowy
Styl proceduralny
Returns a array of errors for the most recent MySQLi function call that can succeed or fail.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
A list of errors, each as an associative array containing the errno, error, and sqlstate.
Przykłady
Przykład #1 $mysqli->error_list example
Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "nobody", "");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
if (!$mysqli->query("SET a=1")) {
print_r($mysqli->error_list);
}
/* close connection */
$mysqli->close();
?>
Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
if (!mysqli_query($link, "SET a=1")) {
print_r(mysqli_error_list($link));
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Array
(
[0] => Array
(
[errno] => 1193
[sqlstate] => HY000
[error] => Unknown system variable 'a'
)
)
Zobacz też:
- mysqli_connect_errno() - Returns the error code from last connect call
- mysqli_connect_error() - Returns a string description of the last connect error
- mysqli_error() - Returns a string description of the last error
- mysqli_sqlstate() - Returns the SQLSTATE error from previous MySQL operation
mysqli::$error
mysqli_error
(PHP 5)
mysqli::$error -- mysqli_error — Returns a string description of the last error
Opis
Styl obiektowy
Styl proceduralny
Returns the last error message for the most recent MySQLi function call that can succeed or fail.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
A string that describes the error. An empty string if no error occurred.
Przykłady
Przykład #1 $mysqli->error example
Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
if (!$mysqli->query("SET a=1")) {
printf("Errormessage: %s\n", $mysqli->error);
}
/* close connection */
$mysqli->close();
?>
Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
if (!mysqli_query($link, "SET a=1")) {
printf("Errormessage: %s\n", mysqli_error($link));
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Errormessage: Unknown system variable 'a'
Zobacz też:
- mysqli_connect_errno() - Returns the error code from last connect call
- mysqli_connect_error() - Returns a string description of the last connect error
- mysqli_errno() - Returns the error code for the most recent function call
- mysqli_sqlstate() - Returns the SQLSTATE error from previous MySQL operation
mysqli::$field_count
mysqli_field_count
(PHP 5)
mysqli::$field_count -- mysqli_field_count — Returns the number of columns for the most recent query
Opis
Styl obiektowy
Styl proceduralny
Returns the number of columns for the most recent query on the connection
represented by the link parameter. This function
can be useful when using the mysqli_store_result()
function to determine if the query should have produced a non-empty result
set or not without knowing the nature of the query.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
An integer representing the number of fields in a result set.
Przykłady
Przykład #1 $mysqli->field_count example
Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "test");
$mysqli->query( "DROP TABLE IF EXISTS friends");
$mysqli->query( "CREATE TABLE friends (id int, name varchar(20))");
$mysqli->query( "INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");
$mysqli->real_query("SELECT * FROM friends");
if ($mysqli->field_count) {
/* this was a select/show or describe query */
$result = $mysqli->store_result();
/* process resultset */
$row = $result->fetch_row();
/* free resultset */
$result->close();
}
/* close connection */
$mysqli->close();
?>
Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "test");
mysqli_query($link, "DROP TABLE IF EXISTS friends");
mysqli_query($link, "CREATE TABLE friends (id int, name varchar(20))");
mysqli_query($link, "INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");
mysqli_real_query($link, "SELECT * FROM friends");
if (mysqli_field_count($link)) {
/* this was a select/show or describe query */
$result = mysqli_store_result($link);
/* process resultset */
$row = mysqli_fetch_row($result);
/* free resultset */
mysqli_free_result($result);
}
/* close connection */
mysqli_close($link);
?>
mysqli::get_charset
mysqli_get_charset
(PHP 5 >= 5.1.0)
mysqli::get_charset -- mysqli_get_charset — Returns a character set object
Opis
Styl obiektowy
Styl proceduralny
Returns a character set object providing several properties of the current active character set.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
The function returns a character set object with the following properties:
-
charset -
Character set name
-
collation -
Collation name
-
dir -
Directory the charset description was fetched from (?) or "" for built-in character sets
-
min_length -
Minimum character length in bytes
-
max_length -
Maximum character length in bytes
-
number -
Internal character set number
-
state -
Character set status (?)
Przykłady
Przykład #1 mysqli::get_charset() example
Styl obiektowy
<?php
$db = mysqli_init();
$db->real_connect("localhost","root","","test");
var_dump($db->get_charset());
?>
Styl proceduralny
<?php
$db = mysqli_init();
mysqli_real_connect($db, "localhost","root","","test");
var_dump($db->get_charset());
?>
Powyższe przykłady wyświetlą:
object(stdClass)#2 (7) {
["charset"]=>
string(6) "latin1"
["collation"]=>
string(17) "latin1_swedish_ci"
["dir"]=>
string(0) ""
["min_length"]=>
int(1)
["max_length"]=>
int(1)
["number"]=>
int(8)
["state"]=>
int(801)
}
Zobacz też:
- mysqli_character_set_name() - Returns the default character set for the database connection
- mysqli_set_charset() - Sets the default client character set
mysqli::get_client_info
mysqli_get_client_info
(PHP 5)
mysqli::get_client_info -- mysqli_get_client_info — Returns the MySQL client version as a string
Opis
Styl obiektowy
Styl proceduralny
Returns a string that represents the MySQL client library version.
Zwracane wartości
A string that represents the MySQL client library version
Przykłady
Przykład #1 mysqli_get_client_info
<?php
/* We don't need a connection to determine
the version of mysql client library */
printf("Client library version: %s\n", mysqli_get_client_info());
?>
Zobacz też:
- mysqli_get_client_version() - Get MySQL client info
- mysqli_get_server_info() - Returns the version of the MySQL server
- mysqli_get_server_version() - Returns the version of the MySQL server as an integer
mysqli_get_client_stats
(PHP 5 >= 5.3.0)
mysqli_get_client_stats — Returns client per-process statistics
Opis
Returns client per-process statistics. Dostępna tylko z mysqlnd.
Parametry
Zwracane wartości
Returns an array with client stats if success, FALSE otherwise.
Przykłady
Przykład #1 A mysqli_get_client_stats() example
<?php
$link = mysqli_connect();
print_r(mysqli_get_client_stats());
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[bytes_sent] => 43
[bytes_received] => 80
[packets_sent] => 1
[packets_received] => 2
[protocol_overhead_in] => 8
[protocol_overhead_out] => 4
[bytes_received_ok_packet] => 11
[bytes_received_eof_packet] => 0
[bytes_received_rset_header_packet] => 0
[bytes_received_rset_field_meta_packet] => 0
[bytes_received_rset_row_packet] => 0
[bytes_received_prepare_response_packet] => 0
[bytes_received_change_user_packet] => 0
[packets_sent_command] => 0
[packets_received_ok] => 1
[packets_received_eof] => 0
[packets_received_rset_header] => 0
[packets_received_rset_field_meta] => 0
[packets_received_rset_row] => 0
[packets_received_prepare_response] => 0
[packets_received_change_user] => 0
[result_set_queries] => 0
[non_result_set_queries] => 0
[no_index_used] => 0
[bad_index_used] => 0
[slow_queries] => 0
[buffered_sets] => 0
[unbuffered_sets] => 0
[ps_buffered_sets] => 0
[ps_unbuffered_sets] => 0
[flushed_normal_sets] => 0
[flushed_ps_sets] => 0
[ps_prepared_never_executed] => 0
[ps_prepared_once_executed] => 0
[rows_fetched_from_server_normal] => 0
[rows_fetched_from_server_ps] => 0
[rows_buffered_from_client_normal] => 0
[rows_buffered_from_client_ps] => 0
[rows_fetched_from_client_normal_buffered] => 0
[rows_fetched_from_client_normal_unbuffered] => 0
[rows_fetched_from_client_ps_buffered] => 0
[rows_fetched_from_client_ps_unbuffered] => 0
[rows_fetched_from_client_ps_cursor] => 0
[rows_skipped_normal] => 0
[rows_skipped_ps] => 0
[copy_on_write_saved] => 0
[copy_on_write_performed] => 0
[command_buffer_too_small] => 0
[connect_success] => 1
[connect_failure] => 0
[connection_reused] => 0
[reconnect] => 0
[pconnect_success] => 0
[active_connections] => 1
[active_persistent_connections] => 0
[explicit_close] => 0
[implicit_close] => 0
[disconnect_close] => 0
[in_middle_of_command_close] => 0
[explicit_free_result] => 0
[implicit_free_result] => 0
[explicit_stmt_close] => 0
[implicit_stmt_close] => 0
[mem_emalloc_count] => 0
[mem_emalloc_ammount] => 0
[mem_ecalloc_count] => 0
[mem_ecalloc_ammount] => 0
[mem_erealloc_count] => 0
[mem_erealloc_ammount] => 0
[mem_efree_count] => 0
[mem_malloc_count] => 0
[mem_malloc_ammount] => 0
[mem_calloc_count] => 0
[mem_calloc_ammount] => 0
[mem_realloc_count] => 0
[mem_realloc_ammount] => 0
[mem_free_count] => 0
[proto_text_fetched_null] => 0
[proto_text_fetched_bit] => 0
[proto_text_fetched_tinyint] => 0
[proto_text_fetched_short] => 0
[proto_text_fetched_int24] => 0
[proto_text_fetched_int] => 0
[proto_text_fetched_bigint] => 0
[proto_text_fetched_decimal] => 0
[proto_text_fetched_float] => 0
[proto_text_fetched_double] => 0
[proto_text_fetched_date] => 0
[proto_text_fetched_year] => 0
[proto_text_fetched_time] => 0
[proto_text_fetched_datetime] => 0
[proto_text_fetched_timestamp] => 0
[proto_text_fetched_string] => 0
[proto_text_fetched_blob] => 0
[proto_text_fetched_enum] => 0
[proto_text_fetched_set] => 0
[proto_text_fetched_geometry] => 0
[proto_text_fetched_other] => 0
[proto_binary_fetched_null] => 0
[proto_binary_fetched_bit] => 0
[proto_binary_fetched_tinyint] => 0
[proto_binary_fetched_short] => 0
[proto_binary_fetched_int24] => 0
[proto_binary_fetched_int] => 0
[proto_binary_fetched_bigint] => 0
[proto_binary_fetched_decimal] => 0
[proto_binary_fetched_float] => 0
[proto_binary_fetched_double] => 0
[proto_binary_fetched_date] => 0
[proto_binary_fetched_year] => 0
[proto_binary_fetched_time] => 0
[proto_binary_fetched_datetime] => 0
[proto_binary_fetched_timestamp] => 0
[proto_binary_fetched_string] => 0
[proto_binary_fetched_blob] => 0
[proto_binary_fetched_enum] => 0
[proto_binary_fetched_set] => 0
[proto_binary_fetched_geometry] => 0
[proto_binary_fetched_other] => 0
)
mysqli::$client_version
mysqli_get_client_version
(PHP 5)
mysqli::$client_version -- mysqli_get_client_version — Get MySQL client info
Opis
Styl obiektowy
Styl proceduralny
Returns client version number as an integer.
Zwracane wartości
A number that represents the MySQL client library version in format: main_version*10000 + minor_version *100 + sub_version. For example, 4.1.0 is returned as 40100.
This is useful to quickly determine the version of the client library to know if some capability exits.
Przykłady
Przykład #1 mysqli_get_client_version
<?php
/* We don't need a connection to determine
the version of mysql client library */
printf("Client library version: %d\n", mysqli_get_client_version());
?>
Zobacz też:
- mysqli_get_client_info() - Returns the MySQL client version as a string
- mysqli_get_server_info() - Returns the version of the MySQL server
- mysqli_get_server_version() - Returns the version of the MySQL server as an integer
mysqli::get_connection_stats
mysqli_get_connection_stats
(PHP 5 >= 5.3.0)
mysqli::get_connection_stats -- mysqli_get_connection_stats — Returns statistics about the client connection
Opis
Styl obiektowy
Styl proceduralny
Returns statistics about the client connection. Dostępna tylko z mysqlnd.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
Returns an array with connection stats if success, FALSE otherwise.
Przykłady
Przykład #1 A mysqli_get_connection_stats() example
<?php
$link = mysqli_connect();
print_r(mysqli_get_connection_stats($link));
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[bytes_sent] => 43
[bytes_received] => 80
[packets_sent] => 1
[packets_received] => 2
[protocol_overhead_in] => 8
[protocol_overhead_out] => 4
[bytes_received_ok_packet] => 11
[bytes_received_eof_packet] => 0
[bytes_received_rset_header_packet] => 0
[bytes_received_rset_field_meta_packet] => 0
[bytes_received_rset_row_packet] => 0
[bytes_received_prepare_response_packet] => 0
[bytes_received_change_user_packet] => 0
[packets_sent_command] => 0
[packets_received_ok] => 1
[packets_received_eof] => 0
[packets_received_rset_header] => 0
[packets_received_rset_field_meta] => 0
[packets_received_rset_row] => 0
[packets_received_prepare_response] => 0
[packets_received_change_user] => 0
[result_set_queries] => 0
[non_result_set_queries] => 0
[no_index_used] => 0
[bad_index_used] => 0
[slow_queries] => 0
[buffered_sets] => 0
[unbuffered_sets] => 0
[ps_buffered_sets] => 0
[ps_unbuffered_sets] => 0
[flushed_normal_sets] => 0
[flushed_ps_sets] => 0
[ps_prepared_never_executed] => 0
[ps_prepared_once_executed] => 0
[rows_fetched_from_server_normal] => 0
[rows_fetched_from_server_ps] => 0
[rows_buffered_from_client_normal] => 0
[rows_buffered_from_client_ps] => 0
[rows_fetched_from_client_normal_buffered] => 0
[rows_fetched_from_client_normal_unbuffered] => 0
[rows_fetched_from_client_ps_buffered] => 0
[rows_fetched_from_client_ps_unbuffered] => 0
[rows_fetched_from_client_ps_cursor] => 0
[rows_skipped_normal] => 0
[rows_skipped_ps] => 0
[copy_on_write_saved] => 0
[copy_on_write_performed] => 0
[command_buffer_too_small] => 0
[connect_success] => 1
[connect_failure] => 0
[connection_reused] => 0
[reconnect] => 0
[pconnect_success] => 0
[active_connections] => 1
[active_persistent_connections] => 0
[explicit_close] => 0
[implicit_close] => 0
[disconnect_close] => 0
[in_middle_of_command_close] => 0
[explicit_free_result] => 0
[implicit_free_result] => 0
[explicit_stmt_close] => 0
[implicit_stmt_close] => 0
[mem_emalloc_count] => 0
[mem_emalloc_ammount] => 0
[mem_ecalloc_count] => 0
[mem_ecalloc_ammount] => 0
[mem_erealloc_count] => 0
[mem_erealloc_ammount] => 0
[mem_efree_count] => 0
[mem_malloc_count] => 0
[mem_malloc_ammount] => 0
[mem_calloc_count] => 0
[mem_calloc_ammount] => 0
[mem_realloc_count] => 0
[mem_realloc_ammount] => 0
[mem_free_count] => 0
[proto_text_fetched_null] => 0
[proto_text_fetched_bit] => 0
[proto_text_fetched_tinyint] => 0
[proto_text_fetched_short] => 0
[proto_text_fetched_int24] => 0
[proto_text_fetched_int] => 0
[proto_text_fetched_bigint] => 0
[proto_text_fetched_decimal] => 0
[proto_text_fetched_float] => 0
[proto_text_fetched_double] => 0
[proto_text_fetched_date] => 0
[proto_text_fetched_year] => 0
[proto_text_fetched_time] => 0
[proto_text_fetched_datetime] => 0
[proto_text_fetched_timestamp] => 0
[proto_text_fetched_string] => 0
[proto_text_fetched_blob] => 0
[proto_text_fetched_enum] => 0
[proto_text_fetched_set] => 0
[proto_text_fetched_geometry] => 0
[proto_text_fetched_other] => 0
[proto_binary_fetched_null] => 0
[proto_binary_fetched_bit] => 0
[proto_binary_fetched_tinyint] => 0
[proto_binary_fetched_short] => 0
[proto_binary_fetched_int24] => 0
[proto_binary_fetched_int] => 0
[proto_binary_fetched_bigint] => 0
[proto_binary_fetched_decimal] => 0
[proto_binary_fetched_float] => 0
[proto_binary_fetched_double] => 0
[proto_binary_fetched_date] => 0
[proto_binary_fetched_year] => 0
[proto_binary_fetched_time] => 0
[proto_binary_fetched_datetime] => 0
[proto_binary_fetched_timestamp] => 0
[proto_binary_fetched_string] => 0
[proto_binary_fetched_blob] => 0
[proto_binary_fetched_enum] => 0
[proto_binary_fetched_set] => 0
[proto_binary_fetched_geometry] => 0
[proto_binary_fetched_other] => 0
)
mysqli::$host_info
mysqli_get_host_info
(PHP 5)
mysqli::$host_info -- mysqli_get_host_info — Returns a string representing the type of connection used
Opis
Styl obiektowy
Styl proceduralny
Returns a string describing the connection represented by
the link parameter (including
the server host name).
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
A character string representing the server hostname and the connection type.
Przykłady
Przykład #1 $mysqli->host_info example
Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* print host information */
printf("Host info: %s\n", $mysqli->host_info);
/* close connection */
$mysqli->close();
?>
Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* print host information */
printf("Host info: %s\n", mysqli_get_host_info($link));
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Host info: Localhost via UNIX socket
mysqli::$protocol_version
mysqli_get_proto_info
(PHP 5)
mysqli::$protocol_version -- mysqli_get_proto_info — Returns the version of the MySQL protocol used
Opis
Styl obiektowy
Styl proceduralny
Returns an integer representing the MySQL protocol version used by the
connection represented by the link parameter.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
Returns an integer representing the protocol version.
Przykłady
Przykład #1 $mysqli->protocol_version example
Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* print protocol version */
printf("Protocol version: %d\n", $mysqli->protocol_version);
/* close connection */
$mysqli->close();
?>
Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* print protocol version */
printf("Protocol version: %d\n", mysqli_get_proto_info($link));
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Protocol version: 10
mysqli::$server_info
mysqli_get_server_info
(PHP 5)
mysqli::$server_info -- mysqli_get_server_info — Returns the version of the MySQL server
Opis
Styl obiektowy
Styl proceduralny
Returns a string representing the version of the MySQL server that the MySQLi extension is connected to.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
A character string representing the server version.
Przykłady
Przykład #1 $mysqli->server_info example
Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* print server version */
printf("Server version: %s\n", $mysqli->server_info);
/* close connection */
$mysqli->close();
?>
Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* print server version */
printf("Server version: %s\n", mysqli_get_server_info($link));
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Server version: 4.1.2-alpha-debug
Zobacz też:
- mysqli_get_client_info() - Returns the MySQL client version as a string
- mysqli_get_client_version() - Get MySQL client info
- mysqli_get_server_version() - Returns the version of the MySQL server as an integer
mysqli::$server_version
mysqli_get_server_version
(PHP 5)
mysqli::$server_version -- mysqli_get_server_version — Returns the version of the MySQL server as an integer
Opis
Styl obiektowy
Styl proceduralny
The mysqli_get_server_version() function returns the
version of the server connected to (represented by the
link parameter) as an integer.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
An integer representing the server version.
The form of this version number is main_version * 10000 + minor_version * 100 + sub_version (i.e. version 4.1.0 is 40100).
Przykłady
Przykład #1 $mysqli->server_version example
Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* print server version */
printf("Server version: %d\n", $mysqli->server_version);
/* close connection */
$mysqli->close();
?>
Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* print server version */
printf("Server version: %d\n", mysqli_get_server_version($link));
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Server version: 40102
Zobacz też:
- mysqli_get_client_info() - Returns the MySQL client version as a string
- mysqli_get_client_version() - Get MySQL client info
- mysqli_get_server_info() - Returns the version of the MySQL server
mysqli::get_warnings
mysqli_get_warnings
(PHP 5 >= 5.1.0)
mysqli::get_warnings -- mysqli_get_warnings — Get result of SHOW WARNINGS
Opis
Styl obiektowy
Styl proceduralny
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
mysqli::$info
mysqli_info
(PHP 5)
mysqli::$info -- mysqli_info — Retrieves information about the most recently executed query
Opis
Styl obiektowy
Styl proceduralny
The mysqli_info() function returns a string providing information about the last query executed. The nature of this string is provided below:
| Query type | Example result string |
|---|---|
| INSERT INTO...SELECT... | Records: 100 Duplicates: 0 Warnings: 0 |
| INSERT INTO...VALUES (...),(...),(...) | Records: 3 Duplicates: 0 Warnings: 0 |
| LOAD DATA INFILE ... | Records: 1 Deleted: 0 Skipped: 0 Warnings: 0 |
| ALTER TABLE ... | Records: 3 Duplicates: 0 Warnings: 0 |
| UPDATE ... | Rows matched: 40 Changed: 40 Warnings: 0 |
Informacja:
Queries which do not fall into one of the preceding formats are not supported. In these situations, mysqli_info() will return an empty string.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
A character string representing additional information about the most recently executed query.
Przykłady
Przykład #1 $mysqli->info example
Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$mysqli->query("CREATE TEMPORARY TABLE t1 LIKE City");
/* INSERT INTO .. SELECT */
$mysqli->query("INSERT INTO t1 SELECT * FROM City ORDER BY ID LIMIT 150");
printf("%s\n", $mysqli->info);
/* close connection */
$mysqli->close();
?>
Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
mysqli_query($link, "CREATE TEMPORARY TABLE t1 LIKE City");
/* INSERT INTO .. SELECT */
mysqli_query($link, "INSERT INTO t1 SELECT * FROM City ORDER BY ID LIMIT 150");
printf("%s\n", mysqli_info($link));
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Records: 150 Duplicates: 0 Warnings: 0
Zobacz też:
- mysqli_affected_rows() - Gets the number of affected rows in a previous MySQL operation
- mysqli_warning_count() - Returns the number of warnings from the last query for the given link
- mysqli_num_rows() - Gets the number of rows in a result
mysqli::init
mysqli_init
(PHP 5)
mysqli::init -- mysqli_init — Initializes MySQLi and returns a resource for use with mysqli_real_connect()
Opis
Styl obiektowy
Styl proceduralny
Allocates or initializes a MYSQL object suitable for mysqli_options() and mysqli_real_connect().
Informacja:
Any subsequent calls to any mysqli function (except mysqli_options()) will fail until mysqli_real_connect() was called.
Zwracane wartości
Returns an object.
Przykłady
Zobacz też:
- mysqli_options() - Set options
- mysqli_close() - Closes a previously opened database connection
- mysqli_real_connect() - Opens a connection to a mysql server
- mysqli_connect() - Alias dla mysqli::__construct
mysqli::$insert_id
mysqli_insert_id
(PHP 5)
mysqli::$insert_id -- mysqli_insert_id — Returns the auto generated id used in the last query
Opis
Styl obiektowy
Styl proceduralny
The mysqli_insert_id() function returns the ID generated by a query on a table with a column having the AUTO_INCREMENT attribute. If the last query wasn't an INSERT or UPDATE statement or if the modified table does not have a column with the AUTO_INCREMENT attribute, this function will return zero.
Informacja:
Performing an INSERT or UPDATE statement using the LAST_INSERT_ID() function will also modify the value returned by the mysqli_insert_id() function.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
The value of the AUTO_INCREMENT field that was updated by the previous query. Returns zero if there was no previous query on the connection or if the query did not update an AUTO_INCREMENT value.
Informacja:
If the number is greater than maximal int value, mysqli_insert_id() will return a string.
Przykłady
Przykład #1 $mysqli->insert_id example
Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$mysqli->query("CREATE TABLE myCity LIKE City");
$query = "INSERT INTO myCity VALUES (NULL, 'Stuttgart', 'DEU', 'Stuttgart', 617000)";
$mysqli->query($query);
printf ("New Record has id %d.\n", $mysqli->insert_id);
/* drop table */
$mysqli->query("DROP TABLE myCity");
/* close connection */
$mysqli->close();
?>
Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
mysqli_query($link, "CREATE TABLE myCity LIKE City");
$query = "INSERT INTO myCity VALUES (NULL, 'Stuttgart', 'DEU', 'Stuttgart', 617000)";
mysqli_query($link, $query);
printf ("New Record has id %d.\n", mysqli_insert_id($link));
/* drop table */
mysqli_query($link, "DROP TABLE myCity");
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
New Record has id 1.
mysqli::kill
mysqli_kill
(PHP 5)
mysqli::kill -- mysqli_kill — Asks the server to kill a MySQL thread
Opis
Styl obiektowy
$processid
)Styl proceduralny
This function is used to ask the server to kill a MySQL thread specified
by the processid parameter. This value must be
retrieved by calling the mysqli_thread_id() function.
To stop a running query you should use the SQL command KILL QUERY processid.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 mysqli::kill() example
Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* determine our thread id */
$thread_id = $mysqli->thread_id;
/* Kill connection */
$mysqli->kill($thread_id);
/* This should produce an error */
if (!$mysqli->query("CREATE TABLE myCity LIKE City")) {
printf("Error: %s\n", $mysqli->error);
exit;
}
/* close connection */
$mysqli->close();
?>
Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* determine our thread id */
$thread_id = mysqli_thread_id($link);
/* Kill connection */
mysqli_kill($link, $thread_id);
/* This should produce an error */
if (!mysqli_query($link, "CREATE TABLE myCity LIKE City")) {
printf("Error: %s\n", mysqli_error($link));
exit;
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Error: MySQL server has gone away
mysqli::more_results
mysqli_more_results
(PHP 5)
mysqli::more_results -- mysqli_more_results — Check if there are any more query results from a multi query
Opis
Styl obiektowy
Styl proceduralny
Indicates if one or more result sets are available from a previous call to mysqli_multi_query().
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
See mysqli_multi_query().
Zobacz też:
- mysqli_multi_query() - Performs a query on the database
- mysqli_next_result() - Prepare next result from multi_query
- mysqli_store_result() - Transfers a result set from the last query
- mysqli_use_result() - Initiate a result set retrieval
mysqli::multi_query
mysqli_multi_query
(PHP 5)
mysqli::multi_query -- mysqli_multi_query — Performs a query on the database
Opis
Styl obiektowy
$query
)Styl proceduralny
Executes one or multiple queries which are concatenated by a semicolon.
To retrieve the resultset from the first query you can use mysqli_use_result() or mysqli_store_result(). All subsequent query results can be processed using mysqli_more_results() and mysqli_next_result().
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
-
query -
The query, as a string.
Data inside the query should be properly escaped.
Zwracane wartości
Returns FALSE if the first statement failed.
To retrieve subsequent errors from other statements you have to call
mysqli_next_result() first.
Przykłady
Przykład #1 mysqli::multi_query() example
Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT CURRENT_USER();";
$query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";
/* execute multi query */
if ($mysqli->multi_query($query)) {
do {
/* store first result set */
if ($result = $mysqli->store_result()) {
while ($row = $result->fetch_row()) {
printf("%s\n", $row[0]);
}
$result->free();
}
/* print divider */
if ($mysqli->more_results()) {
printf("-----------------\n");
}
} while ($mysqli->next_result());
}
/* close connection */
$mysqli->close();
?>
Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT CURRENT_USER();";
$query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";
/* execute multi query */
if (mysqli_multi_query($link, $query)) {
do {
/* store first result set */
if ($result = mysqli_store_result($link)) {
while ($row = mysqli_fetch_row($result)) {
printf("%s\n", $row[0]);
}
mysqli_free_result($result);
}
/* print divider */
if (mysqli_more_results($link)) {
printf("-----------------\n");
}
} while (mysqli_next_result($link));
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą coś podobnego do:
my_user@localhost ----------------- Amersfoort Maastricht Dordrecht Leiden Haarlemmermeer
Zobacz też:
- mysqli_use_result() - Initiate a result set retrieval
- mysqli_store_result() - Transfers a result set from the last query
- mysqli_next_result() - Prepare next result from multi_query
- mysqli_more_results() - Check if there are any more query results from a multi query
mysqli::next_result
mysqli_next_result
(PHP 5)
mysqli::next_result -- mysqli_next_result — Prepare next result from multi_query
Opis
Styl obiektowy
Styl proceduralny
Prepares next result set from a previous call to mysqli_multi_query() which can be retrieved by mysqli_store_result() or mysqli_use_result().
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
See mysqli_multi_query().
Zobacz też:
- mysqli_multi_query() - Performs a query on the database
- mysqli_more_results() - Check if there are any more query results from a multi query
- mysqli_store_result() - Transfers a result set from the last query
- mysqli_use_result() - Initiate a result set retrieval
mysqli::options
mysqli_options
(PHP 5)
mysqli::options -- mysqli_options — Set options
Opis
Styl obiektowy
Styl proceduralny
Used to set extra connect options and affect behavior for a connection.
This function may be called multiple times to set several options.
mysqli_options() should be called after mysqli_init() and before mysqli_real_connect().
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
-
option -
The option that you want to set. It can be one of the following values:
Valid options Name Description MYSQLI_OPT_CONNECT_TIMEOUTconnection timeout in seconds (supported on Windows with TCP/IP since PHP 5.3.1) MYSQLI_OPT_LOCAL_INFILEenable/disable use of LOAD LOCAL INFILE MYSQLI_INIT_COMMANDcommand to execute after when connecting to MySQL server MYSQLI_READ_DEFAULT_FILERead options from named option file instead of my.cnf MYSQLI_READ_DEFAULT_GROUPRead options from the named group from my.cnf or the file specified with MYSQL_READ_DEFAULT_FILE. -
value -
The value for the option.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Notatki
Informacja:
MySQLnd zawsze przyjmuje domyślne kodowanie znaków serwera. To kodowanie jest przesyłane podczas połączenia hand-shake/authentication, którego używa mysqlnd.
Libmysql używa domyślnego kodowania znaków ustawionego w pliku my.cnf lub przez jawne wywołanie funkcji mysqli_options() przed wywołaniem mysqli_real_connect(), ale po wywołaniu mysqli_init().
Zobacz też:
- mysqli_init() - Initializes MySQLi and returns a resource for use with mysqli_real_connect()
- mysqli_real_connect() - Opens a connection to a mysql server
mysqli::ping
mysqli_ping
(PHP 5)
mysqli::ping -- mysqli_ping — Pings a server connection, or tries to reconnect if the connection has gone down
Opis
Styl obiektowy
Styl proceduralny
Checks whether the connection to the server is working. If it has gone down, and global option mysqli.reconnect is enabled an automatic reconnection is attempted.
This function can be used by clients that remain idle for a long while, to check whether the server has closed the connection and reconnect if necessary.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 mysqli::ping() example
Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* check if server is alive */
if ($mysqli->ping()) {
printf ("Our connection is ok!\n");
} else {
printf ("Error: %s\n", $mysqli->error);
}
/* close connection */
$mysqli->close();
?>
Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* check if server is alive */
if (mysqli_ping($link)) {
printf ("Our connection is ok!\n");
} else {
printf ("Error: %s\n", mysqli_error($link));
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Our connection is ok!
mysqli::poll
mysqli_poll
(PHP 5 >= 5.3.0)
mysqli::poll -- mysqli_poll — Poll connections
Opis
Styl obiektowy
&$read
, array &$error
, array &$reject
, int $sec
[, int $usec
] )Styl proceduralny
&$read
, array &$error
, array &$reject
, int $sec
[, int $usec
] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Poll connections. Dostępna tylko z mysqlnd.
Parametry
-
read -
-
error -
-
reject -
-
sec -
Number of seconds to wait, must be non-negative.
-
usec -
Number of microseconds to wait, must be non-negative.
Zwracane wartości
Returns number of ready connections in success, FALSE otherwise.
Przykłady
Przykład #1 A mysqli_poll() example
<?php
$link1 = mysqli_connect();
$link1->query("SELECT 'test'", MYSQLI_ASYNC);
$all_links = array($link1);
$processed = 0;
do {
$links = $errors = $reject = array();
foreach ($all_links as $link) {
$links[] = $errors[] = $reject[] = $link;
}
if (!mysqli_poll($links, $errors, $reject, 1)) {
continue;
}
foreach ($links as $link) {
if ($result = $link->reap_async_query()) {
print_r($result->fetch_row());
mysqli_free_result($result);
$processed++;
}
}
} while ($processed < count($all_links));
?>
Powyższy przykład wyświetli:
Array
(
[0] => test
)
Zobacz też:
- mysqli_query() - Performs a query on the database
- mysqli_reap_async_query() - Get result from async query
mysqli::prepare
mysqli_prepare
(PHP 5)
mysqli::prepare -- mysqli_prepare — Prepare an SQL statement for execution
Opis
Styl obiektowy
Styl proceduralny
Prepares the SQL query, and returns a statement handle to be used for further operations on the statement. The query must consist of a single SQL statement.
The parameter markers must be bound to application variables using mysqli_stmt_bind_param() and/or mysqli_stmt_bind_result() before executing the statement or fetching rows.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
-
query -
The query, as a string.
Informacja:
You should not add a terminating semicolon or \g to the statement.
This parameter can include one or more parameter markers in the SQL statement by embedding question mark (?) characters at the appropriate positions.
Informacja:
The markers are legal only in certain places in SQL statements. For example, they are allowed in the VALUES() list of an INSERT statement (to specify column values for a row), or in a comparison with a column in a WHERE clause to specify a comparison value.
However, they are not allowed for identifiers (such as table or column names), in the select list that names the columns to be returned by a SELECT statement, or to specify both operands of a binary operator such as the = equal sign. The latter restriction is necessary because it would be impossible to determine the parameter type. It's not allowed to compare marker with NULL by ? IS NULL too. In general, parameters are legal only in Data Manipulation Language (DML) statements, and not in Data Definition Language (DDL) statements.
Zwracane wartości
mysqli_prepare() returns a statement object or FALSE if an error occurred.
Przykłady
Przykład #1 mysqli::prepare() example
Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$city = "Amersfoort";
/* create a prepared statement */
if ($stmt = $mysqli->prepare("SELECT District FROM City WHERE Name=?")) {
/* bind parameters for markers */
$stmt->bind_param("s", $city);
/* execute query */
$stmt->execute();
/* bind result variables */
$stmt->bind_result($district);
/* fetch value */
$stmt->fetch();
printf("%s is in district %s\n", $city, $district);
/* close statement */
$stmt->close();
}
/* close connection */
$mysqli->close();
?>
Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$city = "Amersfoort";
/* create a prepared statement */
if ($stmt = mysqli_prepare($link, "SELECT District FROM City WHERE Name=?")) {
/* bind parameters for markers */
mysqli_stmt_bind_param($stmt, "s", $city);
/* execute query */
mysqli_stmt_execute($stmt);
/* bind result variables */
mysqli_stmt_bind_result($stmt, $district);
/* fetch value */
mysqli_stmt_fetch($stmt);
printf("%s is in district %s\n", $city, $district);
/* close statement */
mysqli_stmt_close($stmt);
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Amersfoort is in district Utrecht
Zobacz też:
- mysqli_stmt_execute() - Executes a prepared Query
- mysqli_stmt_fetch() - Fetch results from a prepared statement into the bound variables
- mysqli_stmt_bind_param() - Binds variables to a prepared statement as parameters
- mysqli_stmt_bind_result() - Binds variables to a prepared statement for result storage
- mysqli_stmt_close() - Closes a prepared statement
mysqli::query
mysqli_query
(PHP 5)
mysqli::query -- mysqli_query — Performs a query on the database
Opis
Styl obiektowy
Styl proceduralny
Performs a query against the database.
Functionally, using this function is identical to calling mysqli_real_query() followed either by mysqli_use_result() or mysqli_store_result().
Informacja:
In the case where you pass a statement to mysqli_query() that is longer than max_allowed_packet of the server, the returned error codes are different depending on whether you are using MySQL Native Driver (mysqlnd) or MySQL Client Library (libmysql). The behavior is as follows:
mysqlnd on Linux returns an error code of 1153. The error message means "got a packet bigger than max_allowed_packet bytes".
mysqlnd on Windows returns an error code 2006. This error message means "server has gone away".
libmysql on all platforms returns an error code 2006. This error message means "server has gone away".
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
-
query -
The query string.
Data inside the query should be properly escaped.
-
resultmode -
Either the constant
MYSQLI_USE_RESULTorMYSQLI_STORE_RESULTdepending on the desired behavior. By default,MYSQLI_STORE_RESULTis used.If you use
MYSQLI_USE_RESULTall subsequent calls will return error Commands out of sync unless you call mysqli_free_result()With
MYSQLI_ASYNC(available with mysqlnd), it is possible to perform query asynchronously. mysqli_poll() is then used to get results from such queries.
Zwracane wartości
Returns FALSE on failure. For successful SELECT, SHOW, DESCRIBE or
EXPLAIN queries mysqli_query() will return
a mysqli_result object. For other successful queries mysqli_query() will
return TRUE.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.0 | Added the ability of async queries. |
Przykłady
Przykład #1 mysqli::query() example
Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if ($mysqli->connect_errno) {
printf("Connect failed: %s\n", $mysqli->connect_error);
exit();
}
/* Create table doesn't return a resultset */
if ($mysqli->query("CREATE TEMPORARY TABLE myCity LIKE City") === TRUE) {
printf("Table myCity successfully created.\n");
}
/* Select queries return a resultset */
if ($result = $mysqli->query("SELECT Name FROM City LIMIT 10")) {
printf("Select returned %d rows.\n", $result->num_rows);
/* free result set */
$result->close();
}
/* If we have to retrieve large amount of data we use MYSQLI_USE_RESULT */
if ($result = $mysqli->query("SELECT * FROM City", MYSQLI_USE_RESULT)) {
/* Note, that we can't execute any functions which interact with the
server until result set was closed. All calls will return an
'out of sync' error */
if (!$mysqli->query("SET @a:='this will not work'")) {
printf("Error: %s\n", $mysqli->error);
}
$result->close();
}
$mysqli->close();
?>
Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* Create table doesn't return a resultset */
if (mysqli_query($link, "CREATE TEMPORARY TABLE myCity LIKE City") === TRUE) {
printf("Table myCity successfully created.\n");
}
/* Select queries return a resultset */
if ($result = mysqli_query($link, "SELECT Name FROM City LIMIT 10")) {
printf("Select returned %d rows.\n", mysqli_num_rows($result));
/* free result set */
mysqli_free_result($result);
}
/* If we have to retrieve large amount of data we use MYSQLI_USE_RESULT */
if ($result = mysqli_query($link, "SELECT * FROM City", MYSQLI_USE_RESULT)) {
/* Note, that we can't execute any functions which interact with the
server until result set was closed. All calls will return an
'out of sync' error */
if (!mysqli_query($link, "SET @a:='this will not work'")) {
printf("Error: %s\n", mysqli_error($link));
}
mysqli_free_result($result);
}
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Table myCity successfully created. Select returned 10 rows. Error: Commands out of sync; You can't run this command now
Zobacz też:
- mysqli_real_query() - Execute an SQL query
- mysqli_multi_query() - Performs a query on the database
- mysqli_free_result() - Frees the memory associated with a result
mysqli::real_connect
mysqli_real_connect
(PHP 5)
mysqli::real_connect -- mysqli_real_connect — Opens a connection to a mysql server
Opis
Styl obiektowy
$host
[, string $username
[, string $passwd
[, string $dbname
[, int $port
[, string $socket
[, int $flags
]]]]]]] )Styl proceduralny
$link
[, string $host
[, string $username
[, string $passwd
[, string $dbname
[, int $port
[, string $socket
[, int $flags
]]]]]]] )Establish a connection to a MySQL database engine.
This function differs from mysqli_connect():
-
mysqli_real_connect() needs a valid object which has to be created by function mysqli_init().
-
With the mysqli_options() function you can set various options for connection.
-
There is a
flagsparameter.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
-
host -
Can be either a host name or an IP address. Passing the
NULLvalue or the string "localhost" to this parameter, the local host is assumed. When possible, pipes will be used instead of the TCP/IP protocol. -
username -
The MySQL user name.
-
passwd -
If provided or
NULL, the MySQL server will attempt to authenticate the user against those user records which have no password only. This allows one username to be used with different permissions (depending on if a password as provided or not). -
dbname -
If provided will specify the default database to be used when performing queries.
-
port -
Specifies the port number to attempt to connect to the MySQL server.
-
socket -
Specifies the socket or named pipe that should be used.
Informacja:
Specifying the
socketparameter will not explicitly determine the type of connection to be used when connecting to the MySQL server. How the connection is made to the MySQL database is determined by thehostparameter. -
flags -
With the parameter
flagsyou can set different connection options:Supported flags Name Description MYSQLI_CLIENT_COMPRESSUse compression protocol MYSQLI_CLIENT_FOUND_ROWSreturn number of matched rows, not the number of affected rows MYSQLI_CLIENT_IGNORE_SPACEAllow spaces after function names. Makes all function names reserved words. MYSQLI_CLIENT_INTERACTIVEAllow interactive_timeout seconds (instead of wait_timeout seconds) of inactivity before closing the connection MYSQLI_CLIENT_SSLUse SSL (encryption) Informacja:
For security reasons the
MULTI_STATEMENTflag is not supported in PHP. If you want to execute multiple queries use the mysqli_multi_query() function.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 mysqli::real_connect() example
Styl obiektowy
<?php
$mysqli = mysqli_init();
if (!$mysqli) {
die('mysqli_init failed');
}
if (!$mysqli->options(MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0')) {
die('Setting MYSQLI_INIT_COMMAND failed');
}
if (!$mysqli->options(MYSQLI_OPT_CONNECT_TIMEOUT, 5)) {
die('Setting MYSQLI_OPT_CONNECT_TIMEOUT failed');
}
if (!$mysqli->real_connect('localhost', 'my_user', 'my_password', 'my_db')) {
die('Connect Error (' . mysqli_connect_errno() . ') '
. mysqli_connect_error());
}
echo 'Success... ' . $mysqli->host_info . "\n";
$mysqli->close();
?>
Styl obiektowy when extending mysqli class
<?php
class foo_mysqli extends mysqli {
public function __construct($host, $user, $pass, $db) {
parent::init();
if (!parent::options(MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0')) {
die('Setting MYSQLI_INIT_COMMAND failed');
}
if (!parent::options(MYSQLI_OPT_CONNECT_TIMEOUT, 5)) {
die('Setting MYSQLI_OPT_CONNECT_TIMEOUT failed');
}
if (!parent::real_connect($host, $user, $pass, $db)) {
die('Connect Error (' . mysqli_connect_errno() . ') '
. mysqli_connect_error());
}
}
}
$db = new foo_mysqli('localhost', 'my_user', 'my_password', 'my_db');
echo 'Success... ' . $db->host_info . "\n";
$db->close();
?>
Styl proceduralny
<?php
$link = mysqli_init();
if (!$link) {
die('mysqli_init failed');
}
if (!mysqli_options($link, MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0')) {
die('Setting MYSQLI_INIT_COMMAND failed');
}
if (!mysqli_options($link, MYSQLI_OPT_CONNECT_TIMEOUT, 5)) {
die('Setting MYSQLI_OPT_CONNECT_TIMEOUT failed');
}
if (!mysqli_real_connect($link, 'localhost', 'my_user', 'my_password', 'my_db')) {
die('Connect Error (' . mysqli_connect_errno() . ') '
. mysqli_connect_error());
}
echo 'Success... ' . mysqli_get_host_info($link) . "\n";
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Success... MySQL host info: localhost via TCP/IP
Notatki
Informacja:
MySQLnd zawsze przyjmuje domyślne kodowanie znaków serwera. To kodowanie jest przesyłane podczas połączenia hand-shake/authentication, którego używa mysqlnd.
Libmysql używa domyślnego kodowania znaków ustawionego w pliku my.cnf lub przez jawne wywołanie funkcji mysqli_options() przed wywołaniem mysqli_real_connect(), ale po wywołaniu mysqli_init().
Zobacz też:
- mysqli_connect() - Alias dla mysqli::__construct
- mysqli_init() - Initializes MySQLi and returns a resource for use with mysqli_real_connect()
- mysqli_options() - Set options
- mysqli_ssl_set() - Used for establishing secure connections using SSL
- mysqli_close() - Closes a previously opened database connection
mysqli::real_escape_string
mysqli_real_escape_string
(PHP 5)
mysqli::real_escape_string -- mysqli_real_escape_string — Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection
Opis
Styl obiektowy
$escapestr
)Styl proceduralny
This function is used to create a legal SQL string that you can use in an SQL statement. The given string is encoded to an escaped SQL string, taking into account the current character set of the connection.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
-
escapestr -
The string to be escaped.
Characters encoded are NUL (ASCII 0), \n, \r, \, ', ", and Control-Z.
Zwracane wartości
Returns an escaped string.
Przykłady
Przykład #1 mysqli::real_escape_string() example
Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$mysqli->query("CREATE TEMPORARY TABLE myCity LIKE City");
$city = "'s Hertogenbosch";
/* this query will fail, cause we didn't escape $city */
if (!$mysqli->query("INSERT into myCity (Name) VALUES ('$city')")) {
printf("Error: %s\n", $mysqli->sqlstate);
}
$city = $mysqli->real_escape_string($city);
/* this query with escaped $city will work */
if ($mysqli->query("INSERT into myCity (Name) VALUES ('$city')")) {
printf("%d Row inserted.\n", $mysqli->affected_rows);
}
$mysqli->close();
?>
Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
mysqli_query($link, "CREATE TEMPORARY TABLE myCity LIKE City");
$city = "'s Hertogenbosch";
/* this query will fail, cause we didn't escape $city */
if (!mysqli_query($link, "INSERT into myCity (Name) VALUES ('$city')")) {
printf("Error: %s\n", mysqli_sqlstate($link));
}
$city = mysqli_real_escape_string($link, $city);
/* this query with escaped $city will work */
if (mysqli_query($link, "INSERT into myCity (Name) VALUES ('$city')")) {
printf("%d Row inserted.\n", mysqli_affected_rows($link));
}
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Error: 42000 1 Row inserted.
Notatki
Informacja:
For those accustomed to using mysql_real_escape_string(), note that the arguments of mysqli_real_escape_string() differ from what mysql_real_escape_string() expects. The
linkidentifier comes first in mysqli_real_escape_string(), whereas the string to be escaped comes first in mysql_real_escape_string().
Zobacz też:
- mysqli_character_set_name() - Returns the default character set for the database connection
mysqli::real_query
mysqli_real_query
(PHP 5)
mysqli::real_query -- mysqli_real_query — Execute an SQL query
Opis
Styl obiektowy
$query
)Styl proceduralny
Executes a single query against the database whose result can then be retrieved or stored using the mysqli_store_result() or mysqli_use_result() functions.
In order to determine if a given query should return a result set or not, see mysqli_field_count().
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
-
query -
The query, as a string.
Data inside the query should be properly escaped.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- mysqli_query() - Performs a query on the database
- mysqli_store_result() - Transfers a result set from the last query
- mysqli_use_result() - Initiate a result set retrieval
mysqli::reap_async_query
mysqli_reap_async_query
(PHP 5 >= 5.3.0)
mysqli::reap_async_query -- mysqli_reap_async_query — Get result from async query
Opis
Styl obiektowy
Styl proceduralny
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Get result from async query. Dostępna tylko z mysqlnd.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
Returns mysqli_result in success, FALSE otherwise.
mysqli::refresh
mysqli_refresh
(PHP 5 <= 5.3.0)
mysqli::refresh -- mysqli_refresh — Refreshes
Opis
Styl obiektowy
$options
)Styl proceduralny
$link
, int $options
)Flushes tables or caches, or resets the replication server information.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
-
options -
The options to refresh, using the MYSQLI_REFRESH_* constants as documented within the MySQLi constants documentation.
See also the official » MySQL Refresh documentation.
Zwracane wartości
TRUE if the refresh was a success, otherwise FALSE
mysqli::rollback
mysqli_rollback
(PHP 5)
mysqli::rollback -- mysqli_rollback — Rolls back current transaction
Opis
Styl obiektowy
Styl proceduralny
Rollbacks the current transaction for the database.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 mysqli::rollback() example
Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* disable autocommit */
$mysqli->autocommit(FALSE);
$mysqli->query("CREATE TABLE myCity LIKE City");
$mysqli->query("ALTER TABLE myCity Type=InnoDB");
$mysqli->query("INSERT INTO myCity SELECT * FROM City LIMIT 50");
/* commit insert */
$mysqli->commit();
/* delete all rows */
$mysqli->query("DELETE FROM myCity");
if ($result = $mysqli->query("SELECT COUNT(*) FROM myCity")) {
$row = $result->fetch_row();
printf("%d rows in table myCity.\n", $row[0]);
/* Free result */
$result->close();
}
/* Rollback */
$mysqli->rollback();
if ($result = $mysqli->query("SELECT COUNT(*) FROM myCity")) {
$row = $result->fetch_row();
printf("%d rows in table myCity (after rollback).\n", $row[0]);
/* Free result */
$result->close();
}
/* Drop table myCity */
$mysqli->query("DROP TABLE myCity");
$mysqli->close();
?>
Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* disable autocommit */
mysqli_autocommit($link, FALSE);
mysqli_query($link, "CREATE TABLE myCity LIKE City");
mysqli_query($link, "ALTER TABLE myCity Type=InnoDB");
mysqli_query($link, "INSERT INTO myCity SELECT * FROM City LIMIT 50");
/* commit insert */
mysqli_commit($link);
/* delete all rows */
mysqli_query($link, "DELETE FROM myCity");
if ($result = mysqli_query($link, "SELECT COUNT(*) FROM myCity")) {
$row = mysqli_fetch_row($result);
printf("%d rows in table myCity.\n", $row[0]);
/* Free result */
mysqli_free_result($result);
}
/* Rollback */
mysqli_rollback($link);
if ($result = mysqli_query($link, "SELECT COUNT(*) FROM myCity")) {
$row = mysqli_fetch_row($result);
printf("%d rows in table myCity (after rollback).\n", $row[0]);
/* Free result */
mysqli_free_result($result);
}
/* Drop table myCity */
mysqli_query($link, "DROP TABLE myCity");
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
0 rows in table myCity. 50 rows in table myCity (after rollback).
Zobacz też:
- mysqli_commit() - Commits the current transaction
- mysqli_autocommit() - Turns on or off auto-commiting database modifications
mysqli::rpl_query_type
mysqli_rpl_query_type
(PHP 5)
mysqli::rpl_query_type -- mysqli_rpl_query_type — Returns RPL query type
Opis
Styl obiektowy
$query
)Styl proceduralny
Returns MYSQLI_RPL_MASTER,
MYSQLI_RPL_SLAVE or
MYSQLI_RPL_ADMIN depending on a query type.
INSERT, UPDATE and similar are
master queries, SELECT is
slave, and FLUSH,
REPAIR and similar are admin.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Ta funkcja jest PRZESTARZAŁA i zostanie USUNIĘTA od PHP 5.3.0.
mysqli::select_db
mysqli_select_db
(PHP 5)
mysqli::select_db -- mysqli_select_db — Selects the default database for database queries
Opis
Styl obiektowy
$dbname
)Styl proceduralny
Selects the default database to be used when performing queries against the database connection.
Informacja:
This function should only be used to change the default database for the connection. You can select the default database with 4th parameter in mysqli_connect().
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
-
dbname -
The database name.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 mysqli::select_db() example
Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "test");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* return name of current default database */
if ($result = $mysqli->query("SELECT DATABASE()")) {
$row = $result->fetch_row();
printf("Default database is %s.\n", $row[0]);
$result->close();
}
/* change db to world db */
$mysqli->select_db("world");
/* return name of current default database */
if ($result = $mysqli->query("SELECT DATABASE()")) {
$row = $result->fetch_row();
printf("Default database is %s.\n", $row[0]);
$result->close();
}
$mysqli->close();
?>
Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "test");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* return name of current default database */
if ($result = mysqli_query($link, "SELECT DATABASE()")) {
$row = mysqli_fetch_row($result);
printf("Default database is %s.\n", $row[0]);
mysqli_free_result($result);
}
/* change db to world db */
mysqli_select_db($link, "world");
/* return name of current default database */
if ($result = mysqli_query($link, "SELECT DATABASE()")) {
$row = mysqli_fetch_row($result);
printf("Default database is %s.\n", $row[0]);
mysqli_free_result($result);
}
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Default database is test. Default database is world.
Zobacz też:
- mysqli_connect() - Alias dla mysqli::__construct
- mysqli_real_connect() - Opens a connection to a mysql server
mysqli::send_query
mysqli_send_query
(PHP 5)
mysqli::send_query -- mysqli_send_query — Send the query and return
Opis
Styl obiektowy
$query
)Styl proceduralny
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Ta funkcja jest PRZESTARZAŁA i zostanie USUNIĘTA od PHP 5.3.0.
mysqli::set_charset
mysqli_set_charset
(PHP 5 >= 5.0.5)
mysqli::set_charset -- mysqli_set_charset — Sets the default client character set
Opis
Styl obiektowy
$charset
)Styl proceduralny
Sets the default character set to be used when sending data from and to the database server.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
-
charset -
The charset to be set as default.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Notatki
Informacja:
To use this function on a Windows platform you need MySQL client library version 4.1.11 or above (for MySQL 5.0 you need 5.0.6 or above).
Informacja:
This is the preferred way to change the charset. Using mysqli::query() to execute SET NAMES .. is not recommended.
Przykłady
Przykład #1 mysqli::set_charset() example
Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "test");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* change character set to utf8 */
if (!$mysqli->set_charset("utf8")) {
printf("Error loading character set utf8: %s\n", $mysqli->error);
} else {
printf("Current character set: %s\n", $mysqli->character_set_name());
}
$mysqli->close();
?>
Styl proceduralny
<?php
$link = mysqli_connect('localhost', 'my_user', 'my_password', 'test');
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* change character set to utf8 */
if (!mysqli_set_charset($link, "utf8")) {
printf("Error loading character set utf8: %s\n", mysqli_error($link));
} else {
printf("Current character set: %s\n", mysqli_character_set_name($link));
}
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Current character set: utf8
Zobacz też:
- mysqli_character_set_name() - Returns the default character set for the database connection
- mysqli_real_escape_string() - Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection
- » List of character sets that MySQL supports
mysqli::set_local_infile_default
mysqli_set_local_infile_default
(PHP 5)
mysqli::set_local_infile_default -- mysqli_set_local_infile_default — Unsets user defined handler for load local infile command
Opis
Deactivates a LOAD DATA INFILE LOCAL handler previously set with mysqli_set_local_infile_handler().
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
See mysqli_set_local_infile_handler() examples
Zobacz też:
- mysqli_set_local_infile_handler() - Set callback function for LOAD DATA LOCAL INFILE command
mysqli::set_local_infile_handler
mysqli_set_local_infile_handler
(PHP 5)
mysqli::set_local_infile_handler -- mysqli_set_local_infile_handler — Set callback function for LOAD DATA LOCAL INFILE command
Opis
Styl obiektowy
Styl proceduralny
Set callback function for LOAD DATA LOCAL INFILE command
The callbacks task is to read input from the file specified in the LOAD DATA LOCAL INFILE and to reformat it into the format understood by LOAD DATA INFILE.
The returned data needs to match the format specified in the LOAD DATA
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
-
read_func -
A callback function or object method taking the following parameters:
-
stream -
A PHP stream associated with the SQL commands INFILE
-
&buffer -
A string buffer to store the rewritten input into
-
buflen -
The maximum number of characters to be stored in the buffer
-
&errormsg -
If an error occurs you can store an error message in here
-
The callback function should return the number of characters stored
in the buffer or a negative value if an error
occurred.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 mysqli::set_local_infile_handler() example
Styl obiektowy
<?php
$db = mysqli_init();
$db->real_connect("localhost","root","","test");
function callme($stream, &$buffer, $buflen, &$errmsg)
{
$buffer = fgets($stream);
echo $buffer;
// convert to upper case and replace "," delimiter with [TAB]
$buffer = strtoupper(str_replace(",", "\t", $buffer));
return strlen($buffer);
}
echo "Input:\n";
$db->set_local_infile_handler("callme");
$db->query("LOAD DATA LOCAL INFILE 'input.txt' INTO TABLE t1");
$db->set_local_infile_default();
$res = $db->query("SELECT * FROM t1");
echo "\nResult:\n";
while ($row = $res->fetch_assoc()) {
echo join(",", $row)."\n";
}
?>
Styl proceduralny
<?php
$db = mysqli_init();
mysqli_real_connect($db, "localhost","root","","test");
function callme($stream, &$buffer, $buflen, &$errmsg)
{
$buffer = fgets($stream);
echo $buffer;
// convert to upper case and replace "," delimiter with [TAB]
$buffer = strtoupper(str_replace(",", "\t", $buffer));
return strlen($buffer);
}
echo "Input:\n";
mysqli_set_local_infile_handler($db, "callme");
mysqli_query($db, "LOAD DATA LOCAL INFILE 'input.txt' INTO TABLE t1");
mysqli_set_local_infile_default($db);
$res = mysqli_query($db, "SELECT * FROM t1");
echo "\nResult:\n";
while ($row = mysqli_fetch_assoc($res)) {
echo join(",", $row)."\n";
}
?>
Powyższe przykłady wyświetlą:
Input: 23,foo 42,bar Output: 23,FOO 42,BAR
Zobacz też:
- mysqli_set_local_infile_default() - Unsets user defined handler for load local infile command
mysqli::$sqlstate
mysqli_sqlstate
(PHP 5)
mysqli::$sqlstate -- mysqli_sqlstate — Returns the SQLSTATE error from previous MySQL operation
Opis
Styl obiektowy
Styl proceduralny
Returns a string containing the SQLSTATE error code for the last error. The error code consists of five characters. '00000' means no error. The values are specified by ANSI SQL and ODBC. For a list of possible values, see » http://dev.mysql.com/doc/mysql/en/error-handling.html.
Informacja:
Note that not all MySQL errors are yet mapped to SQLSTATE's. The value HY000 (general error) is used for unmapped errors.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
Returns a string containing the SQLSTATE error code for the last error. The error code consists of five characters. '00000' means no error.
Przykłady
Przykład #1 $mysqli->sqlstate example
Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* Table City already exists, so we should get an error */
if (!$mysqli->query("CREATE TABLE City (ID INT, Name VARCHAR(30))")) {
printf("Error - SQLSTATE %s.\n", $mysqli->sqlstate);
}
$mysqli->close();
?>
Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* Table City already exists, so we should get an error */
if (!mysqli_query($link, "CREATE TABLE City (ID INT, Name VARCHAR(30))")) {
printf("Error - SQLSTATE %s.\n", mysqli_sqlstate($link));
}
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Error - SQLSTATE 42S01.
Zobacz też:
- mysqli_errno() - Returns the error code for the most recent function call
- mysqli_error() - Returns a string description of the last error
mysqli::ssl_set
mysqli_ssl_set
(PHP 5)
mysqli::ssl_set -- mysqli_ssl_set — Used for establishing secure connections using SSL
Opis
Styl obiektowy
$key
, string $cert
, string $ca
, string $capath
, string $cipher
)Styl proceduralny
$link
, string $key
, string $cert
, string $ca
, string $capath
, string $cipher
)Used for establishing secure connections using SSL. It must be called before mysqli_real_connect(). This function does nothing unless OpenSSL support is enabled.
Note that MySQL Native Driver does not support SSL before PHP 5.3.3, so calling this function when using MySQL Native Driver will result in an error. MySQL Native Driver is enabled by default on Microsoft Windows from PHP version 5.3 onwards.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
-
key -
The path name to the key file.
-
cert -
The path name to the certificate file.
-
ca -
The path name to the certificate authority file.
-
capath -
The pathname to a directory that contains trusted SSL CA certificates in PEM format.
-
cipher -
A list of allowable ciphers to use for SSL encryption.
Any unused SSL parameters may be given as NULL
Zwracane wartości
This function always returns TRUE value. If SSL setup is
incorrect mysqli_real_connect() will return an error
when you attempt to connect.
Zobacz też:
- mysqli_options() - Set options
- mysqli_real_connect() - Opens a connection to a mysql server
mysqli::stat
mysqli_stat
(PHP 5)
mysqli::stat -- mysqli_stat — Gets the current system status
Opis
Styl obiektowy
Styl proceduralny
mysqli_stat() returns a string containing information similar to that provided by the 'mysqladmin status' command. This includes uptime in seconds and the number of running threads, questions, reloads, and open tables.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
A string describing the server status. FALSE if an error occurred.
Przykłady
Przykład #1 mysqli::stat() example
Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
printf ("System status: %s\n", $mysqli->stat());
$mysqli->close();
?>
Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
printf("System status: %s\n", mysqli_stat($link));
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
System status: Uptime: 272 Threads: 1 Questions: 5340 Slow queries: 0 Opens: 13 Flush tables: 1 Open tables: 0 Queries per second avg: 19.632 Memory in use: 8496K Max memory used: 8560K
mysqli::stmt_init
mysqli_stmt_init
(PHP 5)
mysqli::stmt_init -- mysqli_stmt_init — Initializes a statement and returns an object for use with mysqli_stmt_prepare
Opis
Styl obiektowy
Styl proceduralny
Allocates and initializes a statement object suitable for mysqli_stmt_prepare().
Informacja:
Any subsequent calls to any mysqli_stmt function will fail until mysqli_stmt_prepare() was called.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
Returns an object.
mysqli::store_result
mysqli_store_result
(PHP 5)
mysqli::store_result -- mysqli_store_result — Transfers a result set from the last query
Opis
Styl obiektowy
Styl proceduralny
Transfers the result set from the last query on the database connection
represented by the link parameter to be used with
the mysqli_data_seek() function.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
Returns a buffered result object or FALSE if an error occurred.
Informacja:
mysqli_store_result() returns
FALSEin case the query didn't return a result set (if the query was, for example an INSERT statement). This function also returnsFALSEif the reading of the result set failed. You can check if you have got an error by checking if mysqli_error() doesn't return an empty string, if mysqli_errno() returns a non zero value, or if mysqli_field_count() returns a non zero value. Also possible reason for this function returningFALSEafter successful call to mysqli_query() can be too large result set (memory for it cannot be allocated). If mysqli_field_count() returns a non-zero value, the statement should have produced a non-empty result set.
Notatki
Informacja:
Although it is always good practice to free the memory used by the result of a query using the mysqli_free_result() function, when transferring large result sets using the mysqli_store_result() this becomes particularly important.
Przykłady
See mysqli_multi_query().
Zobacz też:
- mysqli_real_query() - Execute an SQL query
- mysqli_use_result() - Initiate a result set retrieval
mysqli::$thread_id
mysqli_thread_id
(PHP 5)
mysqli::$thread_id -- mysqli_thread_id — Returns the thread ID for the current connection
Opis
Styl obiektowy
Styl proceduralny
The mysqli_thread_id() function returns the thread ID for the current connection which can then be killed using the mysqli_kill() function. If the connection is lost and you reconnect with mysqli_ping(), the thread ID will be other. Therefore you should get the thread ID only when you need it.
Informacja:
The thread ID is assigned on a connection-by-connection basis. Hence, if the connection is broken and then re-established a new thread ID will be assigned.
To kill a running query you can use the SQL command KILL QUERY processid.
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
Returns the Thread ID for the current connection.
Przykłady
Przykład #1 $mysqli->thread_id example
Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* determine our thread id */
$thread_id = $mysqli->thread_id;
/* Kill connection */
$mysqli->kill($thread_id);
/* This should produce an error */
if (!$mysqli->query("CREATE TABLE myCity LIKE City")) {
printf("Error: %s\n", $mysqli->error);
exit;
}
/* close connection */
$mysqli->close();
?>
Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* determine our thread id */
$thread_id = mysqli_thread_id($link);
/* Kill connection */
mysqli_kill($link, $thread_id);
/* This should produce an error */
if (!mysqli_query($link, "CREATE TABLE myCity LIKE City")) {
printf("Error: %s\n", mysqli_error($link));
exit;
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Error: MySQL server has gone away
mysqli::thread_safe
mysqli_thread_safe
(PHP 5)
mysqli::thread_safe -- mysqli_thread_safe — Returns whether thread safety is given or not
Opis
Styl proceduralny
Tells whether the client library is compiled as thread-safe.
Zwracane wartości
TRUE if the client library is thread-safe, otherwise FALSE.
mysqli::use_result
mysqli_use_result
(PHP 5)
mysqli::use_result -- mysqli_use_result — Initiate a result set retrieval
Opis
Styl obiektowy
Styl proceduralny
Used to initiate the retrieval of a result set from the last query executed using the mysqli_real_query() function on the database connection.
Either this or the mysqli_store_result() function must be called before the results of a query can be retrieved, and one or the other must be called to prevent the next query on that database connection from failing.
Informacja:
The mysqli_use_result() function does not transfer the entire result set from the database and hence cannot be used functions such as mysqli_data_seek() to move to a particular row within the set. To use this functionality, the result set must be stored using mysqli_store_result(). One should not use mysqli_use_result() if a lot of processing on the client side is performed, since this will tie up the server and prevent other threads from updating any tables from which the data is being fetched.
Zwracane wartości
Returns an unbuffered result object or FALSE if an error occurred.
Przykłady
Przykład #1 mysqli::use_result() example
Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT CURRENT_USER();";
$query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";
/* execute multi query */
if ($mysqli->multi_query($query)) {
do {
/* store first result set */
if ($result = $mysqli->use_result()) {
while ($row = $result->fetch_row()) {
printf("%s\n", $row[0]);
}
$result->close();
}
/* print divider */
if ($mysqli->more_results()) {
printf("-----------------\n");
}
} while ($mysqli->next_result());
}
/* close connection */
$mysqli->close();
?>
Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT CURRENT_USER();";
$query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";
/* execute multi query */
if (mysqli_multi_query($link, $query)) {
do {
/* store first result set */
if ($result = mysqli_use_result($link)) {
while ($row = mysqli_fetch_row($result)) {
printf("%s\n", $row[0]);
}
mysqli_free_result($result);
}
/* print divider */
if (mysqli_more_results($link)) {
printf("-----------------\n");
}
} while (mysqli_next_result($link));
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
my_user@localhost ----------------- Amersfoort Maastricht Dordrecht Leiden Haarlemmermeer
Zobacz też:
- mysqli_real_query() - Execute an SQL query
- mysqli_store_result() - Transfers a result set from the last query
mysqli::$warning_count
mysqli_warning_count
(PHP 5)
mysqli::$warning_count -- mysqli_warning_count — Returns the number of warnings from the last query for the given link
Opis
Styl obiektowy
Styl proceduralny
Returns the number of warnings from the last query in the connection.
Informacja:
For retrieving warning messages you can use the SQL command SHOW WARNINGS [limit row_count].
Parametry
-
połączenie -
Tylko styl proceduralny: Identyfikator połączenia zwrócony przez mysqli_connect() lub mysqli_init()
Zwracane wartości
Number of warnings or zero if there are no warnings.
Przykłady
Przykład #1 $mysqli->warning_count example
Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$mysqli->query("CREATE TABLE myCity LIKE City");
/* a remarkable city in Wales */
$query = "INSERT INTO myCity (CountryCode, Name) VALUES('GBR',
'Llanfairpwllgwyngyllgogerychwyrndrobwllllantysiliogogogoch')";
$mysqli->query($query);
if ($mysqli->warning_count) {
if ($result = $mysqli->query("SHOW WARNINGS")) {
$row = $result->fetch_row();
printf("%s (%d): %s\n", $row[0], $row[1], $row[2]);
$result->close();
}
}
/* close connection */
$mysqli->close();
?>
Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
mysqli_query($link, "CREATE TABLE myCity LIKE City");
/* a remarkable long city name in Wales */
$query = "INSERT INTO myCity (CountryCode, Name) VALUES('GBR',
'Llanfairpwllgwyngyllgogerychwyrndrobwllllantysiliogogogoch')";
mysqli_query($link, $query);
if (mysqli_warning_count($link)) {
if ($result = mysqli_query($link, "SHOW WARNINGS")) {
$row = mysqli_fetch_row($result);
printf("%s (%d): %s\n", $row[0], $row[1], $row[2]);
mysqli_free_result($result);
}
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Warning (1264): Data truncated for column 'Name' at row 1
Zobacz też:
- mysqli_errno() - Returns the error code for the most recent function call
- mysqli_error() - Returns a string description of the last error
- mysqli_sqlstate() - Returns the SQLSTATE error from previous MySQL operation
Spis treści
- mysqli::$affected_rows — Gets the number of affected rows in a previous MySQL operation
- mysqli::autocommit — Turns on or off auto-commiting database modifications
- mysqli::change_user — Changes the user of the specified database connection
- mysqli::character_set_name — Returns the default character set for the database connection
- mysqli::$client_info — Returns the MySQL client version as a string
- mysqli::$client_version — Get MySQL client info
- mysqli::close — Closes a previously opened database connection
- mysqli::commit — Commits the current transaction
- mysqli::$connect_errno — Returns the error code from last connect call
- mysqli::$connect_error — Returns a string description of the last connect error
- mysqli::__construct — Open a new connection to the MySQL server
- mysqli::debug — Performs debugging operations
- mysqli::disable_reads_from_master — Disable reads from master
- mysqli::dump_debug_info — Dump debugging information into the log
- mysqli::$errno — Returns the error code for the most recent function call
- mysqli::$error_list — Returns a list of errors from the last command executed
- mysqli::$error — Returns a string description of the last error
- mysqli::$field_count — Returns the number of columns for the most recent query
- mysqli::get_charset — Returns a character set object
- mysqli::get_client_info — Returns the MySQL client version as a string
- mysqli_get_client_stats — Returns client per-process statistics
- mysqli::$client_version — Get MySQL client info
- mysqli::get_connection_stats — Returns statistics about the client connection
- mysqli::$host_info — Returns a string representing the type of connection used
- mysqli::$protocol_version — Returns the version of the MySQL protocol used
- mysqli::$server_info — Returns the version of the MySQL server
- mysqli::$server_version — Returns the version of the MySQL server as an integer
- mysqli::get_warnings — Get result of SHOW WARNINGS
- mysqli::$info — Retrieves information about the most recently executed query
- mysqli::init — Initializes MySQLi and returns a resource for use with mysqli_real_connect()
- mysqli::$insert_id — Returns the auto generated id used in the last query
- mysqli::kill — Asks the server to kill a MySQL thread
- mysqli::more_results — Check if there are any more query results from a multi query
- mysqli::multi_query — Performs a query on the database
- mysqli::next_result — Prepare next result from multi_query
- mysqli::options — Set options
- mysqli::ping — Pings a server connection, or tries to reconnect if the connection has gone down
- mysqli::poll — Poll connections
- mysqli::prepare — Prepare an SQL statement for execution
- mysqli::query — Performs a query on the database
- mysqli::real_connect — Opens a connection to a mysql server
- mysqli::real_escape_string — Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection
- mysqli::real_query — Execute an SQL query
- mysqli::reap_async_query — Get result from async query
- mysqli::refresh — Refreshes
- mysqli::rollback — Rolls back current transaction
- mysqli::rpl_query_type — Returns RPL query type
- mysqli::select_db — Selects the default database for database queries
- mysqli::send_query — Send the query and return
- mysqli::set_charset — Sets the default client character set
- mysqli::set_local_infile_default — Unsets user defined handler for load local infile command
- mysqli::set_local_infile_handler — Set callback function for LOAD DATA LOCAL INFILE command
- mysqli::$sqlstate — Returns the SQLSTATE error from previous MySQL operation
- mysqli::ssl_set — Used for establishing secure connections using SSL
- mysqli::stat — Gets the current system status
- mysqli::stmt_init — Initializes a statement and returns an object for use with mysqli_stmt_prepare
- mysqli::store_result — Transfers a result set from the last query
- mysqli::$thread_id — Returns the thread ID for the current connection
- mysqli::thread_safe — Returns whether thread safety is given or not
- mysqli::use_result — Initiate a result set retrieval
- mysqli::$warning_count — Returns the number of warnings from the last query for the given link
The mysqli_stmt class
(PHP 5)
Wstęp
Represents a prepared statement.
Krótki opis klasy
mysqli_stmt::$affected_rows
mysqli_stmt_affected_rows
(PHP 5)
mysqli_stmt::$affected_rows -- mysqli_stmt_affected_rows — Returns the total number of rows changed, deleted, or inserted by the last executed statement
Opis
Styl obiektowy
Styl proceduralny
Returns the number of rows affected by INSERT, UPDATE, or DELETE query.
This function only works with queries which update a table. In order to get the number of rows from a SELECT query, use mysqli_stmt_num_rows() instead.
Zwracane wartości
An integer greater than zero indicates the number of rows affected or retrieved. Zero indicates that no records where updated for an UPDATE/DELETE statement, no rows matched the WHERE clause in the query or that no query has yet been executed. -1 indicates that the query has returned an error. NULL indicates an invalid argument was supplied to the function.
Informacja:
If the number of affected rows is greater than maximal PHP int value, the number of affected rows will be returned as a string value.
Przykłady
Przykład #1 Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* create temp table */
$mysqli->query("CREATE TEMPORARY TABLE myCountry LIKE Country");
$query = "INSERT INTO myCountry SELECT * FROM Country WHERE Code LIKE ?";
/* prepare statement */
if ($stmt = $mysqli->prepare($query)) {
/* Bind variable for placeholder */
$code = 'A%';
$stmt->bind_param("s", $code);
/* execute statement */
$stmt->execute();
printf("rows inserted: %d\n", $stmt->affected_rows);
/* close statement */
$stmt->close();
}
/* close connection */
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* create temp table */
mysqli_query($link, "CREATE TEMPORARY TABLE myCountry LIKE Country");
$query = "INSERT INTO myCountry SELECT * FROM Country WHERE Code LIKE ?";
/* prepare statement */
if ($stmt = mysqli_prepare($link, $query)) {
/* Bind variable for placeholder */
$code = 'A%';
mysqli_stmt_bind_param($stmt, "s", $code);
/* execute statement */
mysqli_stmt_execute($stmt);
printf("rows inserted: %d\n", mysqli_stmt_affected_rows($stmt));
/* close statement */
mysqli_stmt_close($stmt);
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
rows inserted: 17
Zobacz też:
- mysqli_stmt_num_rows() - Return the number of rows in statements result set
- mysqli_prepare() - Prepare an SQL statement for execution
mysqli_stmt::attr_get
mysqli_stmt_attr_get
(PHP 5)
mysqli_stmt::attr_get -- mysqli_stmt_attr_get — Used to get the current value of a statement attribute
Opis
Styl obiektowy
$attr
)Styl proceduralny
Gets the current value of a statement attribute.
Parametry
-
stmt -
Tylko styl proceduralny: Identyfikator stanu zwrócony przez mysqli_stmt_init().
-
attr -
The attribute that you want to get.
Zwracane wartości
Returns FALSE if the attribute is not found, otherwise returns the value of the attribute.
mysqli_stmt::attr_set
mysqli_stmt_attr_set
(PHP 5)
mysqli_stmt::attr_set -- mysqli_stmt_attr_set — Used to modify the behavior of a prepared statement
Opis
Styl obiektowy
$attr
, int $mode
)Styl proceduralny
Used to modify the behavior of a prepared statement. This function may be called multiple times to set several attributes.
Parametry
-
stmt -
Tylko styl proceduralny: Identyfikator stanu zwrócony przez mysqli_stmt_init().
-
attr -
The attribute that you want to set. It can have one of the following values:
Attribute values Character Description MYSQLI_STMT_ATTR_UPDATE_MAX_LENGTH If set to 1, causes mysqli_stmt_store_result() to update the metadata MYSQL_FIELD->max_length value. MYSQLI_STMT_ATTR_CURSOR_TYPE Type of cursor to open for statement when mysqli_stmt_execute() is invoked. modecan be MYSQLI_CURSOR_TYPE_NO_CURSOR (the default) or MYSQLI_CURSOR_TYPE_READ_ONLY.MYSQLI_STMT_ATTR_PREFETCH_ROWS Number of rows to fetch from server at a time when using a cursor. modecan be in the range from 1 to the maximum value of unsigned long. The default is 1.If you use the MYSQLI_STMT_ATTR_CURSOR_TYPE option with MYSQLI_CURSOR_TYPE_READ_ONLY, a cursor is opened for the statement when you invoke mysqli_stmt_execute(). If there is already an open cursor from a previous mysqli_stmt_execute() call, it closes the cursor before opening a new one. mysqli_stmt_reset() also closes any open cursor before preparing the statement for re-execution. mysqli_stmt_free_result() closes any open cursor.
If you open a cursor for a prepared statement, mysqli_stmt_store_result() is unnecessary.
-
mode -
The value to assign to the attribute.
mysqli_stmt::bind_param
mysqli_stmt_bind_param
(PHP 5)
mysqli_stmt::bind_param -- mysqli_stmt_bind_param — Binds variables to a prepared statement as parameters
Opis
Styl obiektowy
Styl proceduralny
Bind variables for the parameter markers in the SQL statement that was passed to mysqli_prepare().
Informacja:
If data size of a variable exceeds max. allowed packet size (max_allowed_packet), you have to specify b in
typesand use mysqli_stmt_send_long_data() to send the data in packets.
Informacja:
Care must be taken when using mysqli_stmt_bind_param() in conjunction with call_user_func_array(). Note that mysqli_stmt_bind_param() requires parameters to be passed by reference, whereas call_user_func_array() can accept as a parameter a list of variables that can represent references or values.
Parametry
-
stmt -
Tylko styl proceduralny: Identyfikator stanu zwrócony przez mysqli_stmt_init().
-
types -
A string that contains one or more characters which specify the types for the corresponding bind variables:
Type specification chars Character Description i corresponding variable has type integer d corresponding variable has type double s corresponding variable has type string b corresponding variable is a blob and will be sent in packets -
var1 -
The number of variables and length of string
typesmust match the parameters in the statement.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Styl obiektowy
<?php
$mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world');
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$stmt = $mysqli->prepare("INSERT INTO CountryLanguage VALUES (?, ?, ?, ?)");
$stmt->bind_param('sssd', $code, $language, $official, $percent);
$code = 'DEU';
$language = 'Bavarian';
$official = "F";
$percent = 11.2;
/* execute prepared statement */
$stmt->execute();
printf("%d Row inserted.\n", $stmt->affected_rows);
/* close statement and connection */
$stmt->close();
/* Clean up table CountryLanguage */
$mysqli->query("DELETE FROM CountryLanguage WHERE Language='Bavarian'");
printf("%d Row deleted.\n", $mysqli->affected_rows);
/* close connection */
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = mysqli_connect('localhost', 'my_user', 'my_password', 'world');
/* check connection */
if (!$link) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$stmt = mysqli_prepare($link, "INSERT INTO CountryLanguage VALUES (?, ?, ?, ?)");
mysqli_stmt_bind_param($stmt, 'sssd', $code, $language, $official, $percent);
$code = 'DEU';
$language = 'Bavarian';
$official = "F";
$percent = 11.2;
/* execute prepared statement */
mysqli_stmt_execute($stmt);
printf("%d Row inserted.\n", mysqli_stmt_affected_rows($stmt));
/* close statement and connection */
mysqli_stmt_close($stmt);
/* Clean up table CountryLanguage */
mysqli_query($link, "DELETE FROM CountryLanguage WHERE Language='Bavarian'");
printf("%d Row deleted.\n", mysqli_affected_rows($link));
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
1 Row inserted. 1 Row deleted.
Zobacz też:
- mysqli_stmt_bind_result() - Binds variables to a prepared statement for result storage
- mysqli_stmt_execute() - Executes a prepared Query
- mysqli_stmt_fetch() - Fetch results from a prepared statement into the bound variables
- mysqli_prepare() - Prepare an SQL statement for execution
- mysqli_stmt_send_long_data() - Send data in blocks
- mysqli_stmt_errno() - Returns the error code for the most recent statement call
- mysqli_stmt_error() - Returns a string description for last statement error
mysqli_stmt::bind_result
mysqli_stmt_bind_result
(PHP 5)
mysqli_stmt::bind_result -- mysqli_stmt_bind_result — Binds variables to a prepared statement for result storage
Opis
Styl obiektowy
Styl proceduralny
Binds columns in the result set to variables.
When mysqli_stmt_fetch() is called to fetch data, the
MySQL client/server protocol places the data for the bound columns into
the specified variables var1, ....
Informacja:
Note that all columns must be bound after mysqli_stmt_execute() and prior to calling mysqli_stmt_fetch(). Depending on column types bound variables can silently change to the corresponding PHP type.
A column can be bound or rebound at any time, even after a result set has been partially retrieved. The new binding takes effect the next time mysqli_stmt_fetch() is called.
Parametry
-
stmt -
Tylko styl proceduralny: Identyfikator stanu zwrócony przez mysqli_stmt_init().
-
var1 -
The variable to be bound.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* prepare statement */
if ($stmt = $mysqli->prepare("SELECT Code, Name FROM Country ORDER BY Name LIMIT 5")) {
$stmt->execute();
/* bind variables to prepared statement */
$stmt->bind_result($col1, $col2);
/* fetch values */
while ($stmt->fetch()) {
printf("%s %s\n", $col1, $col2);
}
/* close statement */
$stmt->close();
}
/* close connection */
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (!$link) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* prepare statement */
if ($stmt = mysqli_prepare($link, "SELECT Code, Name FROM Country ORDER BY Name LIMIT 5")) {
mysqli_stmt_execute($stmt);
/* bind variables to prepared statement */
mysqli_stmt_bind_result($stmt, $col1, $col2);
/* fetch values */
while (mysqli_stmt_fetch($stmt)) {
printf("%s %s\n", $col1, $col2);
}
/* close statement */
mysqli_stmt_close($stmt);
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
AFG Afghanistan ALB Albania DZA Algeria ASM American Samoa AND Andorra
Zobacz też:
- mysqli_stmt_bind_param() - Binds variables to a prepared statement as parameters
- mysqli_stmt_execute() - Executes a prepared Query
- mysqli_stmt_fetch() - Fetch results from a prepared statement into the bound variables
- mysqli_prepare() - Prepare an SQL statement for execution
- mysqli_stmt_prepare() - Prepare an SQL statement for execution
- mysqli_stmt_init() - Initializes a statement and returns an object for use with mysqli_stmt_prepare
- mysqli_stmt_errno() - Returns the error code for the most recent statement call
- mysqli_stmt_error() - Returns a string description for last statement error
mysqli_stmt::close
mysqli_stmt_close
(PHP 5)
mysqli_stmt::close -- mysqli_stmt_close — Closes a prepared statement
Opis
Styl obiektowy
Styl proceduralny
Closes a prepared statement. mysqli_stmt_close() also deallocates the statement handle. If the current statement has pending or unread results, this function cancels them so that the next query can be executed.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
mysqli_stmt::data_seek
mysqli_stmt_data_seek
(PHP 5)
mysqli_stmt::data_seek -- mysqli_stmt_data_seek — Seeks to an arbitrary row in statement result set
Opis
Styl obiektowy
$offset
)Styl proceduralny
Seeks to an arbitrary result pointer in the statement result set.
mysqli_stmt_store_result() must be called prior to mysqli_stmt_data_seek().
Parametry
-
stmt -
Tylko styl proceduralny: Identyfikator stanu zwrócony przez mysqli_stmt_init().
-
offset -
Must be between zero and the total number of rows minus one (0.. mysqli_stmt_num_rows() - 1).
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 Styl obiektowy
<?php
/* Open a connection */
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT Name, CountryCode FROM City ORDER BY Name";
if ($stmt = $mysqli->prepare($query)) {
/* execute query */
$stmt->execute();
/* bind result variables */
$stmt->bind_result($name, $code);
/* store result */
$stmt->store_result();
/* seek to row no. 400 */
$stmt->data_seek(399);
/* fetch values */
$stmt->fetch();
printf ("City: %s Countrycode: %s\n", $name, $code);
/* close statement */
$stmt->close();
}
/* close connection */
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
/* Open a connection */
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT Name, CountryCode FROM City ORDER BY Name";
if ($stmt = mysqli_prepare($link, $query)) {
/* execute query */
mysqli_stmt_execute($stmt);
/* bind result variables */
mysqli_stmt_bind_result($stmt, $name, $code);
/* store result */
mysqli_stmt_store_result($stmt);
/* seek to row no. 400 */
mysqli_stmt_data_seek($stmt, 399);
/* fetch values */
mysqli_stmt_fetch($stmt);
printf ("City: %s Countrycode: %s\n", $name, $code);
/* close statement */
mysqli_stmt_close($stmt);
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
City: Benin City Countrycode: NGA
mysqli_stmt::$errno
mysqli_stmt_errno
(PHP 5)
mysqli_stmt::$errno -- mysqli_stmt_errno — Returns the error code for the most recent statement call
Opis
Styl obiektowy
Styl proceduralny
Returns the error code for the most recently invoked statement function that can succeed or fail.
Client error message numbers are listed in the MySQL errmsg.h header file, server error message numbers are listed in mysqld_error.h. In the MySQL source distribution you can find a complete list of error messages and error numbers in the file Docs/mysqld_error.txt.
Zwracane wartości
An error code value. Zero means no error occurred.
Przykłady
Przykład #1 Styl obiektowy
<?php
/* Open a connection */
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$mysqli->query("CREATE TABLE myCountry LIKE Country");
$mysqli->query("INSERT INTO myCountry SELECT * FROM Country");
$query = "SELECT Name, Code FROM myCountry ORDER BY Name";
if ($stmt = $mysqli->prepare($query)) {
/* drop table */
$mysqli->query("DROP TABLE myCountry");
/* execute query */
$stmt->execute();
printf("Error: %d.\n", $stmt->errno);
/* close statement */
$stmt->close();
}
/* close connection */
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
/* Open a connection */
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");
$query = "SELECT Name, Code FROM myCountry ORDER BY Name";
if ($stmt = mysqli_prepare($link, $query)) {
/* drop table */
mysqli_query($link, "DROP TABLE myCountry");
/* execute query */
mysqli_stmt_execute($stmt);
printf("Error: %d.\n", mysqli_stmt_errno($stmt));
/* close statement */
mysqli_stmt_close($stmt);
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Error: 1146.
Zobacz też:
- mysqli_stmt_error() - Returns a string description for last statement error
- mysqli_stmt_sqlstate() - Returns SQLSTATE error from previous statement operation
mysqli_stmt::$error_list
mysqli_stmt_error_list
(PHP 5 >= 5.4.0)
mysqli_stmt::$error_list -- mysqli_stmt_error_list — Returns a list of errors from the last statement executed
Opis
Styl obiektowy
Styl proceduralny
Returns an array of errors for the most recently invoked statement function that can succeed or fail.
Zwracane wartości
A list of errors, each as an associative array containing the errno, error, and sqlstate.
Przykłady
Przykład #1 Styl obiektowy
<?php
/* Open a connection */
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$mysqli->query("CREATE TABLE myCountry LIKE Country");
$mysqli->query("INSERT INTO myCountry SELECT * FROM Country");
$query = "SELECT Name, Code FROM myCountry ORDER BY Name";
if ($stmt = $mysqli->prepare($query)) {
/* drop table */
$mysqli->query("DROP TABLE myCountry");
/* execute query */
$stmt->execute();
echo "Error:\n";
print_r($stmt->error_list);
/* close statement */
$stmt->close();
}
/* close connection */
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
/* Open a connection */
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");
$query = "SELECT Name, Code FROM myCountry ORDER BY Name";
if ($stmt = mysqli_prepare($link, $query)) {
/* drop table */
mysqli_query($link, "DROP TABLE myCountry");
/* execute query */
mysqli_stmt_execute($stmt);
echo "Error:\n";
print_r(mysql_stmt_error_list($stmt));
/* close statement */
mysqli_stmt_close($stmt);
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Array
(
[0] => Array
(
[errno] => 1146
[sqlstate] => 42S02
[error] => Table 'world.myCountry' doesn't exist
)
)
Zobacz też:
- mysqli_stmt_error() - Returns a string description for last statement error
- mysqli_stmt_errno() - Returns the error code for the most recent statement call
- mysqli_stmt_sqlstate() - Returns SQLSTATE error from previous statement operation
mysqli_stmt::$error
mysqli_stmt_error
(PHP 5)
mysqli_stmt::$error -- mysqli_stmt_error — Returns a string description for last statement error
Opis
Styl obiektowy
Styl proceduralny
Returns a containing the error message for the most recently invoked statement function that can succeed or fail.
Zwracane wartości
A string that describes the error. An empty string if no error occurred.
Przykłady
Przykład #1 Styl obiektowy
<?php
/* Open a connection */
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$mysqli->query("CREATE TABLE myCountry LIKE Country");
$mysqli->query("INSERT INTO myCountry SELECT * FROM Country");
$query = "SELECT Name, Code FROM myCountry ORDER BY Name";
if ($stmt = $mysqli->prepare($query)) {
/* drop table */
$mysqli->query("DROP TABLE myCountry");
/* execute query */
$stmt->execute();
printf("Error: %s.\n", $stmt->error);
/* close statement */
$stmt->close();
}
/* close connection */
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
/* Open a connection */
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");
$query = "SELECT Name, Code FROM myCountry ORDER BY Name";
if ($stmt = mysqli_prepare($link, $query)) {
/* drop table */
mysqli_query($link, "DROP TABLE myCountry");
/* execute query */
mysqli_stmt_execute($stmt);
printf("Error: %s.\n", mysqli_stmt_error($stmt));
/* close statement */
mysqli_stmt_close($stmt);
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Error: Table 'world.myCountry' doesn't exist.
Zobacz też:
- mysqli_stmt_errno() - Returns the error code for the most recent statement call
- mysqli_stmt_sqlstate() - Returns SQLSTATE error from previous statement operation
mysqli_stmt::execute
mysqli_stmt_execute
(PHP 5)
mysqli_stmt::execute -- mysqli_stmt_execute — Executes a prepared Query
Opis
Styl obiektowy
Styl proceduralny
Executes a query that has been previously prepared using the mysqli_prepare() function. When executed any parameter markers which exist will automatically be replaced with the appropriate data.
If the statement is UPDATE, DELETE, or INSERT, the total number of affected rows can be determined by using the mysqli_stmt_affected_rows() function. Likewise, if the query yields a result set the mysqli_stmt_fetch() function is used.
Informacja:
When using mysqli_stmt_execute(), the mysqli_stmt_fetch() function must be used to fetch the data prior to performing any additional queries.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$mysqli->query("CREATE TABLE myCity LIKE City");
/* Prepare an insert statement */
$query = "INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)";
$stmt = $mysqli->prepare($query);
$stmt->bind_param("sss", $val1, $val2, $val3);
$val1 = 'Stuttgart';
$val2 = 'DEU';
$val3 = 'Baden-Wuerttemberg';
/* Execute the statement */
$stmt->execute();
$val1 = 'Bordeaux';
$val2 = 'FRA';
$val3 = 'Aquitaine';
/* Execute the statement */
$stmt->execute();
/* close statement */
$stmt->close();
/* retrieve all rows from myCity */
$query = "SELECT Name, CountryCode, District FROM myCity";
if ($result = $mysqli->query($query)) {
while ($row = $result->fetch_row()) {
printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
}
/* free result set */
$result->close();
}
/* remove table */
$mysqli->query("DROP TABLE myCity");
/* close connection */
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
mysqli_query($link, "CREATE TABLE myCity LIKE City");
/* Prepare an insert statement */
$query = "INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)";
$stmt = mysqli_prepare($link, $query);
mysqli_stmt_bind_param($stmt, "sss", $val1, $val2, $val3);
$val1 = 'Stuttgart';
$val2 = 'DEU';
$val3 = 'Baden-Wuerttemberg';
/* Execute the statement */
mysqli_stmt_execute($stmt);
$val1 = 'Bordeaux';
$val2 = 'FRA';
$val3 = 'Aquitaine';
/* Execute the statement */
mysqli_stmt_execute($stmt);
/* close statement */
mysqli_stmt_close($stmt);
/* retrieve all rows from myCity */
$query = "SELECT Name, CountryCode, District FROM myCity";
if ($result = mysqli_query($link, $query)) {
while ($row = mysqli_fetch_row($result)) {
printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
}
/* free result set */
mysqli_free_result($result);
}
/* remove table */
mysqli_query($link, "DROP TABLE myCity");
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Stuttgart (DEU,Baden-Wuerttemberg) Bordeaux (FRA,Aquitaine)
Zobacz też:
- mysqli_prepare() - Prepare an SQL statement for execution
- mysqli_stmt_bind_param() - Binds variables to a prepared statement as parameters
mysqli_stmt::fetch
mysqli_stmt_fetch
(PHP 5)
mysqli_stmt::fetch -- mysqli_stmt_fetch — Fetch results from a prepared statement into the bound variables
Opis
Styl obiektowy
Styl proceduralny
Fetch the result from a prepared statement into the variables bound by mysqli_stmt_bind_result().
Informacja:
Note that all columns must be bound by the application before calling mysqli_stmt_fetch().
Informacja:
Data are transferred unbuffered without calling mysqli_stmt_store_result() which can decrease performance (but reduces memory cost).
Zwracane wartości
| Value | Description |
|---|---|
TRUE |
Success. Data has been fetched |
FALSE |
Error occurred |
NULL |
No more rows/data exists or data truncation occurred |
Przykłady
Przykład #1 Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 150,5";
if ($stmt = $mysqli->prepare($query)) {
/* execute statement */
$stmt->execute();
/* bind result variables */
$stmt->bind_result($name, $code);
/* fetch values */
while ($stmt->fetch()) {
printf ("%s (%s)\n", $name, $code);
}
/* close statement */
$stmt->close();
}
/* close connection */
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 150,5";
if ($stmt = mysqli_prepare($link, $query)) {
/* execute statement */
mysqli_stmt_execute($stmt);
/* bind result variables */
mysqli_stmt_bind_result($stmt, $name, $code);
/* fetch values */
while (mysqli_stmt_fetch($stmt)) {
printf ("%s (%s)\n", $name, $code);
}
/* close statement */
mysqli_stmt_close($stmt);
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Rockford (USA) Tallahassee (USA) Salinas (USA) Santa Clarita (USA) Springfield (USA)
Zobacz też:
- mysqli_prepare() - Prepare an SQL statement for execution
- mysqli_stmt_errno() - Returns the error code for the most recent statement call
- mysqli_stmt_error() - Returns a string description for last statement error
- mysqli_stmt_bind_result() - Binds variables to a prepared statement for result storage
mysqli_stmt::$field_count
mysqli_stmt_field_count
(PHP 5)
mysqli_stmt::$field_count -- mysqli_stmt_field_count — Returns the number of field in the given statement
Opis
Styl obiektowy
Styl proceduralny
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
mysqli_stmt::free_result
mysqli_stmt_free_result
(PHP 5)
mysqli_stmt::free_result -- mysqli_stmt_free_result — Frees stored result memory for the given statement handle
Opis
Styl obiektowy
Styl proceduralny
Frees the result memory associated with the statement, which was allocated by mysqli_stmt_store_result().
Zwracane wartości
Nie jest zwracana żadna wartość.
mysqli_stmt::get_result
mysqli_stmt_get_result
(PHP 5 >= 5.3.0)
mysqli_stmt::get_result -- mysqli_stmt_get_result — Gets a result set from a prepared statement
Opis
Styl obiektowy
Styl proceduralny
Call to return a result set from a prepared statement query.
Zwracane wartości
Returns a resultset lub FALSE w przypadku niepowodzenia.
Wyłączenie w natywnym sterowniku MySQL
Dostępna tylko z mysqlnd.
Przykłady
Przykład #1 Styl obiektowy
<?php
$mysqli = new mysqli("127.0.0.1", "user", "password", "world");
if($mysqli->connect_error)
{
die("$mysqli->connect_errno: $myslqi->connect_error");
}
$query = "SELECT Name, Population, Continent FROM Country WHERE Continent=? ORDER BY Name LIMIT 1";
$stmt = $mysqli->stmt_init();
if(!$stmt->prepare($query))
{
print "Failed to prepare statement\n";
}
else
{
$stmt->bind_param("s", $continent);
$continent_array = array('Europe','Africa','Asia','North America');
foreach($continent_array as $continent)
{
$stmt->execute();
$result = $stmt->get_result();
while ($row = $result->fetch_array(MYSQLI_NUM))
{
foreach ($row as $r)
{
print "$r ";
}
print "\n";
}
}
}
$stmt->close();
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = mysqli_connect("127.0.0.1", "user", "password", "world");
if (!$link)
{
$error = mysqli_connect_error();
$errno = mysqli_connect_errno();
print "$errno: $error\n";
exit();
}
$query = "SELECT Name, Population, Continent FROM Country WHERE Continent=? ORDER BY Name LIMIT 1";
$stmt = mysqli_stmt_init($link);
if(!mysqli_stmt_prepare($stmt, $query))
{
print "Failed to prepare statement\n";
}
else
{
mysqli_stmt_bind_param($stmt, "s", $continent);
$continent_array = array('Europe','Africa','Asia','North America');
foreach($continent_array as $continent)
{
mysqli_stmt_execute($stmt);
$result = mysqli_stmt_get_result($stmt);
while ($row = mysqli_fetch_array($result, MYSQLI_NUM))
{
foreach ($row as $r)
{
print "$r ";
}
print "\n";
}
}
}
mysqli_stmt_close($stmt);
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Albania 3401200 Europe Algeria 31471000 Africa Afghanistan 22720000 Asia Anguilla 8000 North America
Zobacz też:
- mysqli_prepare() - Prepare an SQL statement for execution
- mysqli_stmt_result_metadata() - Returns result set metadata from a prepared statement
- mysqli_stmt_fetch() - Fetch results from a prepared statement into the bound variables
- mysqli_fetch_array() - Fetch a result row as an associative, a numeric array, or both
- mysqli_stmt_store_result() - Transfers a result set from a prepared statement
mysqli_stmt::get_warnings
mysqli_stmt_get_warnings
(PHP 5 >= 5.1.0)
mysqli_stmt::get_warnings -- mysqli_stmt_get_warnings — Get result of SHOW WARNINGS
Opis
Styl obiektowy
Styl proceduralny
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
mysqli_stmt::$insert_id
mysqli_stmt_insert_id
(PHP 5)
mysqli_stmt::$insert_id -- mysqli_stmt_insert_id — Get the ID generated from the previous INSERT operation
Opis
Styl obiektowy
Styl proceduralny
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
mysqli_stmt::more_results
mysqli_stmt_more_results
(No version information available, might only be in SVN)
mysqli_stmt::more_results -- mysqli_stmt_more_results — Check if there are more query results from a multiple query
Opis
Styl obiektowy (method):
Styl proceduralny:
$stmt
)Checks if there are more query results from a multiple query.
Zwracane wartości
Returns TRUE if more results exist, otherwise FALSE.
Zobacz też:
- mysqli_stmt::next_result() - Reads the next result from a multiple query
- mysqli::multi_query() - Performs a query on the database
mysqli_stmt::next_result
mysqli_stmt_next_result
(No version information available, might only be in SVN)
mysqli_stmt::next_result -- mysqli_stmt_next_result — Reads the next result from a multiple query
Opis
Styl obiektowy (method):
Styl proceduralny:
$stmt
)Reads the next result from a multiple query.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Błędy/Wyjątki
Emits an E_STRICT level error if a result set does
not exist, and suggests using mysqli_stmt::more_results()
in these cases, before calling mysqli_stmt::next_result().
Zobacz też:
- mysqli_stmt::more_results() - Check if there are more query results from a multiple query
- mysqli::multi_query() - Performs a query on the database
mysqli_stmt::$num_rows
mysqli_stmt_num_rows
(PHP 5)
mysqli_stmt::$num_rows -- mysqli_stmt_num_rows — Return the number of rows in statements result set
Opis
Styl obiektowy
Styl proceduralny
Returns the number of rows in the result set. The use of mysqli_stmt_num_rows() depends on whether or not you used mysqli_stmt_store_result() to buffer the entire result set in the statement handle.
If you use mysqli_stmt_store_result(), mysqli_stmt_num_rows() may be called immediately.
Zwracane wartości
An integer representing the number of rows in result set.
Przykłady
Przykład #1 Styl obiektowy
<?php
/* Open a connection */
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20";
if ($stmt = $mysqli->prepare($query)) {
/* execute query */
$stmt->execute();
/* store result */
$stmt->store_result();
printf("Number of rows: %d.\n", $stmt->num_rows);
/* close statement */
$stmt->close();
}
/* close connection */
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
/* Open a connection */
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20";
if ($stmt = mysqli_prepare($link, $query)) {
/* execute query */
mysqli_stmt_execute($stmt);
/* store result */
mysqli_stmt_store_result($stmt);
printf("Number of rows: %d.\n", mysqli_stmt_num_rows($stmt));
/* close statement */
mysqli_stmt_close($stmt);
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Number of rows: 20.
Zobacz też:
- mysqli_stmt_affected_rows() - Returns the total number of rows changed, deleted, or inserted by the last executed statement
- mysqli_prepare() - Prepare an SQL statement for execution
- mysqli_stmt_store_result() - Transfers a result set from a prepared statement
mysqli_stmt::$param_count
mysqli_stmt_param_count
(PHP 5)
mysqli_stmt::$param_count -- mysqli_stmt_param_count — Returns the number of parameter for the given statement
Opis
Styl obiektowy
Styl proceduralny
Returns the number of parameter markers present in the prepared statement.
Zwracane wartości
Returns an integer representing the number of parameters.
Przykłady
Przykład #1 Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
if ($stmt = $mysqli->prepare("SELECT Name FROM Country WHERE Name=? OR Code=?")) {
$marker = $stmt->param_count;
printf("Statement has %d markers.\n", $marker);
/* close statement */
$stmt->close();
}
/* close connection */
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
if ($stmt = mysqli_prepare($link, "SELECT Name FROM Country WHERE Name=? OR Code=?")) {
$marker = mysqli_stmt_param_count($stmt);
printf("Statement has %d markers.\n", $marker);
/* close statement */
mysqli_stmt_close($stmt);
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Statement has 2 markers.
mysqli_stmt::prepare
mysqli_stmt_prepare
(PHP 5)
mysqli_stmt::prepare -- mysqli_stmt_prepare — Prepare an SQL statement for execution
Opis
Styl obiektowy
Styl proceduralny
Prepares the SQL query pointed to by the null-terminated string query.
The parameter markers must be bound to application variables using mysqli_stmt_bind_param() and/or mysqli_stmt_bind_result() before executing the statement or fetching rows.
Informacja:
In the case where you pass a statement to mysqli_stmt_prepare() that is longer than max_allowed_packet of the server, the returned error codes are different depending on whether you are using MySQL Native Driver (mysqlnd) or MySQL Client Library (libmysql). The behavior is as follows:
mysqlnd on Linux returns an error code of 1153. The error message means "got a packet bigger than max_allowed_packet bytes".
mysqlnd on Windows returns an error code 2006. This error message means "server has gone away".
libmysql on all platforms returns an error code 2006. This error message means "server has gone away".
Parametry
-
stmt -
Tylko styl proceduralny: Identyfikator stanu zwrócony przez mysqli_stmt_init().
-
query -
The query, as a string. It must consist of a single SQL statement.
You can include one or more parameter markers in the SQL statement by embedding question mark (?) characters at the appropriate positions.
Informacja:
You should not add a terminating semicolon or \g to the statement.
Informacja:
The markers are legal only in certain places in SQL statements. For example, they are allowed in the VALUES() list of an INSERT statement (to specify column values for a row), or in a comparison with a column in a WHERE clause to specify a comparison value.
However, they are not allowed for identifiers (such as table or column names), in the select list that names the columns to be returned by a SELECT statement), or to specify both operands of a binary operator such as the = equal sign. The latter restriction is necessary because it would be impossible to determine the parameter type. In general, parameters are legal only in Data Manipulation Language (DML) statements, and not in Data Definition Language (DDL) statements.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$city = "Amersfoort";
/* create a prepared statement */
$stmt = $mysqli->stmt_init();
if ($stmt->prepare("SELECT District FROM City WHERE Name=?")) {
/* bind parameters for markers */
$stmt->bind_param("s", $city);
/* execute query */
$stmt->execute();
/* bind result variables */
$stmt->bind_result($district);
/* fetch value */
$stmt->fetch();
printf("%s is in district %s\n", $city, $district);
/* close statement */
$stmt->close();
}
/* close connection */
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$city = "Amersfoort";
/* create a prepared statement */
$stmt = mysqli_stmt_init($link);
if (mysqli_stmt_prepare($stmt, 'SELECT District FROM City WHERE Name=?')) {
/* bind parameters for markers */
mysqli_stmt_bind_param($stmt, "s", $city);
/* execute query */
mysqli_stmt_execute($stmt);
/* bind result variables */
mysqli_stmt_bind_result($stmt, $district);
/* fetch value */
mysqli_stmt_fetch($stmt);
printf("%s is in district %s\n", $city, $district);
/* close statement */
mysqli_stmt_close($stmt);
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Amersfoort is in district Utrecht
Zobacz też:
- mysqli_stmt_init() - Initializes a statement and returns an object for use with mysqli_stmt_prepare
- mysqli_stmt_execute() - Executes a prepared Query
- mysqli_stmt_fetch() - Fetch results from a prepared statement into the bound variables
- mysqli_stmt_bind_param() - Binds variables to a prepared statement as parameters
- mysqli_stmt_bind_result() - Binds variables to a prepared statement for result storage
- mysqli_stmt_close() - Closes a prepared statement
mysqli_stmt::reset
mysqli_stmt_reset
(PHP 5)
mysqli_stmt::reset -- mysqli_stmt_reset — Resets a prepared statement
Opis
Styl obiektowy
Styl proceduralny
Resets a prepared statement on client and server to state after prepare.
It resets the statement on the server, data sent using mysqli_stmt_send_long_data(), unbuffered result sets and current errors. It does not clear bindings or stored result sets. Stored result sets will be cleared when executing the prepared statement (or closing it).
To prepare a statement with another query use function mysqli_stmt_prepare().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
mysqli_stmt::result_metadata
mysqli_stmt_result_metadata
(PHP 5)
mysqli_stmt::result_metadata -- mysqli_stmt_result_metadata — Returns result set metadata from a prepared statement
Opis
Styl obiektowy
Styl proceduralny
If a statement passed to mysqli_prepare() is one that produces a result set, mysqli_stmt_result_metadata() returns the result object that can be used to process the meta information such as total number of fields and individual field information.
Informacja:
This result set pointer can be passed as an argument to any of the field-based functions that process result set metadata, such as:
The result set structure should be freed when you are done with it, which you can do by passing it to mysqli_free_result()
Informacja:
The result set returned by mysqli_stmt_result_metadata() contains only metadata. It does not contain any row results. The rows are obtained by using the statement handle with mysqli_stmt_fetch().
Zwracane wartości
Returns a result object or FALSE if an error occurred.
Przykłady
Przykład #1 Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "test");
$mysqli->query("DROP TABLE IF EXISTS friends");
$mysqli->query("CREATE TABLE friends (id int, name varchar(20))");
$mysqli->query("INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");
$stmt = $mysqli->prepare("SELECT id, name FROM friends");
$stmt->execute();
/* get resultset for metadata */
$result = $stmt->result_metadata();
/* retrieve field information from metadata result set */
$field = $result->fetch_field();
printf("Fieldname: %s\n", $field->name);
/* close resultset */
$result->close();
/* close connection */
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "test");
mysqli_query($link, "DROP TABLE IF EXISTS friends");
mysqli_query($link, "CREATE TABLE friends (id int, name varchar(20))");
mysqli_query($link, "INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");
$stmt = mysqli_prepare($link, "SELECT id, name FROM friends");
mysqli_stmt_execute($stmt);
/* get resultset for metadata */
$result = mysqli_stmt_result_metadata($stmt);
/* retrieve field information from metadata result set */
$field = mysqli_fetch_field($result);
printf("Fieldname: %s\n", $field->name);
/* close resultset */
mysqli_free_result($result);
/* close connection */
mysqli_close($link);
?>
Zobacz też:
- mysqli_prepare() - Prepare an SQL statement for execution
- mysqli_free_result() - Frees the memory associated with a result
mysqli_stmt::send_long_data
mysqli_stmt_send_long_data
(PHP 5)
mysqli_stmt::send_long_data -- mysqli_stmt_send_long_data — Send data in blocks
Opis
Styl obiektowy
$param_nr
, string $data
)Styl proceduralny
Allows to send parameter data to the server in pieces (or chunks), e.g. if the size of a blob exceeds the size of max_allowed_packet. This function can be called multiple times to send the parts of a character or binary data value for a column, which must be one of the TEXT or BLOB datatypes.
Parametry
-
stmt -
Tylko styl proceduralny: Identyfikator stanu zwrócony przez mysqli_stmt_init().
-
param_nr -
Indicates which parameter to associate the data with. Parameters are numbered beginning with 0.
-
data -
A string containing data to be sent.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Styl obiektowy
<?php
$stmt = $mysqli->prepare("INSERT INTO messages (message) VALUES (?)");
$null = NULL;
$stmt->bind_param("b", $null);
$fp = fopen("messages.txt", "r");
while (!feof($fp)) {
$stmt->send_long_data(0, fread($fp, 8192));
}
fclose($fp);
$stmt->execute();
?>
Zobacz też:
- mysqli_prepare() - Prepare an SQL statement for execution
- mysqli_stmt_bind_param() - Binds variables to a prepared statement as parameters
mysqli_stmt::$sqlstate
mysqli_stmt_sqlstate
(PHP 5)
mysqli_stmt::$sqlstate -- mysqli_stmt_sqlstate — Returns SQLSTATE error from previous statement operation
Opis
Styl obiektowy
Styl proceduralny
Returns a string containing the SQLSTATE error code for the most recently invoked prepared statement function that can succeed or fail. The error code consists of five characters. '00000' means no error. The values are specified by ANSI SQL and ODBC. For a list of possible values, see » http://dev.mysql.com/doc/mysql/en/error-handling.html.
Zwracane wartości
Returns a string containing the SQLSTATE error code for the last error. The error code consists of five characters. '00000' means no error.
Notatki
Informacja:
Note that not all MySQL errors are yet mapped to SQLSTATE's. The value HY000 (general error) is used for unmapped errors.
Przykłady
Przykład #1 Styl obiektowy
<?php
/* Open a connection */
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$mysqli->query("CREATE TABLE myCountry LIKE Country");
$mysqli->query("INSERT INTO myCountry SELECT * FROM Country");
$query = "SELECT Name, Code FROM myCountry ORDER BY Name";
if ($stmt = $mysqli->prepare($query)) {
/* drop table */
$mysqli->query("DROP TABLE myCountry");
/* execute query */
$stmt->execute();
printf("Error: %s.\n", $stmt->sqlstate);
/* close statement */
$stmt->close();
}
/* close connection */
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
/* Open a connection */
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");
$query = "SELECT Name, Code FROM myCountry ORDER BY Name";
if ($stmt = mysqli_prepare($link, $query)) {
/* drop table */
mysqli_query($link, "DROP TABLE myCountry");
/* execute query */
mysqli_stmt_execute($stmt);
printf("Error: %s.\n", mysqli_stmt_sqlstate($stmt));
/* close statement */
mysqli_stmt_close($stmt);
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Error: 42S02.
Zobacz też:
- mysqli_stmt_errno() - Returns the error code for the most recent statement call
- mysqli_stmt_error() - Returns a string description for last statement error
mysqli_stmt::store_result
mysqli_stmt_store_result
(PHP 5)
mysqli_stmt::store_result -- mysqli_stmt_store_result — Transfers a result set from a prepared statement
Opis
Styl obiektowy
Styl proceduralny
You must call mysqli_stmt_store_result() for every query that successfully produces a result set (SELECT, SHOW, DESCRIBE, EXPLAIN), and only if you want to buffer the complete result set by the client, so that the subsequent mysqli_stmt_fetch() call returns buffered data.
Informacja:
It is unnecessary to call mysqli_stmt_store_result() for other queries, but if you do, it will not harm or cause any notable performance in all cases. You can detect whether the query produced a result set by checking if mysqli_stmt_result_metadata() returns NULL.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Styl obiektowy
<?php
/* Open a connection */
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20";
if ($stmt = $mysqli->prepare($query)) {
/* execute query */
$stmt->execute();
/* store result */
$stmt->store_result();
printf("Number of rows: %d.\n", $stmt->num_rows);
/* free result */
$stmt->free_result();
/* close statement */
$stmt->close();
}
/* close connection */
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
/* Open a connection */
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20";
if ($stmt = mysqli_prepare($link, $query)) {
/* execute query */
mysqli_stmt_execute($stmt);
/* store result */
mysqli_stmt_store_result($stmt);
printf("Number of rows: %d.\n", mysqli_stmt_num_rows($stmt));
/* free result */
mysqli_stmt_free_result($stmt);
/* close statement */
mysqli_stmt_close($stmt);
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Number of rows: 20.
Zobacz też:
- mysqli_prepare() - Prepare an SQL statement for execution
- mysqli_stmt_result_metadata() - Returns result set metadata from a prepared statement
- mysqli_stmt_fetch() - Fetch results from a prepared statement into the bound variables
Spis treści
- mysqli_stmt::$affected_rows — Returns the total number of rows changed, deleted, or inserted by the last executed statement
- mysqli_stmt::attr_get — Used to get the current value of a statement attribute
- mysqli_stmt::attr_set — Used to modify the behavior of a prepared statement
- mysqli_stmt::bind_param — Binds variables to a prepared statement as parameters
- mysqli_stmt::bind_result — Binds variables to a prepared statement for result storage
- mysqli_stmt::close — Closes a prepared statement
- mysqli_stmt::data_seek — Seeks to an arbitrary row in statement result set
- mysqli_stmt::$errno — Returns the error code for the most recent statement call
- mysqli_stmt::$error_list — Returns a list of errors from the last statement executed
- mysqli_stmt::$error — Returns a string description for last statement error
- mysqli_stmt::execute — Executes a prepared Query
- mysqli_stmt::fetch — Fetch results from a prepared statement into the bound variables
- mysqli_stmt::$field_count — Returns the number of field in the given statement
- mysqli_stmt::free_result — Frees stored result memory for the given statement handle
- mysqli_stmt::get_result — Gets a result set from a prepared statement
- mysqli_stmt::get_warnings — Get result of SHOW WARNINGS
- mysqli_stmt::$insert_id — Get the ID generated from the previous INSERT operation
- mysqli_stmt::more_results — Check if there are more query results from a multiple query
- mysqli_stmt::next_result — Reads the next result from a multiple query
- mysqli_stmt::$num_rows — Return the number of rows in statements result set
- mysqli_stmt::$param_count — Returns the number of parameter for the given statement
- mysqli_stmt::prepare — Prepare an SQL statement for execution
- mysqli_stmt::reset — Resets a prepared statement
- mysqli_stmt::result_metadata — Returns result set metadata from a prepared statement
- mysqli_stmt::send_long_data — Send data in blocks
- mysqli_stmt::$sqlstate — Returns SQLSTATE error from previous statement operation
- mysqli_stmt::store_result — Transfers a result set from a prepared statement
The mysqli_result class
(PHP 5)
Wstęp
Represents the result set obtained from a query against the database.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.4.0 | Iterator support was added, as mysqli_result now implements Traversable. |
Krótki opis klasy
mysqli_result::$current_field
mysqli_field_tell
(PHP 5)
mysqli_result::$current_field -- mysqli_field_tell — Get current field offset of a result pointer
Opis
Styl obiektowy
Styl proceduralny
Returns the position of the field cursor used for the last mysqli_fetch_field() call. This value can be used as an argument to mysqli_field_seek().
Parametry
-
wynik -
Tylko styl proceduralny: Identyfikator zbioru wyników zwróconych przez mysqli_query(), mysqli_store_result() lub mysqli_use_result().
Zwracane wartości
Returns current offset of field cursor.
Przykłady
Przykład #1 Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";
if ($result = $mysqli->query($query)) {
/* Get field information for all columns */
while ($finfo = $result->fetch_field()) {
/* get fieldpointer offset */
$currentfield = $result->current_field;
printf("Column %d:\n", $currentfield);
printf("Name: %s\n", $finfo->name);
printf("Table: %s\n", $finfo->table);
printf("max. Len: %d\n", $finfo->max_length);
printf("Flags: %d\n", $finfo->flags);
printf("Type: %d\n\n", $finfo->type);
}
$result->close();
}
/* close connection */
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";
if ($result = mysqli_query($link, $query)) {
/* Get field information for all fields */
while ($finfo = mysqli_fetch_field($result)) {
/* get fieldpointer offset */
$currentfield = mysqli_field_tell($result);
printf("Column %d:\n", $currentfield);
printf("Name: %s\n", $finfo->name);
printf("Table: %s\n", $finfo->table);
printf("max. Len: %d\n", $finfo->max_length);
printf("Flags: %d\n", $finfo->flags);
printf("Type: %d\n\n", $finfo->type);
}
mysqli_free_result($result);
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Column 1: Name: Name Table: Country max. Len: 11 Flags: 1 Type: 254 Column 2: Name: SurfaceArea Table: Country max. Len: 10 Flags: 32769 Type: 4
Zobacz też:
- mysqli_fetch_field() - Returns the next field in the result set
- mysqli_field_seek() - Set result pointer to a specified field offset
mysqli_result::data_seek
mysqli_data_seek
(PHP 5)
mysqli_result::data_seek -- mysqli_data_seek — Adjusts the result pointer to an arbitary row in the result
Opis
Styl obiektowy
$offset
)Styl proceduralny
The mysqli_data_seek() function seeks to an arbitrary
result pointer specified by the offset in the
result set.
Parametry
-
wynik -
Tylko styl proceduralny: Identyfikator zbioru wyników zwróconych przez mysqli_query(), mysqli_store_result() lub mysqli_use_result().
-
offset -
The field offset. Must be between zero and the total number of rows minus one (0..mysqli_num_rows() - 1).
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Notatki
Informacja:
This function can only be used with buffered results attained from the use of the mysqli_store_result() or mysqli_query() functions.
Przykłady
Przykład #1 Styl obiektowy
<?php
/* Open a connection */
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT Name, CountryCode FROM City ORDER BY Name";
if ($result = $mysqli->query( $query)) {
/* seek to row no. 400 */
$result->data_seek(399);
/* fetch row */
$row = $result->fetch_row();
printf ("City: %s Countrycode: %s\n", $row[0], $row[1]);
/* free result set*/
$result->close();
}
/* close connection */
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
/* Open a connection */
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (!$link) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT Name, CountryCode FROM City ORDER BY Name";
if ($result = mysqli_query($link, $query)) {
/* seek to row no. 400 */
mysqli_data_seek($result, 399);
/* fetch row */
$row = mysqli_fetch_row($result);
printf ("City: %s Countrycode: %s\n", $row[0], $row[1]);
/* free result set*/
mysqli_free_result($result);
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
City: Benin City Countrycode: NGA
Zobacz też:
- mysqli_store_result() - Transfers a result set from the last query
- mysqli_fetch_row() - Get a result row as an enumerated array
- mysqli_fetch_array() - Fetch a result row as an associative, a numeric array, or both
- mysqli_fetch_assoc() - Fetch a result row as an associative array
- mysqli_fetch_object() - Returns the current row of a result set as an object
- mysqli_query() - Performs a query on the database
- mysqli_num_rows() - Gets the number of rows in a result
mysqli_result::fetch_all
mysqli_fetch_all
(PHP 5 >= 5.3.0)
mysqli_result::fetch_all -- mysqli_fetch_all — Fetches all result rows as an associative array, a numeric array, or both
Opis
Styl obiektowy
Styl proceduralny
mysqli_fetch_all() fetches all result rows and returns the result set as an associative array, a numeric array, or both.
Parametry
-
wynik -
Tylko styl proceduralny: Identyfikator zbioru wyników zwróconych przez mysqli_query(), mysqli_store_result() lub mysqli_use_result().
-
resulttype -
This optional parameter is a constant indicating what type of array should be produced from the current row data. The possible values for this parameter are the constants
MYSQLI_ASSOC,MYSQLI_NUM, orMYSQLI_BOTH.
Zwracane wartości
Returns an array of associative or numeric arrays holding result rows.
Wyłączenie w natywnym sterowniku MySQL
Dostępna tylko z mysqlnd.
As mysqli_fetch_all() returns all the rows as an array in a single step, it may consume more memory than some similar functions such as mysqli_fetch_array(), which only returns one row at a time from the result set. Further, if you need to iterate over the result set, you will need a looping construct that will further impact performance. For these reasons mysqli_fetch_all() should only be used in those situations where the fetched result set will be sent to another layer for processing.
Zobacz też:
- mysqli_fetch_array() - Fetch a result row as an associative, a numeric array, or both
- mysqli_query() - Performs a query on the database
mysqli_result::fetch_array
mysqli_fetch_array
(PHP 5)
mysqli_result::fetch_array -- mysqli_fetch_array — Fetch a result row as an associative, a numeric array, or both
Opis
Styl obiektowy
Styl proceduralny
Returns an array that corresponds to the fetched row or NULL if there
are no more rows for the resultset represented by the
result parameter.
mysqli_fetch_array() is an extended version of the mysqli_fetch_row() function. In addition to storing the data in the numeric indices of the result array, the mysqli_fetch_array() function can also store the data in associative indices, using the field names of the result set as keys.
Informacja: Nazwy pól zwracane przez tą funkcję rozróżniają wielkość znaków.
Informacja: Ta funkcja ustala wartość pól NULL na
NULL.
If two or more columns of the result have the same field names, the last column will take precedence and overwrite the earlier data. In order to access multiple columns with the same name, the numerically indexed version of the row must be used.
Parametry
-
wynik -
Tylko styl proceduralny: Identyfikator zbioru wyników zwróconych przez mysqli_query(), mysqli_store_result() lub mysqli_use_result().
-
resulttype -
This optional parameter is a constant indicating what type of array should be produced from the current row data. The possible values for this parameter are the constants
MYSQLI_ASSOC,MYSQLI_NUM, orMYSQLI_BOTH.By using the
MYSQLI_ASSOCconstant this function will behave identically to the mysqli_fetch_assoc(), whileMYSQLI_NUMwill behave identically to the mysqli_fetch_row() function. The final optionMYSQLI_BOTHwill create a single array with the attributes of both.
Zwracane wartości
Returns an array of strings that corresponds to the fetched row or NULL if there
are no more rows in resultset.
Przykłady
Przykład #1 Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT Name, CountryCode FROM City ORDER by ID LIMIT 3";
$result = $mysqli->query($query);
/* numeric array */
$row = $result->fetch_array(MYSQLI_NUM);
printf ("%s (%s)\n", $row[0], $row[1]);
/* associative array */
$row = $result->fetch_array(MYSQLI_ASSOC);
printf ("%s (%s)\n", $row["Name"], $row["CountryCode"]);
/* associative and numeric array */
$row = $result->fetch_array(MYSQLI_BOTH);
printf ("%s (%s)\n", $row[0], $row["CountryCode"]);
/* free result set */
$result->close();
/* close connection */
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT Name, CountryCode FROM City ORDER by ID LIMIT 3";
$result = mysqli_query($link, $query);
/* numeric array */
$row = mysqli_fetch_array($result, MYSQLI_NUM);
printf ("%s (%s)\n", $row[0], $row[1]);
/* associative array */
$row = mysqli_fetch_array($result, MYSQLI_ASSOC);
printf ("%s (%s)\n", $row["Name"], $row["CountryCode"]);
/* associative and numeric array */
$row = mysqli_fetch_array($result, MYSQLI_BOTH);
printf ("%s (%s)\n", $row[0], $row["CountryCode"]);
/* free result set */
mysqli_free_result($result);
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Kabul (AFG) Qandahar (AFG) Herat (AFG)
Zobacz też:
- mysqli_fetch_assoc() - Fetch a result row as an associative array
- mysqli_fetch_row() - Get a result row as an enumerated array
- mysqli_fetch_object() - Returns the current row of a result set as an object
- mysqli_query() - Performs a query on the database
- mysqli_data_seek() - Adjusts the result pointer to an arbitary row in the result
mysqli_result::fetch_assoc
mysqli_fetch_assoc
(PHP 5)
mysqli_result::fetch_assoc -- mysqli_fetch_assoc — Fetch a result row as an associative array
Opis
Styl obiektowy
Styl proceduralny
Returns an associative array that corresponds to the fetched row or NULL
if there are no more rows.
Informacja: Nazwy pól zwracane przez tą funkcję rozróżniają wielkość znaków.
Informacja: Ta funkcja ustala wartość pól NULL na
NULL.
Parametry
-
wynik -
Tylko styl proceduralny: Identyfikator zbioru wyników zwróconych przez mysqli_query(), mysqli_store_result() lub mysqli_use_result().
Zwracane wartości
Returns an associative array of strings representing the fetched row in the result
set, where each key in the array represents the name of one of the result
set's columns or NULL if there are no more rows in resultset.
If two or more columns of the result have the same field names, the last column will take precedence. To access the other column(s) of the same name, you either need to access the result with numeric indices by using mysqli_fetch_row() or add alias names.
Przykłady
Przykład #1 Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 50,5";
if ($result = $mysqli->query($query)) {
/* fetch associative array */
while ($row = $result->fetch_assoc()) {
printf ("%s (%s)\n", $row["Name"], $row["CountryCode"]);
}
/* free result set */
$result->free();
}
/* close connection */
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 50,5";
if ($result = mysqli_query($link, $query)) {
/* fetch associative array */
while ($row = mysqli_fetch_assoc($result)) {
printf ("%s (%s)\n", $row["Name"], $row["CountryCode"]);
}
/* free result set */
mysqli_free_result($result);
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Pueblo (USA) Arvada (USA) Cape Coral (USA) Green Bay (USA) Santa Clara (USA)
Przykład #3 A mysqli_result example comparing iterator usage
<?php
$c = mysqli_connect('127.0.0.1','user', 'pass');
// Using iterators (support was added with PHP 5.4)
foreach ( $c->query('SELECT user,host FROM mysql.user') as $row ) {
printf("'%s'@'%s'\n", $row['user'], $row['host']);
}
echo "\n==================\n";
// Not using iterators
$result = $c->query('SELECT user,host FROM mysql.user');
while ($row = $result->fetch_assoc()) {
printf("'%s'@'%s'\n", $row['user'], $row['host']);
}
?>
Powyższy przykład wyświetli coś podobnego do:
'root'@'192.168.1.1' 'root'@'127.0.0.1' 'dude'@'localhost' 'lebowski'@'localhost' ================== 'root'@'192.168.1.1' 'root'@'127.0.0.1' 'dude'@'localhost' 'lebowski'@'localhost'
Zobacz też:
- mysqli_fetch_array() - Fetch a result row as an associative, a numeric array, or both
- mysqli_fetch_row() - Get a result row as an enumerated array
- mysqli_fetch_object() - Returns the current row of a result set as an object
- mysqli_query() - Performs a query on the database
- mysqli_data_seek() - Adjusts the result pointer to an arbitary row in the result
mysqli_result::fetch_field_direct
mysqli_fetch_field_direct
(PHP 5)
mysqli_result::fetch_field_direct -- mysqli_fetch_field_direct — Fetch meta-data for a single field
Opis
Styl obiektowy
$fieldnr
)Styl proceduralny
Returns an object which contains field definition information from the specified result set.
Parametry
-
wynik -
Tylko styl proceduralny: Identyfikator zbioru wyników zwróconych przez mysqli_query(), mysqli_store_result() lub mysqli_use_result().
-
fieldnr -
The field number. This value must be in the range from 0 to number of fields - 1.
Zwracane wartości
Returns an object which contains field definition information or FALSE
if no field information for specified fieldnr is
available.
| Attribute | Description |
|---|---|
| name | The name of the column |
| orgname | Original column name if an alias was specified |
| table | The name of the table this field belongs to (if not calculated) |
| orgtable | Original table name if an alias was specified |
| def | The default value for this field, represented as a string |
| max_length | The maximum width of the field for the result set. |
| length | The width of the field, as specified in the table definition. |
| charsetnr | The character set number for the field. |
| flags | An integer representing the bit-flags for the field. |
| type | The data type used for this field |
| decimals | The number of decimals used (for integer fields) |
Przykłady
Przykład #1 Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT Name, SurfaceArea from Country ORDER BY Name LIMIT 5";
if ($result = $mysqli->query($query)) {
/* Get field information for column 'SurfaceArea' */
$finfo = $result->fetch_field_direct(1);
printf("Name: %s\n", $finfo->name);
printf("Table: %s\n", $finfo->table);
printf("max. Len: %d\n", $finfo->max_length);
printf("Flags: %d\n", $finfo->flags);
printf("Type: %d\n", $finfo->type);
$result->close();
}
/* close connection */
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT Name, SurfaceArea from Country ORDER BY Name LIMIT 5";
if ($result = mysqli_query($link, $query)) {
/* Get field information for column 'SurfaceArea' */
$finfo = mysqli_fetch_field_direct($result, 1);
printf("Name: %s\n", $finfo->name);
printf("Table: %s\n", $finfo->table);
printf("max. Len: %d\n", $finfo->max_length);
printf("Flags: %d\n", $finfo->flags);
printf("Type: %d\n", $finfo->type);
mysqli_free_result($result);
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Name: SurfaceArea Table: Country max. Len: 10 Flags: 32769 Type: 4
Zobacz też:
- mysqli_num_fields() - Get the number of fields in a result
- mysqli_fetch_field() - Returns the next field in the result set
- mysqli_fetch_fields() - Returns an array of objects representing the fields in a result set
mysqli_result::fetch_field
mysqli_fetch_field
(PHP 5)
mysqli_result::fetch_field -- mysqli_fetch_field — Returns the next field in the result set
Opis
Styl obiektowy
Styl proceduralny
Returns the definition of one column of a result set as an object. Call this function repeatedly to retrieve information about all columns in the result set.
Parametry
-
wynik -
Tylko styl proceduralny: Identyfikator zbioru wyników zwróconych przez mysqli_query(), mysqli_store_result() lub mysqli_use_result().
Zwracane wartości
Returns an object which contains field definition information or FALSE
if no field information is available.
| Property | Description |
|---|---|
| name | The name of the column |
| orgname | Original column name if an alias was specified |
| table | The name of the table this field belongs to (if not calculated) |
| orgtable | Original table name if an alias was specified |
| def | Reserved for default value, currently always "" |
| db | Database (since PHP 5.3.6) |
| catalog | The catalog name, always "def" (since PHP 5.3.6) |
| max_length | The maximum width of the field for the result set. |
| length | The width of the field, as specified in the table definition. |
| charsetnr | The character set number for the field. |
| flags | An integer representing the bit-flags for the field. |
| type | The data type used for this field |
| decimals | The number of decimals used (for integer fields) |
Przykłady
Przykład #1 Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";
if ($result = $mysqli->query($query)) {
/* Get field information for all columns */
while ($finfo = $result->fetch_field()) {
printf("Name: %s\n", $finfo->name);
printf("Table: %s\n", $finfo->table);
printf("max. Len: %d\n", $finfo->max_length);
printf("Flags: %d\n", $finfo->flags);
printf("Type: %d\n\n", $finfo->type);
}
$result->close();
}
/* close connection */
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";
if ($result = mysqli_query($link, $query)) {
/* Get field information for all fields */
while ($finfo = mysqli_fetch_field($result)) {
printf("Name: %s\n", $finfo->name);
printf("Table: %s\n", $finfo->table);
printf("max. Len: %d\n", $finfo->max_length);
printf("Flags: %d\n", $finfo->flags);
printf("Type: %d\n\n", $finfo->type);
}
mysqli_free_result($result);
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Name: Name Table: Country max. Len: 11 Flags: 1 Type: 254 Name: SurfaceArea Table: Country max. Len: 10 Flags: 32769 Type: 4
Zobacz też:
- mysqli_num_fields() - Get the number of fields in a result
- mysqli_fetch_field_direct() - Fetch meta-data for a single field
- mysqli_fetch_fields() - Returns an array of objects representing the fields in a result set
- mysqli_field_seek() - Set result pointer to a specified field offset
mysqli_result::fetch_fields
mysqli_fetch_fields
(PHP 5)
mysqli_result::fetch_fields -- mysqli_fetch_fields — Returns an array of objects representing the fields in a result set
Opis
Styl obiektowy
Styl proceduralny
This function serves an identical purpose to the mysqli_fetch_field() function with the single difference that, instead of returning one object at a time for each field, the columns are returned as an array of objects.
Parametry
-
wynik -
Tylko styl proceduralny: Identyfikator zbioru wyników zwróconych przez mysqli_query(), mysqli_store_result() lub mysqli_use_result().
Zwracane wartości
Returns an array of objects which contains field definition information or
FALSE if no field information is available.
| Property | Description |
|---|---|
| name | The name of the column |
| orgname | Original column name if an alias was specified |
| table | The name of the table this field belongs to (if not calculated) |
| orgtable | Original table name if an alias was specified |
| max_length | The maximum width of the field for the result set. |
| length | The width of the field, as specified in the table definition. |
| charsetnr | The character set number for the field. |
| flags | An integer representing the bit-flags for the field. |
| type | The data type used for this field |
| decimals | The number of decimals used (for integer fields) |
Przykłady
Przykład #1 Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";
if ($result = $mysqli->query($query)) {
/* Get field information for all columns */
$finfo = $result->fetch_fields();
foreach ($finfo as $val) {
printf("Name: %s\n", $val->name);
printf("Table: %s\n", $val->table);
printf("max. Len: %d\n", $val->max_length);
printf("Flags: %d\n", $val->flags);
printf("Type: %d\n\n", $val->type);
}
$result->close();
}
/* close connection */
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";
if ($result = mysqli_query($link, $query)) {
/* Get field information for all columns */
$finfo = mysqli_fetch_fields($result);
foreach ($finfo as $val) {
printf("Name: %s\n", $val->name);
printf("Table: %s\n", $val->table);
printf("max. Len: %d\n", $val->max_length);
printf("Flags: %d\n", $val->flags);
printf("Type: %d\n\n", $val->type);
}
mysqli_free_result($result);
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Name: Name Table: Country max. Len: 11 Flags: 1 Type: 254 Name: SurfaceArea Table: Country max. Len: 10 Flags: 32769 Type: 4
Zobacz też:
- mysqli_num_fields() - Get the number of fields in a result
- mysqli_fetch_field_direct() - Fetch meta-data for a single field
- mysqli_fetch_field() - Returns the next field in the result set
mysqli_result::fetch_object
mysqli_fetch_object
(PHP 5)
mysqli_result::fetch_object -- mysqli_fetch_object — Returns the current row of a result set as an object
Opis
Styl obiektowy
$class_name
[, array $params
]] )Styl proceduralny
The mysqli_fetch_object() will return the current row result set as an object where the attributes of the object represent the names of the fields found within the result set.
Note that mysqli_fetch_object() sets the properties of the object before calling the object constructor.
Parametry
-
wynik -
Tylko styl proceduralny: Identyfikator zbioru wyników zwróconych przez mysqli_query(), mysqli_store_result() lub mysqli_use_result().
-
class_name -
The name of the class to instantiate, set the properties of and return. If not specified, a stdClass object is returned.
-
params -
An optional array of parameters to pass to the constructor for
class_nameobjects.
Zwracane wartości
Returns an object with string properties that corresponds to the fetched
row or NULL if there are no more rows in resultset.
Informacja: Nazwy pól zwracane przez tą funkcję rozróżniają wielkość znaków.
Informacja: Ta funkcja ustala wartość pól NULL na
NULL.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.0.0 | Added the ability to return as a different object. |
Przykłady
Przykład #1 Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 50,5";
if ($result = $mysqli->query($query)) {
/* fetch object array */
while ($obj = $result->fetch_object()) {
printf ("%s (%s)\n", $obj->Name, $obj->CountryCode);
}
/* free result set */
$result->close();
}
/* close connection */
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 50,5";
if ($result = mysqli_query($link, $query)) {
/* fetch associative array */
while ($obj = mysqli_fetch_object($result)) {
printf ("%s (%s)\n", $obj->Name, $obj->CountryCode);
}
/* free result set */
mysqli_free_result($result);
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Pueblo (USA) Arvada (USA) Cape Coral (USA) Green Bay (USA) Santa Clara (USA)
Zobacz też:
- mysqli_fetch_array() - Fetch a result row as an associative, a numeric array, or both
- mysqli_fetch_assoc() - Fetch a result row as an associative array
- mysqli_fetch_row() - Get a result row as an enumerated array
- mysqli_query() - Performs a query on the database
- mysqli_data_seek() - Adjusts the result pointer to an arbitary row in the result
mysqli_result::fetch_row
mysqli_fetch_row
(PHP 5)
mysqli_result::fetch_row -- mysqli_fetch_row — Get a result row as an enumerated array
Opis
Styl obiektowy
Styl proceduralny
Fetches one row of data from the result set and returns it as an enumerated
array, where each column is stored in an array offset starting from 0 (zero).
Each subsequent call to this function will return the next row within the
result set, or NULL if there are no more rows.
Parametry
-
wynik -
Tylko styl proceduralny: Identyfikator zbioru wyników zwróconych przez mysqli_query(), mysqli_store_result() lub mysqli_use_result().
Zwracane wartości
mysqli_fetch_row() returns an array of strings that corresponds to the fetched row
or NULL if there are no more rows in result set.
Informacja: Ta funkcja ustala wartość pól NULL na
NULL.
Przykłady
Przykład #1 Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 50,5";
if ($result = $mysqli->query($query)) {
/* fetch object array */
while ($row = $result->fetch_row()) {
printf ("%s (%s)\n", $row[0], $row[1]);
}
/* free result set */
$result->close();
}
/* close connection */
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 50,5";
if ($result = mysqli_query($link, $query)) {
/* fetch associative array */
while ($row = mysqli_fetch_row($result)) {
printf ("%s (%s)\n", $row[0], $row[1]);
}
/* free result set */
mysqli_free_result($result);
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Pueblo (USA) Arvada (USA) Cape Coral (USA) Green Bay (USA) Santa Clara (USA)
Zobacz też:
- mysqli_fetch_array() - Fetch a result row as an associative, a numeric array, or both
- mysqli_fetch_assoc() - Fetch a result row as an associative array
- mysqli_fetch_object() - Returns the current row of a result set as an object
- mysqli_query() - Performs a query on the database
- mysqli_data_seek() - Adjusts the result pointer to an arbitary row in the result
mysqli_result::$field_count
mysqli_num_fields
(PHP 5)
mysqli_result::$field_count -- mysqli_num_fields — Get the number of fields in a result
Opis
Styl obiektowy
Styl proceduralny
Returns the number of fields from specified result set.
Parametry
-
wynik -
Tylko styl proceduralny: Identyfikator zbioru wyników zwróconych przez mysqli_query(), mysqli_store_result() lub mysqli_use_result().
Zwracane wartości
The number of fields from a result set.
Przykłady
Przykład #1 Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
if ($result = $mysqli->query("SELECT * FROM City ORDER BY ID LIMIT 1")) {
/* determine number of fields in result set */
$field_cnt = $result->field_count;
printf("Result set has %d fields.\n", $field_cnt);
/* close result set */
$result->close();
}
/* close connection */
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
if ($result = mysqli_query($link, "SELECT * FROM City ORDER BY ID LIMIT 1")) {
/* determine number of fields in result set */
$field_cnt = mysqli_num_fields($result);
printf("Result set has %d fields.\n", $field_cnt);
/* close result set */
mysqli_free_result($result);
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Result set has 5 fields.
mysqli_result::field_seek
mysqli_field_seek
(PHP 5)
mysqli_result::field_seek -- mysqli_field_seek — Set result pointer to a specified field offset
Opis
Styl obiektowy
$fieldnr
)Styl proceduralny
Sets the field cursor to the given offset. The next call to mysqli_fetch_field() will retrieve the field definition of the column associated with that offset.
Informacja:
To seek to the beginning of a row, pass an offset value of zero.
Parametry
-
wynik -
Tylko styl proceduralny: Identyfikator zbioru wyników zwróconych przez mysqli_query(), mysqli_store_result() lub mysqli_use_result().
-
fieldnr -
The field number. This value must be in the range from 0 to number of fields - 1.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";
if ($result = $mysqli->query($query)) {
/* Get field information for 2nd column */
$result->field_seek(1);
$finfo = $result->fetch_field();
printf("Name: %s\n", $finfo->name);
printf("Table: %s\n", $finfo->table);
printf("max. Len: %d\n", $finfo->max_length);
printf("Flags: %d\n", $finfo->flags);
printf("Type: %d\n\n", $finfo->type);
$result->close();
}
/* close connection */
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";
if ($result = mysqli_query($link, $query)) {
/* Get field information for 2nd column */
mysqli_field_seek($result, 1);
$finfo = mysqli_fetch_field($result);
printf("Name: %s\n", $finfo->name);
printf("Table: %s\n", $finfo->table);
printf("max. Len: %d\n", $finfo->max_length);
printf("Flags: %d\n", $finfo->flags);
printf("Type: %d\n\n", $finfo->type);
mysqli_free_result($result);
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Name: SurfaceArea Table: Country max. Len: 10 Flags: 32769 Type: 4
mysqli_result::free
mysqli_free_result
(PHP 5)
mysqli_result::free -- mysqli_free_result — Frees the memory associated with a result
Opis
Styl obiektowy
Styl proceduralny
Frees the memory associated with the result.
Informacja:
You should always free your result with mysqli_free_result(), when your result object is not needed anymore.
Parametry
-
wynik -
Tylko styl proceduralny: Identyfikator zbioru wyników zwróconych przez mysqli_query(), mysqli_store_result() lub mysqli_use_result().
Zwracane wartości
Nie jest zwracana żadna wartość.
Zobacz też:
- mysqli_query() - Performs a query on the database
- mysqli_stmt_store_result() - Transfers a result set from a prepared statement
- mysqli_store_result() - Transfers a result set from the last query
- mysqli_use_result() - Initiate a result set retrieval
mysqli_result::$lengths
mysqli_fetch_lengths
(PHP 5)
mysqli_result::$lengths -- mysqli_fetch_lengths — Returns the lengths of the columns of the current row in the result set
Opis
Styl obiektowy
Styl proceduralny
The mysqli_fetch_lengths() function returns an array containing the lengths of every column of the current row within the result set.
Parametry
-
wynik -
Tylko styl proceduralny: Identyfikator zbioru wyników zwróconych przez mysqli_query(), mysqli_store_result() lub mysqli_use_result().
Zwracane wartości
An array of integers representing the size of each column (not including
any terminating null characters). FALSE if an error occurred.
mysqli_fetch_lengths() is valid only for the current
row of the result set. It returns FALSE if you call it before calling
mysqli_fetch_row/array/object or after retrieving all rows in the result.
Przykłady
Przykład #1 Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT * from Country ORDER BY Code LIMIT 1";
if ($result = $mysqli->query($query)) {
$row = $result->fetch_row();
/* display column lengths */
foreach ($result->lengths as $i => $val) {
printf("Field %2d has Length %2d\n", $i+1, $val);
}
$result->close();
}
/* close connection */
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
$query = "SELECT * from Country ORDER BY Code LIMIT 1";
if ($result = mysqli_query($link, $query)) {
$row = mysqli_fetch_row($result);
/* display column lengths */
foreach (mysqli_fetch_lengths($result) as $i => $val) {
printf("Field %2d has Length %2d\n", $i+1, $val);
}
mysqli_free_result($result);
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Field 1 has Length 3 Field 2 has Length 5 Field 3 has Length 13 Field 4 has Length 9 Field 5 has Length 6 Field 6 has Length 1 Field 7 has Length 6 Field 8 has Length 4 Field 9 has Length 6 Field 10 has Length 6 Field 11 has Length 5 Field 12 has Length 44 Field 13 has Length 7 Field 14 has Length 3 Field 15 has Length 2
mysqli_result::$num_rows
mysqli_num_rows
(PHP 5)
mysqli_result::$num_rows -- mysqli_num_rows — Gets the number of rows in a result
Opis
Styl obiektowy
Styl proceduralny
Returns the number of rows in the result set.
The behaviour of mysqli_num_rows() depends on whether buffered or unbuffered result sets are being used. For unbuffered result sets, mysqli_num_rows() will not return the correct number of rows until all the rows in the result have been retrieved.
Parametry
-
wynik -
Tylko styl proceduralny: Identyfikator zbioru wyników zwróconych przez mysqli_query(), mysqli_store_result() lub mysqli_use_result().
Zwracane wartości
Returns number of rows in the result set.
Informacja:
If the number of rows is greater than
MAXINT, the number will be returned as a string.
Przykłady
Przykład #1 Styl obiektowy
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
if ($result = $mysqli->query("SELECT Code, Name FROM Country ORDER BY Name")) {
/* determine number of rows result set */
$row_cnt = $result->num_rows;
printf("Result set has %d rows.\n", $row_cnt);
/* close result set */
$result->close();
}
/* close connection */
$mysqli->close();
?>
Przykład #2 Styl proceduralny
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
if ($result = mysqli_query($link, "SELECT Code, Name FROM Country ORDER BY Name")) {
/* determine number of rows result set */
$row_cnt = mysqli_num_rows($result);
printf("Result set has %d rows.\n", $row_cnt);
/* close result set */
mysqli_free_result($result);
}
/* close connection */
mysqli_close($link);
?>
Powyższe przykłady wyświetlą:
Result set has 239 rows.
Zobacz też:
- mysqli_affected_rows() - Gets the number of affected rows in a previous MySQL operation
- mysqli_store_result() - Transfers a result set from the last query
- mysqli_use_result() - Initiate a result set retrieval
- mysqli_query() - Performs a query on the database
Spis treści
- mysqli_result::$current_field — Get current field offset of a result pointer
- mysqli_result::data_seek — Adjusts the result pointer to an arbitary row in the result
- mysqli_result::fetch_all — Fetches all result rows as an associative array, a numeric array, or both
- mysqli_result::fetch_array — Fetch a result row as an associative, a numeric array, or both
- mysqli_result::fetch_assoc — Fetch a result row as an associative array
- mysqli_result::fetch_field_direct — Fetch meta-data for a single field
- mysqli_result::fetch_field — Returns the next field in the result set
- mysqli_result::fetch_fields — Returns an array of objects representing the fields in a result set
- mysqli_result::fetch_object — Returns the current row of a result set as an object
- mysqli_result::fetch_row — Get a result row as an enumerated array
- mysqli_result::$field_count — Get the number of fields in a result
- mysqli_result::field_seek — Set result pointer to a specified field offset
- mysqli_result::free — Frees the memory associated with a result
- mysqli_result::$lengths — Returns the lengths of the columns of the current row in the result set
- mysqli_result::$num_rows — Gets the number of rows in a result
The mysqli_driver class
(PHP 5)
Wstęp
MySQLi Driver.
Krótki opis klasy
Właściwości
- client_info
-
The Client API header version
- client_version
-
The Client version
- driver_version
-
The MySQLi Driver version
- embedded
-
Whether MySQLi Embedded support is enabled
- reconnect
-
Allow or prevent reconnect (see the mysqli.reconnect INI directive)
- report_mode
-
Set to
MYSQLI_REPORT_OFF,MYSQLI_REPORT_ALLor any combination ofMYSQLI_REPORT_STRICT(throw Exceptions for errors),MYSQLI_REPORT_ERROR(report errors) andMYSQLI_REPORT_INDEX(errors regarding indexes). See also mysqli_report().
mysqli_driver::embedded_server_end
mysqli_embedded_server_end
(PHP 5)
mysqli_driver::embedded_server_end -- mysqli_embedded_server_end — Stop embedded server
Opis
Styl obiektowy
Styl proceduralny
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
mysqli_driver::embedded_server_start
mysqli_embedded_server_start
(PHP 5)
mysqli_driver::embedded_server_start -- mysqli_embedded_server_start — Initialize and start embedded server
Opis
Styl obiektowy
$start
, array $arguments
, array $groups
)Styl proceduralny
$start
, array $arguments
, array $groups
)Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Spis treści
- mysqli_driver::embedded_server_end — Stop embedded server
- mysqli_driver::embedded_server_start — Initialize and start embedded server
The mysqli_warning class
(PHP 5)
Wstęp
Represents a MySQL warning.
Krótki opis klasy
Właściwości
- message
-
Message string
- sqlstate
-
SQL state
- errno
-
Error number
mysqli_warning::__construct
(PHP 5)
mysqli_warning::__construct — The __construct purpose
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
mysqli_warning::next
(PHP 5)
mysqli_warning::next — The next purpose
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Spis treści
- mysqli_warning::__construct — The __construct purpose
- mysqli_warning::next — The next purpose
The mysqli_sql_exception class
(PHP 5)
Wstęp
The mysqli exception handling class.
Krótki opis klasy
Właściwości
- message
-
The error message.
- file
-
The file with the error.
- line
-
The line with the error.
- code
-
The code causing the error.
- sqlstate
-
The sql state with the error.
Aliases and deprecated Mysqli Funkcje
Opis
This function is an alias of mysqli_stmt_bind_param().
Notatki
Informacja:
mysqli_bind_param() is deprecated and will be removed.
Opis
This function is an alias of mysqli_stmt_bind_result().
Notatki
Informacja:
mysqli_bind_result() is deprecated and will be removed.
Opis
This function is an alias of mysqli_character_set_name().
Zobacz też:
- mysqli_real_escape_string() - Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection
Opis
Ta funkcja jest aliasem dla: mysqli::__construct()
mysqli_disable_rpl_parse
(PHP 5)
mysqli_disable_rpl_parse — Disable RPL parse
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Ta funkcja jest PRZESTARZAŁA i zostanie USUNIĘTA od PHP 5.3.0.
mysqli_enable_reads_from_master
(PHP 5)
mysqli_enable_reads_from_master — Enable reads from master
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Ta funkcja jest PRZESTARZAŁA i zostanie USUNIĘTA od PHP 5.3.0.
mysqli_enable_rpl_parse
(PHP 5)
mysqli_enable_rpl_parse — Enable RPL parse
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Ta funkcja jest PRZESTARZAŁA i zostanie USUNIĘTA od PHP 5.3.0.
Opis
Ta funkcja jest aliasem dla: mysqli_real_escape_string().
Opis
This function is an alias of mysqli_stmt_execute().
Notatki
Informacja:
mysqli_execute() is deprecated and will be removed.
Opis
This function is an alias of mysqli_stmt_fetch().
Notatki
Informacja:
mysqli_fetch() is deprecated and will be removed.
mysqli_get_cache_stats
(PHP 5 >= 5.3.0)
mysqli_get_cache_stats — Returns client Zval cache statistics
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Returns client Zval cache statistics. Dostępna tylko z mysqlnd.
Parametry
Zwracane wartości
Returns an array with client Zval cache stats if success, FALSE otherwise.
Przykłady
Przykład #1 A mysqli_get_cache_stats() example
<?php
$link = mysqli_connect();
print_r(mysqli_get_cache_stats());
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[bytes_sent] => 43
[bytes_received] => 80
[packets_sent] => 1
[packets_received] => 2
[protocol_overhead_in] => 8
[protocol_overhead_out] => 4
[bytes_received_ok_packet] => 11
[bytes_received_eof_packet] => 0
[bytes_received_rset_header_packet] => 0
[bytes_received_rset_field_meta_packet] => 0
[bytes_received_rset_row_packet] => 0
[bytes_received_prepare_response_packet] => 0
[bytes_received_change_user_packet] => 0
[packets_sent_command] => 0
[packets_received_ok] => 1
[packets_received_eof] => 0
[packets_received_rset_header] => 0
[packets_received_rset_field_meta] => 0
[packets_received_rset_row] => 0
[packets_received_prepare_response] => 0
[packets_received_change_user] => 0
[result_set_queries] => 0
[non_result_set_queries] => 0
[no_index_used] => 0
[bad_index_used] => 0
[slow_queries] => 0
[buffered_sets] => 0
[unbuffered_sets] => 0
[ps_buffered_sets] => 0
[ps_unbuffered_sets] => 0
[flushed_normal_sets] => 0
[flushed_ps_sets] => 0
[ps_prepared_never_executed] => 0
[ps_prepared_once_executed] => 0
[rows_fetched_from_server_normal] => 0
[rows_fetched_from_server_ps] => 0
[rows_buffered_from_client_normal] => 0
[rows_buffered_from_client_ps] => 0
[rows_fetched_from_client_normal_buffered] => 0
[rows_fetched_from_client_normal_unbuffered] => 0
[rows_fetched_from_client_ps_buffered] => 0
[rows_fetched_from_client_ps_unbuffered] => 0
[rows_fetched_from_client_ps_cursor] => 0
[rows_skipped_normal] => 0
[rows_skipped_ps] => 0
[copy_on_write_saved] => 0
[copy_on_write_performed] => 0
[command_buffer_too_small] => 0
[connect_success] => 1
[connect_failure] => 0
[connection_reused] => 0
[reconnect] => 0
[pconnect_success] => 0
[active_connections] => 1
[active_persistent_connections] => 0
[explicit_close] => 0
[implicit_close] => 0
[disconnect_close] => 0
[in_middle_of_command_close] => 0
[explicit_free_result] => 0
[implicit_free_result] => 0
[explicit_stmt_close] => 0
[implicit_stmt_close] => 0
[mem_emalloc_count] => 0
[mem_emalloc_ammount] => 0
[mem_ecalloc_count] => 0
[mem_ecalloc_ammount] => 0
[mem_erealloc_count] => 0
[mem_erealloc_ammount] => 0
[mem_efree_count] => 0
[mem_malloc_count] => 0
[mem_malloc_ammount] => 0
[mem_calloc_count] => 0
[mem_calloc_ammount] => 0
[mem_realloc_count] => 0
[mem_realloc_ammount] => 0
[mem_free_count] => 0
[proto_text_fetched_null] => 0
[proto_text_fetched_bit] => 0
[proto_text_fetched_tinyint] => 0
[proto_text_fetched_short] => 0
[proto_text_fetched_int24] => 0
[proto_text_fetched_int] => 0
[proto_text_fetched_bigint] => 0
[proto_text_fetched_decimal] => 0
[proto_text_fetched_float] => 0
[proto_text_fetched_double] => 0
[proto_text_fetched_date] => 0
[proto_text_fetched_year] => 0
[proto_text_fetched_time] => 0
[proto_text_fetched_datetime] => 0
[proto_text_fetched_timestamp] => 0
[proto_text_fetched_string] => 0
[proto_text_fetched_blob] => 0
[proto_text_fetched_enum] => 0
[proto_text_fetched_set] => 0
[proto_text_fetched_geometry] => 0
[proto_text_fetched_other] => 0
[proto_binary_fetched_null] => 0
[proto_binary_fetched_bit] => 0
[proto_binary_fetched_tinyint] => 0
[proto_binary_fetched_short] => 0
[proto_binary_fetched_int24] => 0
[proto_binary_fetched_int] => 0
[proto_binary_fetched_bigint] => 0
[proto_binary_fetched_decimal] => 0
[proto_binary_fetched_float] => 0
[proto_binary_fetched_double] => 0
[proto_binary_fetched_date] => 0
[proto_binary_fetched_year] => 0
[proto_binary_fetched_time] => 0
[proto_binary_fetched_datetime] => 0
[proto_binary_fetched_timestamp] => 0
[proto_binary_fetched_string] => 0
[proto_binary_fetched_blob] => 0
[proto_binary_fetched_enum] => 0
[proto_binary_fetched_set] => 0
[proto_binary_fetched_geometry] => 0
[proto_binary_fetched_other] => 0
)
Opis
This function is an alias of mysqli_stmt_result_metadata().
Notatki
Informacja:
mysqli_get_metadata() is deprecated and will be removed.
mysqli_master_query
(PHP 5)
mysqli_master_query — Enforce execution of a query on the master in a master/slave setup
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Ta funkcja jest PRZESTARZAŁA i zostanie USUNIĘTA od PHP 5.3.0.
Opis
This function is an alias of mysqli_stmt_param_count().
Notatki
Informacja:
mysqli_param_count() is deprecated and will be removed.
mysqli_report
(PHP 5)
mysqli_report — Enables or disables internal report functions
Opis
$flags
)mysqli_report() is a powerful function to improve your queries and code during development and testing phase. Depending on the flags it reports errors from mysqli function calls or queries which don't use an index (or use a bad index).
Parametry
-
flags -
Supported flags Name Description MYSQLI_REPORT_OFFTurns reporting off MYSQLI_REPORT_ERRORReport errors from mysqli function calls MYSQLI_REPORT_STRICTThrow mysqli_sql_exception for errors instead of warnings MYSQLI_REPORT_INDEXReport if no index or bad index was used in a query MYSQLI_REPORT_ALLSet all options (report all)
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.2.15 & 5.3.4 | Changing the reporting mode is now be per-request, rather than per-process. |
Przykłady
Przykład #1 Styl obiektowy
<?php
/* activate reporting */
mysqli_report(MYSQLI_REPORT_ALL);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
/* this query should report an error */
$result = $mysqli->query("SELECT Name FROM Nonexistingtable WHERE population > 50000");
/* this query should report a bad index */
$result = $mysqli->query("SELECT Name FROM City WHERE population > 50000");
$result->close();
$mysqli->close();
?>
Zobacz też:
- mysqli_driver::$report_mode
- mysqli_debug() - Performs debugging operations
- mysqli_dump_debug_info() - Dump debugging information into the log
mysqli_rpl_parse_enabled
(PHP 5)
mysqli_rpl_parse_enabled — Check if RPL parse is enabled
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Ta funkcja jest PRZESTARZAŁA i zostanie USUNIĘTA od PHP 5.3.0.
mysqli_rpl_probe
(PHP 5)
mysqli_rpl_probe — RPL probe
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Ta funkcja jest PRZESTARZAŁA i zostanie USUNIĘTA od PHP 5.3.0.
Opis
This function is an alias of mysqli_stmt_send_long_data().
Notatki
Informacja:
mysqli_send_long_data() is deprecated and will be removed.
Opis
This function is an alias of mysqli_options().
mysqli_slave_query
(PHP 5)
mysqli_slave_query — Force execution of a query on a slave in a master/slave setup
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Ta funkcja jest PRZESTARZAŁA i zostanie USUNIĘTA od PHP 5.3.0.
Spis treści
- mysqli_bind_param — Alias for mysqli_stmt_bind_param
- mysqli_bind_result — Alias for mysqli_stmt_bind_result
- mysqli_client_encoding — Alias of mysqli_character_set_name
- mysqli_connect — Alias dla mysqli::__construct
- mysqli_disable_rpl_parse — Disable RPL parse
- mysqli_enable_reads_from_master — Enable reads from master
- mysqli_enable_rpl_parse — Enable RPL parse
- mysqli_escape_string — Alias dla mysqli_real_escape_string
- mysqli_execute — Alias for mysqli_stmt_execute
- mysqli_fetch — Alias for mysqli_stmt_fetch
- mysqli_get_cache_stats — Returns client Zval cache statistics
- mysqli_get_metadata — Alias for mysqli_stmt_result_metadata
- mysqli_master_query — Enforce execution of a query on the master in a master/slave setup
- mysqli_param_count — Alias for mysqli_stmt_param_count
- mysqli_report — Enables or disables internal report functions
- mysqli_rpl_parse_enabled — Check if RPL parse is enabled
- mysqli_rpl_probe — RPL probe
- mysqli_send_long_data — Alias for mysqli_stmt_send_long_data
- mysqli_set_opt — Alias of mysqli_options
- mysqli_slave_query — Force execution of a query on a slave in a master/slave setup
- Wstęp
- Overview
- Quick start guide
- Instalacja/Konfiguracja
- The mysqli Extension and Persistent Connections
- Stałe predefiniowane
- Notes
- The MySQLi Extension Function Summary
- mysqli — The mysqli class
- mysqli::$affected_rows — Gets the number of affected rows in a previous MySQL operation
- mysqli::autocommit — Turns on or off auto-commiting database modifications
- mysqli::change_user — Changes the user of the specified database connection
- mysqli::character_set_name — Returns the default character set for the database connection
- mysqli::$client_info — Returns the MySQL client version as a string
- mysqli::$client_version — Get MySQL client info
- mysqli::close — Closes a previously opened database connection
- mysqli::commit — Commits the current transaction
- mysqli::$connect_errno — Returns the error code from last connect call
- mysqli::$connect_error — Returns a string description of the last connect error
- mysqli::__construct — Open a new connection to the MySQL server
- mysqli::debug — Performs debugging operations
- mysqli::disable_reads_from_master — Disable reads from master
- mysqli::dump_debug_info — Dump debugging information into the log
- mysqli::$errno — Returns the error code for the most recent function call
- mysqli::$error_list — Returns a list of errors from the last command executed
- mysqli::$error — Returns a string description of the last error
- mysqli::$field_count — Returns the number of columns for the most recent query
- mysqli::get_charset — Returns a character set object
- mysqli::get_client_info — Returns the MySQL client version as a string
- mysqli_get_client_stats — Returns client per-process statistics
- mysqli::$client_version — Get MySQL client info
- mysqli::get_connection_stats — Returns statistics about the client connection
- mysqli::$host_info — Returns a string representing the type of connection used
- mysqli::$protocol_version — Returns the version of the MySQL protocol used
- mysqli::$server_info — Returns the version of the MySQL server
- mysqli::$server_version — Returns the version of the MySQL server as an integer
- mysqli::get_warnings — Get result of SHOW WARNINGS
- mysqli::$info — Retrieves information about the most recently executed query
- mysqli::init — Initializes MySQLi and returns a resource for use with mysqli_real_connect()
- mysqli::$insert_id — Returns the auto generated id used in the last query
- mysqli::kill — Asks the server to kill a MySQL thread
- mysqli::more_results — Check if there are any more query results from a multi query
- mysqli::multi_query — Performs a query on the database
- mysqli::next_result — Prepare next result from multi_query
- mysqli::options — Set options
- mysqli::ping — Pings a server connection, or tries to reconnect if the connection has gone down
- mysqli::poll — Poll connections
- mysqli::prepare — Prepare an SQL statement for execution
- mysqli::query — Performs a query on the database
- mysqli::real_connect — Opens a connection to a mysql server
- mysqli::real_escape_string — Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection
- mysqli::real_query — Execute an SQL query
- mysqli::reap_async_query — Get result from async query
- mysqli::refresh — Refreshes
- mysqli::rollback — Rolls back current transaction
- mysqli::rpl_query_type — Returns RPL query type
- mysqli::select_db — Selects the default database for database queries
- mysqli::send_query — Send the query and return
- mysqli::set_charset — Sets the default client character set
- mysqli::set_local_infile_default — Unsets user defined handler for load local infile command
- mysqli::set_local_infile_handler — Set callback function for LOAD DATA LOCAL INFILE command
- mysqli::$sqlstate — Returns the SQLSTATE error from previous MySQL operation
- mysqli::ssl_set — Used for establishing secure connections using SSL
- mysqli::stat — Gets the current system status
- mysqli::stmt_init — Initializes a statement and returns an object for use with mysqli_stmt_prepare
- mysqli::store_result — Transfers a result set from the last query
- mysqli::$thread_id — Returns the thread ID for the current connection
- mysqli::thread_safe — Returns whether thread safety is given or not
- mysqli::use_result — Initiate a result set retrieval
- mysqli::$warning_count — Returns the number of warnings from the last query for the given link
- mysqli_stmt — The mysqli_stmt class
- mysqli_stmt::$affected_rows — Returns the total number of rows changed, deleted, or inserted by the last executed statement
- mysqli_stmt::attr_get — Used to get the current value of a statement attribute
- mysqli_stmt::attr_set — Used to modify the behavior of a prepared statement
- mysqli_stmt::bind_param — Binds variables to a prepared statement as parameters
- mysqli_stmt::bind_result — Binds variables to a prepared statement for result storage
- mysqli_stmt::close — Closes a prepared statement
- mysqli_stmt::data_seek — Seeks to an arbitrary row in statement result set
- mysqli_stmt::$errno — Returns the error code for the most recent statement call
- mysqli_stmt::$error_list — Returns a list of errors from the last statement executed
- mysqli_stmt::$error — Returns a string description for last statement error
- mysqli_stmt::execute — Executes a prepared Query
- mysqli_stmt::fetch — Fetch results from a prepared statement into the bound variables
- mysqli_stmt::$field_count — Returns the number of field in the given statement
- mysqli_stmt::free_result — Frees stored result memory for the given statement handle
- mysqli_stmt::get_result — Gets a result set from a prepared statement
- mysqli_stmt::get_warnings — Get result of SHOW WARNINGS
- mysqli_stmt::$insert_id — Get the ID generated from the previous INSERT operation
- mysqli_stmt::more_results — Check if there are more query results from a multiple query
- mysqli_stmt::next_result — Reads the next result from a multiple query
- mysqli_stmt::$num_rows — Return the number of rows in statements result set
- mysqli_stmt::$param_count — Returns the number of parameter for the given statement
- mysqli_stmt::prepare — Prepare an SQL statement for execution
- mysqli_stmt::reset — Resets a prepared statement
- mysqli_stmt::result_metadata — Returns result set metadata from a prepared statement
- mysqli_stmt::send_long_data — Send data in blocks
- mysqli_stmt::$sqlstate — Returns SQLSTATE error from previous statement operation
- mysqli_stmt::store_result — Transfers a result set from a prepared statement
- mysqli_result — The mysqli_result class
- mysqli_result::$current_field — Get current field offset of a result pointer
- mysqli_result::data_seek — Adjusts the result pointer to an arbitary row in the result
- mysqli_result::fetch_all — Fetches all result rows as an associative array, a numeric array, or both
- mysqli_result::fetch_array — Fetch a result row as an associative, a numeric array, or both
- mysqli_result::fetch_assoc — Fetch a result row as an associative array
- mysqli_result::fetch_field_direct — Fetch meta-data for a single field
- mysqli_result::fetch_field — Returns the next field in the result set
- mysqli_result::fetch_fields — Returns an array of objects representing the fields in a result set
- mysqli_result::fetch_object — Returns the current row of a result set as an object
- mysqli_result::fetch_row — Get a result row as an enumerated array
- mysqli_result::$field_count — Get the number of fields in a result
- mysqli_result::field_seek — Set result pointer to a specified field offset
- mysqli_result::free — Frees the memory associated with a result
- mysqli_result::$lengths — Returns the lengths of the columns of the current row in the result set
- mysqli_result::$num_rows — Gets the number of rows in a result
- mysqli_driver — The mysqli_driver class
- mysqli_driver::embedded_server_end — Stop embedded server
- mysqli_driver::embedded_server_start — Initialize and start embedded server
- mysqli_warning — The mysqli_warning class
- mysqli_warning::__construct — The __construct purpose
- mysqli_warning::next — The next purpose
- mysqli_sql_exception — The mysqli_sql_exception class
- Aliases and deprecated Mysqli Funkcje
- mysqli_bind_param — Alias for mysqli_stmt_bind_param
- mysqli_bind_result — Alias for mysqli_stmt_bind_result
- mysqli_client_encoding — Alias of mysqli_character_set_name
- mysqli_connect — Alias dla mysqli::__construct
- mysqli_disable_rpl_parse — Disable RPL parse
- mysqli_enable_reads_from_master — Enable reads from master
- mysqli_enable_rpl_parse — Enable RPL parse
- mysqli_escape_string — Alias dla mysqli_real_escape_string
- mysqli_execute — Alias for mysqli_stmt_execute
- mysqli_fetch — Alias for mysqli_stmt_fetch
- mysqli_get_cache_stats — Returns client Zval cache statistics
- mysqli_get_metadata — Alias for mysqli_stmt_result_metadata
- mysqli_master_query — Enforce execution of a query on the master in a master/slave setup
- mysqli_param_count — Alias for mysqli_stmt_param_count
- mysqli_report — Enables or disables internal report functions
- mysqli_rpl_parse_enabled — Check if RPL parse is enabled
- mysqli_rpl_probe — RPL probe
- mysqli_send_long_data — Alias for mysqli_stmt_send_long_data
- mysqli_set_opt — Alias of mysqli_options
- mysqli_slave_query — Force execution of a query on a slave in a master/slave setup
MySQL Native Driver
Wstęp
MySQL Native Driver is a replacement for the MySQL Client Library (libmysql). MySQL Native Driver is part of the official PHP sources as of PHP 5.3.0.
The MySQL database extensions MySQL extension, mysqli and PDO MYSQL all communicate with the MySQL server. In the past, this was done by the extension using the services provided by the MySQL Client Library. The extensions were compiled against the MySQL Client Library in order to use its client-server protocol.
With MySQL Native Driver there is now an alternative, as the MySQL database extensions can be compiled to use MySQL Native Driver instead of the MySQL Client Library.
MySQL Native Driver is written in C as a PHP extension.
Overview
What it is not
Although MySQL Native Driver is written as a PHP extension, it is important to note that it does not provide a new API to the PHP programmer. The programmer APIs for MySQL database connectivity are provided by the MySQL extension, mysqli and PDO MYSQL. These extensions can now use the services of MySQL Native Driver to communicate with the MySQL Server. Therefore, you should not think of MySQL Native Driver as an API.
Why use it?
Using the MySQL Native Driver offers a number of advantages over using the MySQL Client Library.
The older MySQL Client Library was written by MySQL AB (now Oracle Corporation) and so was released under the MySQL license. This ultimately led to MySQL support being disabled by default in PHP. However, the MySQL Native Driver has been developed as part of the PHP project, and is therefore released under the PHP license. This removes licensing issues that have been problematic in the past.
Also, in the past, you needed to build the MySQL database extensions against a copy of the MySQL Client Library. This typically meant you needed to have MySQL installed on a machine where you were building the PHP source code. Also, when your PHP application was running, the MySQL database extensions would call down to the MySQL Client library file at run time, so the file needed to be installed on your system. With MySQL Native Driver that is no longer the case as it is included as part of the standard distribution. So you do not need MySQL installed in order to build PHP or run PHP database applications.
Because MySQL Native Driver is written as a PHP extension, it is tightly coupled to the workings of PHP. This leads to gains in efficiency, especially when it comes to memory usage, as the driver uses the PHP memory management system. It also supports the PHP memory limit. Using MySQL Native Driver leads to comparable or better performance than using MySQL Client Library, it always ensures the most efficient use of memory. One example of the memory efficiency is the fact that when using the MySQL Client Library, each row is stored in memory twice, whereas with the MySQL Native Driver each row is only stored once in memory.
Special features
MySQL Native Driver also provides some special features not available when the MySQL database extensions use MySQL Client Library. These special features are listed below:
-
Improved persistent connections
-
The special function mysqli_fetch_all()
-
Performance statistics calls: mysqli_get_cache_stats(), mysqli_get_client_stats(), mysqli_get_connection_stats()
The performance statistics facility can prove to be very useful in identifying performance bottlenecks.
MySQL Native Driver also allows for persistent connections when used with the mysqli extension.
SSL Support
MySQL Native Driver has supported SSL since PHP version 5.3.3
Compressed Protocol Support
As of PHP 5.3.2 MySQL Native Driver supports the compressed client server protocol. MySQL Native Driver did not support this in 5.3.0 and 5.3.1. Extensions such as ext/mysql, ext/mysqli, that are configured to use MySQL Native Driver, can also take advantage of this feature. Note that PDO_MYSQL does NOT support compression when used together with mysqlnd.
Named Pipes Support
Named pipes support for Windows was added in PHP version 5.4.0.
Installation
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.0 | The MySQL Native Driver was added, with support for all MySQL extensions (i.e., mysql, mysqli and PDO_MYSQL). Passing in mysqlnd to the appropriate configure switch enables this support. |
| 5.4.0 | The MySQL Native Driver is now the default for all MySQL extensions (i.e., mysql, mysqli and PDO_MYSQL). Passing in mysqlnd to configure is now optional. |
Installation on Unix
The MySQL database extensions must be configured to use the MySQL Client Library. In order to use the MySQL Native Driver, PHP needs to be built specifying that the MySQL database extensions are compiled with MySQL Native Driver support. This is done through configuration options prior to building the PHP source code.
For example, to build the MySQL extension, mysqli and PDO MYSQL using the MySQL Native Driver, the following command would be given:
./configure --with-mysql=mysqlnd \ --with-mysqli=mysqlnd \ --with-pdo-mysql=mysqlnd \ [other options]
Installation on Windows
In the official PHP Windows distributions from 5.3 onwards, MySQL Native Driver is enabled by default, so no additional configuration is required to use it. All MySQL database extensions will use MySQL Native Driver in this case.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| mysqlnd.collect_statistics | "1" | PHP_INI_SYSTEM | Available since PHP 5.3.0. |
| mysqlnd.collect_memory_statistics | "0" | PHP_INI_SYSTEM | Available since PHP 5.3.0. |
| mysqlnd.debug | "0" | PHP_INI_SYSTEM | Available since PHP 5.3.0. |
| mysqlnd.log_mask | 0 | PHP_INI_ALL | Available since PHP 5.3.0 |
| mysqlnd.mempool_default_size | 16000 | PHP_INI_ALL | Available since PHP 5.3.3 |
| mysqlnd.net_read_timeout | "31536000" | PHP_INI_SYSTEM | Available since PHP 5.3.0. |
| mysqlnd.net_cmd_buffer_size | 5.3.0 - "2048", 5.3.1 - "4096" | PHP_INI_SYSTEM | Available since PHP 5.3.0. |
| mysqlnd.net_read_buffer_size | "32768" | PHP_INI_SYSTEM | Available since PHP 5.3.0. |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
mysqlnd.collect_statisticsboolean -
Enables the collection of various client statistics which can be accessed through mysqli_get_client_stats(), mysqli_get_connection_stats(), mysqli_get_cache_stats() and are shown in mysqlnd section of the output of the phpinfo() function as well.
This configuration setting enables all MySQL Native Driver statistics except those relating to memory management.
-
mysqlnd.collect_memory_statisticsboolean -
Enable the collection of various memory statistics which can be accessed through mysqli_get_client_stats(), mysqli_get_connection_stats(), mysqli_get_cache_stats() and are shown in mysqlnd section of the output of the phpinfo() function as well.
This configuration setting enables the memory management statistics within the overall set of MySQL Native Driver statistics.
-
mysqlnd.debugstring -
Records communication from all extensions using mysqlnd to the specified log file.
The format of the directive is mysqlnd.debug = "option1[,parameter_option1][:option2[,parameter_option2]]".
The options for the format string are as follows:
-
A[,file] - Appends trace output to specified file. Also ensures that data is written after each write. This is done by closing and reopening the trace file (this is slow). It helps ensure a complete log file should the application crash.
-
a[,file] - Appends trace output to the specified file.
-
d - Enables output from DBUG_<N> macros for the current state. May be followed by a list of keywords which selects output only for the DBUG macros with that keyword. An empty list of keywords implies output for all macros.
-
f[,functions] - Limits debugger actions to the specified list of functions. An empty list of functions implies that all functions are selected.
-
F - Marks each debugger output line with the name of the source file containing the macro causing the output.
-
i - Marks each debugger output line with the PID of the current process.
-
L - Marks each debugger output line with the name of the source file line number of the macro causing the output.
-
n - Marks each debugger output line with the current function nesting depth
-
o[,file] - Similar to a[,file] but overwrites old file, and does not append.
-
O[,file] - Similar to A[,file] but overwrites old file, and does not append.
-
t[,N] - Enables function control flow tracing. The maximum nesting depth is specified by N, and defaults to 200.
-
x - This option activates profiling.
Example:
d:t:x:O,/tmp/mysqlnd.trace
Informacja:
This feature is only available with a debug build of PHP. Works on Microsoft Windows if using a debug build of PHP and PHP was built using Microsoft Visual C version 9 and above.
-
-
mysqlnd.log_maskinteger -
Defines which queries will be logged. The default 0, which disables logging. Define using an integer, and not with PHP constants. For example, a value of 48 (16 + 32) will log slow queries which either use 'no good index' (SERVER_QUERY_NO_GOOD_INDEX_USED = 16) or no index at all (SERVER_QUERY_NO_INDEX_USED = 32). A value of 2043 (1 + 2 + 8 + ... + 1024) will log all slow query types.
The types are as follows: SERVER_STATUS_IN_TRANS=1, SERVER_STATUS_AUTOCOMMIT=2, SERVER_MORE_RESULTS_EXISTS=8, SERVER_QUERY_NO_GOOD_INDEX_USED=16, SERVER_QUERY_NO_INDEX_USED=32, SERVER_STATUS_CURSOR_EXISTS=64, SERVER_STATUS_LAST_ROW_SENT=128, SERVER_STATUS_DB_DROPPED=256, SERVER_STATUS_NO_BACKSLASH_ESCAPES=512, and SERVER_QUERY_WAS_SLOW=1024.
-
mysqlnd.mempool_default_sizeinteger -
Default size of the mysqlnd memory pool, which is used by result sets.
-
mysqlnd.net_read_timeoutinteger -
mysqlnd and the MySQL Client Library, libmysql use different networking APIs. mysqlnd uses PHP streams, whereas libmysql uses its own wrapper around the operating level network calls. PHP, by default, sets a read timeout of 60s for streams. This is set via php.ini, default_socket_timeout. This default applies to all streams that set no other timeout value. mysqlnd does not set any other value and therefore connections of long running queries can be disconnected after default_socket_timeout seconds resulting in an error message "2006 - MySQL Server has gone away". The MySQL Client Library sets a default timeout of 365 * 24 * 3600 seconds (1 year) and waits for other timeouts to occur, such as TCP/IP timeouts. mysqlnd now uses the same very long timeout. The value is configurable through a new php.ini setting: mysqlnd.net_read_timeout. mysqlnd.net_read_timeout gets used by any extension (ext/mysql, ext/mysqli, PDO_MySQL) that uses mysqlnd. mysqlnd tells PHP Streams to use mysqlnd.net_read_timeout. Please note that there may be subtle differences between MYSQL_OPT_READ_TIMEOUT from the MySQL Client Library and PHP Streams, for example MYSQL_OPT_READ_TIMEOUT is documented to work only for TCP/IP connections and, prior to MySQL 5.1.2, only for Windows. PHP streams may not have this limitation. Please check the streams documentation, if in doubt.
-
mysqlnd.net_cmd_buffer_sizelong -
mysqlnd allocates an internal command/network buffer of mysqlnd.net_cmd_buffer_size (in php.ini) bytes for every connection. If a MySQL Client Server protocol command, for example, COM_QUERY ("normal" query), does not fit into the buffer, mysqlnd will grow the buffer to the size required for sending the command. Whenever the buffer gets extended for one connection, command_buffer_too_small will be incremented by one.
If mysqlnd has to grow the buffer beyond its initial size of mysqlnd.net_cmd_buffer_size bytes for almost every connection, you should consider increasing the default size to avoid re-allocations.
The default buffer size is 2048 bytes in PHP 5.3.0. In later versions the default is 4096 bytes. The default can changed either through the php.ini setting mysqlnd.net_cmd_buffer_size or using mysqli_options(MYSQLI_OPT_NET_CMD_BUFFER_SIZE, int size).
It is recommended that the buffer size be set to no less than 4096 bytes because mysqlnd also uses it when reading certain communication packet from MySQL. In PHP 5.3.0, mysqlnd will not grow the buffer if MySQL sends a packet that is larger than the current size of the buffer. As a consequence, mysqlnd is unable to decode the packet and the client application will get an error. There are only two situations when the packet can be larger than the 2048 bytes default of mysqlnd.net_cmd_buffer_size in PHP 5.3.0: the packet transports a very long error message, or the packet holds column meta data from COM_LIST_FIELD (mysql_list_fields() and the meta data come from a string column with a very long default value (>1900 bytes).
As of PHP 5.3.2 mysqlnd does not allow setting buffers smaller than 4096 bytes.
The value can also be set using mysqli_options(link, MYSQLI_OPT_NET_CMD_BUFFER_SIZE, size).
-
mysqlnd.net_read_buffer_sizelong -
Maximum read chunk size in bytes when reading the body of a MySQL command packet. The MySQL client server protocol encapsulates all its commands in packets. The packets consist of a small header and a body with the actual payload. The size of the body is encoded in the header. mysqlnd reads the body in chunks of MIN(header.size, mysqlnd.net_read_buffer_size) bytes. If a packet body is larger than mysqlnd.net_read_buffer_size bytes, mysqlnd has to call read() multiple times.
The value can also be set using mysqli_options(link, MYSQLI_OPT_NET_READ_BUFFER_SIZE, size).
Persistent Connections
Using Persistent Connections
If mysqli is used with mysqlnd, when a persistent connection is created it generates a COM_CHANGE_USER (mysql_change_user()) call on the server. This ensures that re-authentication of the connection takes place.
As there is some overhead associated with the COM_CHANGE_USER call, it is possible to switch this off at compile time. Reusing a persistent connection will then generate a COM_PING (mysql_ping) call to simply test the connection is reusable.
Generation of COM_CHANGE_USER can be switched off with the compile flag MYSQLI_NO_CHANGE_USER_ON_PCONNECT. For example:
shell# CFLAGS="-DMYSQLI_NO_CHANGE_USER_ON_PCONNECT" ./configure --with-mysql=/usr/local/mysql/ --with-mysqli=/usr/local/mysql/bin/mysql_config --with-pdo-mysql=/usr/local/mysql/bin/mysql_config --enable-debug && make clean && make -j6
Or alternatively:
shell# export CFLAGS="-DMYSQLI_NO_CHANGE_USER_ON_PCONNECT" shell# configure --whatever-option shell# make clean shell# make
Note that only mysqli on mysqlnd uses COM_CHANGE_USER. Other extension-driver combinations use COM_PING on initial use of a persistent connection.
Statistics
Using Statistical Data
MySQL Native Driver contains support for gathering statistics on the communication between the client and the server. The statistics gathered are of three main types:
-
Client statistics
-
Connection statistics
-
Zval cache statistics
If you are using the mysqli extension, these statistics can be obtained through three API calls:
Informacja:
Statistics are aggregated among all extensions that use MySQL Native Driver. For example, when compiling both ext/mysql and ext/mysqli against MySQL Native Driver, both function calls of ext/mysql and ext/mysqli will change the statistics. There is no way to find out how much a certain API call of any extension that has been compiled against MySQL Native Driver has impacted a certain statistic. You can configure the PDO MySQL Driver, ext/mysql and ext/mysqli to optionally use the MySQL Native Driver. When doing so, all three extensions will change the statistics.
Accessing Client Statistics
To access client statistics, you need to call mysqli_get_client_stats(). The function call does not require any parameters.
The function returns an associative array that contains the name of the statistic as the key and the statistical data as the value.
Client statistics can also be accessed by calling the phpinfo() function.
Accessing Connection Statistics
To access connection statistics call mysqli_get_connection_stats(). This takes the database connection handle as the parameter.
The function returns an associative array that contains the name of the statistic as the key and the statistical data as the value.
Accessing Zval Cache Statistics
The MySQL Native Driver also collects statistics from its internal Zval cache. These statistics can be accessed by calling mysqli_get_cache_stats().
The Zval cache statistics obtained may lead to a tweaking of php.ini settings related to the Zval cache, resulting in better performance.
Buffered and Unbuffered Result Sets
Result sets can be buffered or unbuffered. Using default settings, ext/mysql and ext/mysqli work with buffered result sets for normal (non prepared statement) queries. Buffered result sets are cached on the client. After the query execution all results are fetched from the MySQL Server and stored in a cache on the client. The big advantage of buffered result sets is that they allow the server to free all resources allocated to a result set, once the results have been fetched by the client.
Unbuffered result sets on the other hand are kept much longer on the server. If you want to reduce memory consumption on the client, but increase load on the server, use unbuffered results. If you experience a high server load and the figures for unbuffered result sets are high, you should consider moving the load to the clients. Clients typically scale better than servers. "Load" does not only refer to memory buffers - the server also needs to keep other resources open, for example file handles and threads, before a result set can be freed.
Prepared Statements use unbuffered result sets by default. However, you can use mysqli_stmt_store_result() to enable buffered result sets.
Statistics returned by MySQL Native Driver
The following tables show a list of statistics returned by the mysqli_get_client_stats(), mysqli_get_connection_stats() and mysqli_get_cache_stats() functions.
Network
| Statistic | Scope | Description | Notes |
|---|---|---|---|
| bytes_sent | Connection | Number of bytes sent from PHP to the MySQL server | Can be used to check the efficiency of the compression protocol |
| bytes_received | Connection | Number of bytes received from MySQL server | Can be used to check the efficiency of the compression protocol |
| packets_sent | Connection | Number of MySQL Client Server protocol packets sent | Used for debugging Client Server protocol implementation |
| packets_received | Connection | Number of MySQL Client Server protocol packets received | Used for debugging Client Server protocol implementation |
| protocol_overhead_in | Connection | MySQL Client Server protocol overhead in bytes for incoming traffic. Currently only the Packet Header (4 bytes) is considered as overhead. protocol_overhead_in = packets_received * 4 | Used for debugging Client Server protocol implementation |
| protocol_overhead_out | Connection | MySQL Client Server protocol overhead in bytes for outgoing traffic. Currently only the Packet Header (4 bytes) is considered as overhead. protocol_overhead_out = packets_sent * 4 | Used for debugging Client Server protocol implementation |
| bytes_received_ok_packet | Connection | Total size of bytes of MySQL Client Server protocol OK packets received. OK packets can contain a status message. The length of the status message can vary and thus the size of an OK packet is not fixed. | Used for debugging CS protocol implementation. Note that the total size in bytes includes the size of the header packet (4 bytes, see protocol overhead). |
| packets_received_ok | Connection | Number of MySQL Client Server protocol OK packets received. | Used for debugging CS protocol implementation. Note that the total size in bytes includes the size of the header packet (4 bytes, see protocol overhead). |
| bytes_received_eof_packet | Connection | Total size in bytes of MySQL Client Server protocol EOF packets received. EOF can vary in size depending on the server version. Also, EOF can transport an error message. | Used for debugging CS protocol implementation. Note that the total size in bytes includes the size of the header packet (4 bytes, see protocol overhead). |
| packets_received_eof | Connection | Number of MySQL Client Server protocol EOF packets. Like with other packet statistics the number of packets will be increased even if PHP does not receive the expected packet but, for example, an error message. | Used for debugging CS protocol implementation. Note that the total size in bytes includes the size of the header packet (4 bytes, see protocol overhead). |
| bytes_received_rset_header_packet | Connection | Total size in bytes of MySQL Client Server protocol result set header packets. The size of the packets varies depending on the payload (LOAD LOCAL INFILE, INSERT, UPDATE, SELECT, error message). | Used for debugging CS protocol implementation. Note that the total size in bytes includes the size of the header packet (4 bytes, see protocol overhead). |
| packets_received_rset_header | Connection | Number of MySQL Client Server protocol result set header packets. | Used for debugging CS protocol implementation. Note that the total size in bytes includes the size of the header packet (4 bytes, see protocol overhead). |
| bytes_received_rset_field_meta_packet | Connection | Total size in bytes of MySQL Client Server protocol result set meta data (field information) packets. Of course the size varies with the fields in the result set. The packet may also transport an error or an EOF packet in case of COM_LIST_FIELDS. | Only useful for debugging CS protocol implementation. Note that the total size in bytes includes the size of the header packet (4 bytes, see protocol overhead). |
| packets_received_rset_field_meta | Connection | Number of MySQL Client Server protocol result set meta data (field information) packets. | Only useful for debugging CS protocol implementation. Note that the total size in bytes includes the size of the header packet (4 bytes, see protocol overhead). |
| bytes_received_rset_row_packet | Connection | Total size in bytes of MySQL Client Server protocol result set row data packets. The packet may also transport an error or an EOF packet. You can reverse engineer the number of error and EOF packets by substracting rows_fetched_from_server_normal and rows_fetched_from_server_ps from bytes_received_rset_row_packet. | Only useful for debugging CS protocol implementation. Note that the total size in bytes includes the size of the header packet (4 bytes, see protocol overhead). |
| packets_received_rset_row | Connection | Number of MySQL Client Server protocol result set row data packets and their total size in bytes. | Only useful for debugging CS protocol implementation. Note that the total size in bytes includes the size of the header packet (4 bytes, see protocol overhead). |
| bytes_received_prepare_response_packet | Connection | Total size in bytes of MySQL Client Server protocol OK for Prepared Statement Initialization packets (prepared statement init packets). The packet may also transport an error. The packet size depends on the MySQL version: 9 bytes with MySQL 4.1 and 12 bytes from MySQL 5.0 on. There is no safe way to know how many errors happened. You may be able to guess that an error has occurred if, for example, you always connect to MySQL 5.0 or newer and, bytes_received_prepare_response_packet != packets_received_prepare_response * 12. See also ps_prepared_never_executed, ps_prepared_once_executed. | Only useful for debugging CS protocol implementation. Note that the total size in bytes includes the size of the header packet (4 bytes, see protocol overhead). |
| packets_received_prepare_response | Connection | Number of MySQL Client Server protocol OK for Prepared Statement Initialization packets (prepared statement init packets). | Only useful for debugging CS protocol implementation. Note that the total size in bytes includes the size of the header packet (4 bytes, see protocol overhead). |
| bytes_received_change_user_packet | Connection | Total size in bytes of MySQL Client Server protocol COM_CHANGE_USER packets. The packet may also transport an error or EOF. | Only useful for debugging CS protocol implementation. Note that the total size in bytes includes the size of the header packet (4 bytes, see protocol overhead). |
| packets_received_change_user | Connection | Number of MySQL Client Server protocol COM_CHANGE_USER packets | Only useful for debugging CS protocol implementation. Note that the total size in bytes includes the size of the header packet (4 bytes, see protocol overhead). |
| packets_sent_command | Connection | Number of MySQL Client Server protocol commands sent from PHP to MySQL. There is no way to know which specific commands and how many of them have been sent. At its best you can use it to check if PHP has sent any commands to MySQL to know if you can consider to disable MySQL support in your PHP binary. There is also no way to reverse engineer the number of errors that may have occurred while sending data to MySQL. The only error recoded is command_buffer_too_small (see below). | Only useful for debugging CS protocol implementation. |
| bytes_received_real_data_normal | Connection | Number of bytes of payload fetched by the PHP client from mysqlnd using the text protocol. | This is the size of the actual data contained in result sets that do not
originate from prepared statements and which have been fetched by
the PHP client. Note that although a full result set may have been
pulled from MySQL by mysqlnd, this statistic
only counts actual data pulled from mysqlnd by
the PHP client. An example of a code sequence that will increase
the value is as follows:
$mysqli = new mysqli();
$res = $mysqli->query("SELECT 'abc'");
$res->fetch_assoc();
$res->close();
Every fetch operation will increase the value. The statistic will not be increased if the result set is only buffered on the client, but not fetched, such as in the following example:
$mysqli = new mysqli();
$res = $mysqli->query("SELECT 'abc'");
$res->close();
This statistic is available as of PHP version 5.3.4. |
| bytes_received_real_data_ps | Connection | Number of bytes of the payload fetched by the PHP client from mysqlnd using the prepared statement protocol. | This is the size of the actual data contained in result sets that originate from prepared statements and which has been fetched by the PHP client. The value will not be increased if the result set is not subsequently read by the PHP client. Note that although a full result set may have been pulled from MySQL by mysqlnd, this statistic only counts actual data pulled from mysqlnd by the PHP client. See also bytes_received_real_data_normal. This statistic is available as of PHP version 5.3.4. |
Result Set
| Statistic | Scope | Description | Notes |
|---|---|---|---|
| result_set_queries | Connection | Number of queries that have generated a result set. Examples of queries that generate a result set: SELECT, SHOW. The statistic will not be incremented if there is an error reading the result set header packet from the line. | You may use it as an indirect measure for the number of queries PHP has sent to MySQL, for example, to identify a client that causes a high database load. |
| non_result_set_queries | Connection | Number of queries that did not generate a result set. Examples of queries that do not generate a result set: INSERT, UPDATE, LOAD DATA, SHOW. The statistic will not be incremented if there is an error reading the result set header packet from the line. | You may use it as an indirect measure for the number of queries PHP has sent to MySQL, for example, to identify a client that causes a high database load. |
| no_index_used | Connection | Number of queries that have generated a result set but did not use an index (see also mysqld start option –log-queries-not-using-indexes). If you want these queries to be reported you can use mysqli_report(MYSQLI_REPORT_INDEX) to make ext/mysqli throw an exception. If you prefer a warning instead of an exception use mysqli_report(MYSQLI_REPORT_INDEX ^ MYSQLI_REPORT_STRICT). | |
| bad_index_used | Connection | Number of queries that have generated a result set and did not use a good index (see also mysqld start option –log-slow-queries). | If you want these queries to be reported you can use mysqli_report(MYSQLI_REPORT_INDEX) to make ext/mysqli throw an exception. If you prefer a warning instead of an exception use mysqli_report(MYSQLI_REPORT_INDEX ^ MYSQLI_REPORT_STRICT) |
| slow_queries | Connection | SQL statements that took more than long_query_time seconds to execute and required at least min_examined_row_limit rows to be examined. | Not reported through mysqli_report() |
| buffered_sets | Connection | Number of buffered result sets returned by "normal" queries. "Normal" means "not prepared statement" in the following notes. | Examples of API calls that will buffer result sets on the client: mysql_query(), mysqli_query(), mysqli_store_result(), mysqli_stmt_get_result(). Buffering result sets on the client ensures that server resources are freed as soon as possible and it makes result set scrolling easier. The downside is the additional memory consumption on the client for buffering data. Note that mysqlnd (unlike the MySQL Client Library) respects the PHP memory limit because it uses PHP internal memory management functions to allocate memory. This is also the reason why memory_get_usage() reports a higer memory consumption when using mysqlnd instead of the MySQL Client Library. memory_get_usage() does not measure the memory consumption of the MySQL Client Library at all because the MySQL Client Library does not use PHP internal memory management functions monitored by the function! |
| unbuffered_sets | Connection | Number of unbuffered result sets returned by normal (non prepared statement) queries. | Examples of API calls that will not buffer result sets on the client: mysqli_use_result() |
| ps_buffered_sets | Connection | Number of buffered result sets returned by prepared statements. By default prepared statements are unbuffered. | Examples of API calls that will not buffer result sets on the client: mysqli_stmt_store_result |
| ps_unbuffered_sets | Connection | Number of unbuffered result sets returned by prepared statements. | By default prepared statements are unbuffered. |
| flushed_normal_sets | Connection | Number of result sets from normal (non prepared statement) queries with unread data which have been flushed silently for you. Flushing happens only with unbuffered result sets. | Unbuffered result sets must be fetched completely before a new query can
be run on the connection otherwise MySQL will throw an error. If
the application does not fetch all rows from an unbuffered result
set, mysqlnd does implicitly fetch the result set to clear the
line. See also rows_skipped_normal,
rows_skipped_ps. Some possible causes for an
implicit flush:
|
| flushed_ps_sets | Connection | Number of result sets from prepared statements with unread data which have been flushed silently for you. Flushing happens only with unbuffered result sets. | Unbuffered result sets must be fetched completely before a new query can
be run on the connection otherwise MySQL will throw an error. If
the application does not fetch all rows from an unbuffered result
set, mysqlnd does implicitly fetch the result set to clear the
line. See also rows_skipped_normal,
rows_skipped_ps. Some possible causes for an
implicit flush:
|
| ps_prepared_never_executed | Connection | Number of statements prepared but never executed. | Prepared statements occupy server resources. You should not prepare a statement if you do not plan to execute it. |
| ps_prepared_once_executed | Connection | Number of prepared statements executed only one. | One of the ideas behind prepared statements is that the same query gets executed over and over again (with different parameters) and some parsing and other preparation work can be saved, if statement execution is split up in separate prepare and execute stages. The idea is to prepare once and "cache" results, for example, the parse tree to be reused during multiple statement executions. If you execute a prepared statement only once the two stage processing can be inefficient compared to "normal" queries because all the caching means extra work and it takes (limited) server resources to hold the cached information. Consequently, prepared statements that are executed only once may cause performance hurts. |
| rows_fetched_from_server_normal, rows_fetched_from_server_ps | Connection | Total number of result set rows successfully fetched from MySQL regardless if the client application has consumed them or not. Some of the rows may not have been fetched by the client application but have been flushed implicitly. | See also packets_received_rset_row |
| rows_buffered_from_client_normal, rows_buffered_from_client_ps | Connection | Total number of succesfully buffered rows originating from a "normal" query or a prepared statement. This is the number of rows that have been fetched from MySQL and buffered on client. Note that there are two distinct statistics on rows that have been buffered (MySQL to mysqlnd internal buffer) and buffered rows that have been fetched by the client application (mysqlnd internal buffer to client application). If the number of buffered rows is higher than the number of fetched buffered rows it can mean that the client application runs queries that cause larger result sets than needed resulting in rows not read by the client. | Examples of queries that will buffer results: mysqli_query(), mysqli_store_result() |
| rows_fetched_from_client_normal_buffered, rows_fetched_from_client_ps_buffered | Connection | Total number of rows fetched by the client from a buffered result set created by a normal query or a prepared statement. | |
| rows_fetched_from_client_normal_unbuffered, rows_fetched_from_client_ps_unbuffered | Connection | Total number of rows fetched by the client from a unbuffered result set created by a "normal" query or a prepared statement. | |
| rows_fetched_from_client_ps_cursor | Connection | Total number of rows fetch by the client from a cursor created by a prepared statement. | |
| rows_skipped_normal, rows_skipped_ps | Connection | Reserved for future use (currently not supported) | |
| copy_on_write_saved, copy_on_write_performed | Process | With mysqlnd, variables returned by the extensions point into mysqlnd internal network result buffers. If you do not change the variables, fetched data will be kept only once in memory. If you change the variables, mysqlnd has to perform a copy-on-write to protect the internal network result buffers from being changed. With the MySQL Client Library you always hold fetched data twice in memory. Once in the internal MySQL Client Library buffers and once in the variables returned by the extensions. In theory mysqlnd can save up to 40% memory. However, note that the memory saving cannot be measured using memory_get_usage(). | |
| explicit_free_result, implicit_free_result | Connection, Process (only during prepared statement cleanup) | Total number of freed result sets. | The free is always considered explicit but for result sets created by an init command, for example, mysqli_options(MYSQLI_INIT_COMMAND , ...) |
| proto_text_fetched_null, proto_text_fetched_bit, proto_text_fetched_tinyint proto_text_fetched_short, proto_text_fetched_int24, proto_text_fetched_int proto_text_fetched_bigint, proto_text_fetched_decimal, proto_text_fetched_float proto_text_fetched_double, proto_text_fetched_date, proto_text_fetched_year proto_text_fetched_time, proto_text_fetched_datetime, proto_text_fetched_timestamp proto_text_fetched_string, proto_text_fetched_blob, proto_text_fetched_enum proto_text_fetched_set, proto_text_fetched_geometry, proto_text_fetched_other | Connection | Total number of columns of a certain type fetched from a normal query (MySQL text protocol). | Mapping from C API / MySQL meta data type to statistics name:
Note that the MYSQL_*-type constants may not be associated with the very same SQL column types in every version of MySQL. |
| proto_binary_fetched_null, proto_binary_fetched_bit, proto_binary_fetched_tinyint proto_binary_fetched_short, proto_binary_fetched_int24, proto_binary_fetched_int, proto_binary_fetched_bigint, proto_binary_fetched_decimal, proto_binary_fetched_float, proto_binary_fetched_double, proto_binary_fetched_date, proto_binary_fetched_year, proto_binary_fetched_time, proto_binary_fetched_datetime, proto_binary_fetched_timestamp, proto_binary_fetched_string, proto_binary_fetched_blob, proto_binary_fetched_enum, proto_binary_fetched_set, proto_binary_fetched_geometry, proto_binary_fetched_other | Connection | Total number of columns of a certain type fetched from a prepared statement (MySQL binary protocol). | For type mapping see proto_text_* described in the preceding text. |
Connection
| Statistic | Scope | Description | Notes |
|---|---|---|---|
| connect_success, connect_failure | Connection | Total number of successful / failed connection attempt. | Reused connections and all other kinds of connections are included. |
| reconnect | Process | Total number of (real_)connect attempts made on an already opened connection handle. | The code sequence $link = new mysqli(...); $link->real_connect(...) will cause a reconnect. But $link = new mysqli(...); $link->connect(...) will not because $link->connect(...) will explicitly close the existing connection before a new connection is established. |
| pconnect_success | Connection | Total number of successful persistent connection attempts. | Note that connect_success holds the sum of successful persistent and non-persistent connection attempts. The number of successful non-persistent connection attempts is connect_success - pconnect_success. |
| active_connections | Connection | Total number of active persistent and non-persistent connections. | |
| active_persistent_connections | Connection | Total number of active persistent connections. | The total number of active non-persistent connections is active_connections - active_persistent_connections. |
| explicit_close | Connection | Total number of explicitly closed connections (ext/mysqli only). | Examples of code snippets that cause an explicit close :
$link = new mysqli(...); $link->close(...) $link = new mysqli(...); $link->connect(...) |
| implicit_close | Connection | Total number of implicitly closed connections (ext/mysqli only). | Examples of code snippets that cause an implicit close :
|
| disconnect_close | Connection | Connection failures indicated by the C API call mysql_real_connect() during an attempt to establish a connection. | It is called disconnect_close because the connection handle passed to the C API call will be closed. |
| in_middle_of_command_close | Process | A connection has been closed in the middle of a command execution (outstanding result sets not fetched, after sending a query and before retrieving an answer, while fetching data, while transferring data with LOAD DATA). | Unless you use asynchronous queries this should only happen if your script stops unexpectedly and PHP shuts down the connections for you. |
| init_command_executed_count | Connection | Total number of init command executions, for example, mysqli_options(MYSQLI_INIT_COMMAND , ...). | The number of successful executions is init_command_executed_count - init_command_failed_count. |
| init_command_failed_count | Connection | Total number of failed init commands. |
COM_* Commands
| Statistic | Scope | Description | Notes |
|---|---|---|---|
| com_quit, com_init_db, com_query, com_field_list, com_create_db, com_drop_db, com_refresh, com_shutdown, com_statistics, com_process_info, com_connect, com_process_kill, com_debug, com_ping, com_time, com_delayed_insert, com_change_user, com_binlog_dump, com_table_dump, com_connect_out, com_register_slave, com_stmt_prepare, com_stmt_execute, com_stmt_send_long_data, com_stmt_close, com_stmt_reset, com_stmt_set_option, com_stmt_fetch, com_daemon | Connection | Total number of attempts to send a certain COM_* command from PHP to MySQL. | The statistics are incremented after checking the line and immediately before sending the corresponding MySQL client server protocol packet. If mysqlnd fails to send the packet over the wire the statistics will not be decremented. In case of a failure mysqlnd emits a PHP warning "Error while sending %s packet. PID=%d." Usage examples:
|
Miscellaneous
| Statistic | Scope | Description | Notes |
|---|---|---|---|
| explicit_stmt_close, implicit_stmt_close | Process | Total number of close prepared statements. | A close is always considered explicit but for a failed prepare. |
| mem_emalloc_count, mem_emalloc_ammount, mem_ecalloc_count, mem_ecalloc_ammount, mem_erealloc_count, mem_erealloc_ammount, mem_efree_count, mem_malloc_count, mem_malloc_ammount, mem_calloc_count, mem_calloc_ammount, mem_realloc_count, mem_realloc_ammount, mem_free_count | Process | Memory management calls. | Development only. |
| command_buffer_too_small | Connection | Number of network command buffer extensions while sending commands from PHP to MySQL. | mysqlnd allocates an internal command/network buffer of mysqlnd.net_cmd_buffer_size (php.ini) bytes for every connection. If a MySQL Client Server protocol command, for example, COM_QUERY (normal query), does not fit into the buffer, mysqlnd will grow the buffer to what is needed for sending the command. Whenever the buffer gets extended for one connection command_buffer_too_small will be incremented by one. If mysqlnd has to grow the buffer beyond its initial size of mysqlnd.net_cmd_buffer_size (php.ini) bytes for almost every connection, you should consider to increase the default size to avoid re-allocations. The default buffer size is 2048 bytes in PHP 5.3.0. In future versions the default will be 4kB or larger. The default can changed either through the php.ini setting mysqlnd.net_cmd_buffer_size or using mysqli_options(MYSQLI_OPT_NET_CMD_BUFFER_SIZE, int size). It is recommended to set the buffer size to no less than 4096 bytes because mysqlnd also uses it when reading certain communication packet from MySQL. In PHP 5.3.0, mysqlnd will not grow the buffer if MySQL sends a packet that is larger than the current size of the buffer. As a consequence mysqlnd is unable to decode the packet and the client application will get an error. There are only two situations when the packet can be larger than the 2048 bytes default of mysqlnd.net_cmd_buffer_size in PHP 5.3.0: the packet transports a very long error message or the packet holds column meta data from COM_LIST_FIELD (mysql_list_fields()) and the meta data comes from a string column with a very long default value (>1900 bytes). No bug report on this exists - it should happen rarely. As of PHP 5.3.2 mysqlnd does not allow setting buffers smaller than 4096 bytes. |
| connection_reused |
Notes
This section provides a collection of miscellaneous notes on MySQL Native Driver usage.
Using mysqlnd means using PHP streams for underlying connectivity. For mysqlnd, the PHP streams documentation (Streams) should be consulted on such details as timeout settings, not the documentation for the MySQL Client Library.
MySQL Native Driver Plugin API
Spis treści
- A comparison of mysqlnd plugins with MySQL Proxy
- Obtaining the mysqlnd plugin API
- MySQL Native Driver Plugin Architecture
- The mysqlnd plugin API
- Getting started building a mysqlnd plugin
The MySQL Native Driver Plugin API is a feature of MySQL Native Driver, or mysqlnd. Mysqlnd plugins operate in the layer between PHP applications and the MySQL server. This is comparable to MySQL Proxy. MySQL Proxy operates on a layer between any MySQL client application, for example, a PHP application and, the MySQL server. Mysqlnd plugins can undertake typical MySQL Proxy tasks such as load balancing, monitoring and performance optimizations. Due to the different architecture and location, mysqlnd plugins do not have some of MySQL Proxy's disadvantages. For example, with plugins, there is no single point of failure, no dedicated proxy server to deploy, and no new programming language to learn (Lua).
A mysqlnd plugin can be thought of as an extension to mysqlnd. Plugins can intercept the majority of mysqlnd functions. The mysqlnd functions are called by the PHP MySQL extensions such as ext/mysql, ext/mysqli, and PDO_MYSQL. As a result, it is possible for a mysqlnd plugin to intercept all calls made to these extensions from the client application.
Internal mysqlnd function calls can also be intercepted, or replaced. There are no restrictions on manipulating mysqlnd internal function tables. It is possible to set things up so that when certain mysqlnd functions are called by the extensions that use mysqlnd, the call is directed to the appropriate function in the mysqlnd plugin. The ability to manipulate mysqlnd internal function tables in this way allows maximum flexibility for plugins.
Mysqlnd plugins are in fact PHP Extensions, written in C, that use the mysqlnd plugin API (which is built into MySQL Native Driver, mysqlnd). Plugins can be made 100% transparent to PHP applications. No application changes are needed because plugins operate on a different layer. The mysqlnd plugin can be thought of as operating in a layer below mysqlnd.
The following list represents some possible applications of mysqlnd plugins.
-
Load Balancing
-
Read/Write Splitting. An example of this is the PECL/mysqlnd_ms (Master Slave) extension. This extension splits read/write queries for a replication setup.
-
Failover
-
Round-Robin, least loaded
-
-
Monitoring
-
Query Logging
-
Query Analysis
-
Query Auditing. An example of this is the PECL/mysqlnd_sip (SQL Injection Protection) extension. This extension inspects queries and executes only those that are allowed according to a ruleset.
-
-
Performance
-
Caching. An example of this is the PECL/mysqlnd_qc (Query Cache) extension.
-
Throttling
-
Sharding. An example of this is the PECL/mysqlnd_mc (Multi Connect) extension. This extension will attempt to split a SELECT statement into n-parts, using SELECT ... LIMIT part_1, SELECT LIMIT part_n. It sends the queries to distinct MySQL servers and merges the result at the client.
-
MySQL Native Driver Plugins Available
There are a number of mysqlnd plugins already available. These include:
-
PECL/mysqlnd_mc - Multi Connect plugin.
-
PECL/mysqlnd_ms - Master Slave plugin.
-
PECL/mysqlnd_qc - Query Cache plugin.
-
PECL/mysqlnd_pscache - Prepared Statement Handle Cache plugin.
-
PECL/mysqlnd_sip - SQL Injection Protection plugin.
-
PECL/mysqlnd_uh - User Handler plugin.
A comparison of mysqlnd plugins with MySQL Proxy
Mysqlnd plugins and MySQL Proxy are different technologies using different approaches. Both are valid tools for solving a variety of common tasks such as load balancing, monitoring, and performance enhancements. An important difference is that MySQL Proxy works with all MySQL clients, whereas mysqlnd plugins are specific to PHP applications.
As a PHP Extension, a mysqlnd plugin gets installed on the PHP application server, along with the rest of PHP. MySQL Proxy can either be run on the PHP application server or can be installed on a dedicated machine to handle multiple PHP application servers.
Deploying MySQL Proxy on the application server has two advantages:
-
No single point of failure
-
Easy to scale out (horizontal scale out, scale by client)
MySQL Proxy (and mysqlnd plugins) can solve problems easily which otherwise would have required changes to existing applications.
However, MySQL Proxy does have some disadvantages:
-
MySQL Proxy is a new component and technology to master and deploy.
-
MySQL Proxy requires knowledge of the Lua scripting language.
MySQL Proxy can be customized with C and Lua programming. Lua is the preferred scripting language of MySQL Proxy. For most PHP experts Lua is a new language to learn. A mysqlnd plugin can be written in C. It is also possible to write plugins in PHP using » PECL/mysqlnd_uh.
MySQL Proxy runs as a daemon - a background process. MySQL Proxy can recall earlier decisions, as all state can be retained. However, a mysqlnd plugin is bound to the request-based lifecycle of PHP. MySQL Proxy can also share one-time computed results among multiple application servers. A mysqlnd plugin would need to store data in a persistent medium to be able to do this. Another daemon would need to be used for this purpose, such as Memcache. This gives MySQL Proxy an advantage in this case.
MySQL Proxy works on top of the wire protocol. With MySQL Proxy you have to parse and reverse engineer the MySQL Client Server Protocol. Actions are limited to those that can be achieved by manipulating the communication protocol. If the wire protocol changes (which happens very rarely) MySQL Proxy scripts would need to be changed as well.
Mysqlnd plugins work on top of the C API, which mirrors the libmysql client and Connector/C APIs. This C API is basically a wrapper around the MySQL Client Server protocol, or wire protocol, as it is sometimes called. You can intercept all C API calls. PHP makes use of the C API, therefore you can hook all PHP calls, without the need to program at the level of the wire protocol.
Mysqlnd implements the wire protocol. Plugins can therefore parse, reverse engineer, manipulate and even replace the communication protocol. However, this is usually not required.
As plugins allow you to create implementations that use two levels (C API and wire protocol), they have greater flexibility than MySQL Proxy. If a mysqlnd plugin is implemented using the C API, any subsequent changes to the wire protocol do not require changes to the plugin itself.
Obtaining the mysqlnd plugin API
The mysqlnd plugin API is simply part of the MySQL Native Driver PHP extension, ext/mysqlnd. Development started on the mysqlnd plugin API in December 2009. It is developed as part of the PHP source repository, and as such is available to the public either via SVN, or through source snapshot downloads.
The following table shows PHP versions and the corresponding mysqlnd version contained within.
| PHP Version | MySQL Native Driver version |
|---|---|
| 5.3.0 | 5.0.5 |
| 5.3.1 | 5.0.5 |
| 5.3.2 | 5.0.7 |
| 5.3.3 | 5.0.7 |
| 5.3.4 | 5.0.7 |
Plugin developers can determine the mysqlnd version through accessing MYSQLND_VERSION, which is a string of the format "mysqlnd 5.0.7-dev - 091210 - $Revision: 300535", or through MYSQLND_VERSION_ID, which is an integer such as 50007. Developers can calculate the version number as follows:
| Version (part) | Example |
|---|---|
| Major*10000 | 5*10000 = 50000 |
| Minor*100 | 0*100 = 0 |
| Patch | 7 = 7 |
| MYSQLND_VERSION_ID | 50007 |
During development, developers should refer to the mysqlnd version number for compatibility and version tests, as several iterations of mysqlnd could occur during the lifetime of a PHP development branch with a single PHP version number.
MySQL Native Driver Plugin Architecture
This section provides an overview of the mysqlnd plugin architecture.
MySQL Native Driver Overview
Before developing mysqlnd plugins, it is useful to know a little of how mysqlnd itself is organized. Mysqlnd consists of the following modules:
| Modules Statistics | mysqlnd_statistics.c |
| Connection | mysqlnd.c |
| Resultset | mysqlnd_result.c |
| Resultset Metadata | mysqlnd_result_meta.c |
| Statement | mysqlnd_ps.c |
| Network | mysqlnd_net.c |
| Wire protocol | mysqlnd_wireprotocol.c |
C Object Oriented Paradigm
At the code level, mysqlnd uses a C pattern for implementing object orientation.
In C you use a struct to represent an object. Members of the struct represent object properties. Struct members pointing to functions represent methods.
Unlike with other languages such as C++ or Java, there are no fixed rules on inheritance in the C object oriented paradigm. However, there are some conventions that need to be followed that will be discussed later.
The PHP Life Cycle
When considering the PHP life cycle there are two basic cycles:
-
PHP engine startup and shutdown cycle
-
Request cycle
When the PHP engine starts up it will call the module initialization (MINIT) function of each registered extension. This allows each module to setup variables and allocate resources that will exist for the lifetime of the PHP engine process. When the PHP engine shuts down it will call the module shutdown (MSHUTDOWN) function of each extension.
During the lifetime of the PHP engine it will receive a number of requests. Each request constitutes another life cycle. On each request the PHP engine will call the request initialization function of each extension. The extension can perform any variable setup and resource allocation required for request processing. As the request cycle ends the engine calls the request shutdown (RSHUTDOWN) function of each extension so the extension can perform any cleanup required.
How a plugin works
A mysqlnd plugin works by intercepting calls made to mysqlnd by extensions that use mysqlnd. This is achieved by obtaining the mysqlnd function table, backing it up, and replacing it by a custom function table, which calls the functions of the plugin as required.
The following code shows how the mysqlnd function table is replaced:
/* a place to store orginal function table */
struct st_mysqlnd_conn_methods org_methods;
void minit_register_hooks(TSRMLS_D) {
/* active function table */
struct st_mysqlnd_conn_methods * current_methods
= mysqlnd_conn_get_methods();
/* backup original function table */
memcpy(&org_methods, current_methods,
sizeof(struct st_mysqlnd_conn_methods);
/* install new methods */
current_methods->query = MYSQLND_METHOD(my_conn_class, query);
}
Connection function table manipulations must be done during Module Initialization (MINIT). The function table is a global shared resource. In an multi-threaded environment, with a TSRM build, the manipulation of a global shared resource during the request processing will almost certainly result in conflicts.
Informacja:
Do not use any fixed-size logic when manipulating the mysqlnd function table: new methods may be added at the end of the function table. The function table may change at any time in the future.
Calling parent methods
If the original function table entries are backed up, it is still possible to call the original function table entries - the parent methods.
In some cases, such as for Connection::stmt_init(), it is vital to call the parent method prior to any other activity in the derived method.
MYSQLND_METHOD(my_conn_class, query)(MYSQLND *conn,
const char *query, unsigned int query_len TSRMLS_DC) {
php_printf("my_conn_class::query(query = %s)\n", query);
query = "SELECT 'query rewritten' FROM DUAL";
query_len = strlen(query);
return org_methods.query(conn, query, query_len); /* return with call to parent */
}
Extending properties
A mysqlnd object is represented by a C struct. It is not possible to add a member to a C struct at run time. Users of mysqlnd objects cannot simply add properties to the objects.
Arbitrary data (properties) can be added to a mysqlnd objects using an appropriate function of the mysqlnd_plugin_get_plugin_<object>_data() family. When allocating an object mysqlnd reserves space at the end of the object to hold a void * pointer to arbitrary data. mysqlnd reserves space for one void * pointer per plugin.
The following table shows how to calculate the position of the pointer for a specific plugin:
| Memory address | Contents |
| 0 | Beginning of the mysqlnd object C struct |
| n | End of the mysqlnd object C struct |
| n + (m x sizeof(void*)) | void* to object data of the m-th plugin |
If you plan to subclass any of the mysqlnd object constructors, which is allowed, you must keep this in mind!
The following code shows extending properties:
/* any data we want to associate */
typedef struct my_conn_properties {
unsigned long query_counter;
} MY_CONN_PROPERTIES;
/* plugin id */
unsigned int my_plugin_id;
void minit_register_hooks(TSRMLS_D) {
/* obtain unique plugin ID */
my_plugin_id = mysqlnd_plugin_register();
/* snip - see Extending Connection: methods */
}
static MY_CONN_PROPERTIES** get_conn_properties(const MYSQLND *conn TSRMLS_DC) {
MY_CONN_PROPERTIES** props;
props = (MY_CONN_PROPERTIES**)mysqlnd_plugin_get_plugin_connection_data(
conn, my_plugin_id);
if (!props || !(*props)) {
*props = mnd_pecalloc(1, sizeof(MY_CONN_PROPERTIES), conn->persistent);
(*props)->query_counter = 0;
}
return props;
}
The plugin developer is responsible for the management of plugin data memory.
Use of the mysqlnd memory allocator is recommended for plugin data. These functions are named using the convention: mnd_*loc(). The mysqlnd allocator has some useful features, such as the ability to use a debug allocator in a non-debug build.
When and how to subclass
| When to subclass? | Each instance has its own private function table? | How to subclass? | |
| Connection (MYSQLND) | MINIT | No | mysqlnd_conn_get_methods() |
| Resultset (MYSQLND_RES) | MINIT or later | Yes | mysqlnd_result_get_methods() or object method function table manipulation |
| Resultset Meta (MYSQLND_RES_METADATA) | MINIT | No | mysqlnd_result_metadata_get_methods() |
| Statement (MYSQLND_STMT) | MINIT | No | mysqlnd_stmt_get_methods() |
| Network (MYSQLND_NET) | MINIT or later | Yes | mysqlnd_net_get_methods() or object method function table manipulation |
| Wire protocol (MYSQLND_PROTOCOL) | MINIT or later | Yes | mysqlnd_protocol_get_methods() or object method function table manipulation |
You must not manipulate function tables at any time later than MINIT if it is not allowed according to the above table.
Some classes contain a pointer to the method function table. All instances of such a class will share the same function table. To avoid chaos, in particular in threaded environments, such function tables must only be manipulated during MINIT.
Other classes use copies of a globally shared function table. The class function table copy is created together with the object. Each object uses its own function table. This gives you two options: you can manipulate the default function table of an object at MINIT, and you can additionally refine methods of an object without impacting other instances of the same class.
The advantage of the shared function table approach is performance. There is no need to copy a function table for each and every object.
Constructors
| Allocation, construction, reset | Can be modified? | Caller | |
| Connection (MYSQLND) | mysqlnd_init() | No | mysqlnd_connect() |
| Resultset(MYSQLND_RES) | Allocation:
Reset and re-initialized during:
|
Yes, but call parent! |
|
| Resultset Meta (MYSQLND_RES_METADATA) | Connection::result_meta_init() | Yes, but call parent! | Result::read_result_metadata() |
| Statement (MYSQLND_STMT) | Connection::stmt_init() | Yes, but call parent! | Connection::stmt_init() |
| Network (MYSQLND_NET) | mysqlnd_net_init() | No | Connection::init() |
| Wire protocol (MYSQLND_PROTOCOL) | mysqlnd_protocol_init() | No | Connection::init() |
It is strongly recommended that you do not entirely replace a constructor. The constructors perform memory allocations. The memory allocations are vital for the mysqlnd plugin API and the object logic of mysqlnd. If you do not care about warnings and insist on hooking the constructors, you should at least call the parent constructor before doing anything in your constructor.
Regardless of all warnings, it can be useful to subclass constructors. Constructors are the perfect place for modifying the function tables of objects with non-shared object tables, such as Resultset, Network, Wire Protocol.
Destruction
| Derived method must call parent? | Destructor | |
| Connection | yes, after method execution | free_contents(), end_psession() |
| Resultset | yes, after method execution | free_result() |
| Resultset Meta | yes, after method execution | free() |
| Statement | yes, after method execution | dtor(), free_stmt_content() |
| Network | yes, after method execution | free() |
| Wire protocol | yes, after method execution | free() |
The destructors are the appropriate place to free properties, mysqlnd_plugin_get_plugin_<object>_data().
The listed destructors may not be equivalent to the actual mysqlnd method freeing the object itself. However, they are the best possible place for you to hook in and free your plugin data. As with constructors you may replace the methods entirely but this is not recommended. If multiple methods are listed in the above table you will need to hook all of the listed methods and free your plugin data in whichever method is called first by mysqlnd.
The recommended method for plugins is to simply hook the methods, free your memory and call the parent implementation immediately following this.
Due to a bug in PHP versions 5.3.0 to 5.3.3, plugins do not associate plugin data with a persistent connection. This is because ext/mysql and ext/mysqli do not trigger all the necessary mysqlnd end_psession() method calls and the plugin may therefore leak memory. This has been fixed in PHP 5.3.4.
The mysqlnd plugin API
The following is a list of functions provided in the mysqlnd plugin API:
-
mysqlnd_plugin_register()
-
mysqlnd_plugin_count()
-
mysqlnd_plugin_get_plugin_connection_data()
-
mysqlnd_plugin_get_plugin_result_data()
-
mysqlnd_plugin_get_plugin_stmt_data()
-
mysqlnd_plugin_get_plugin_net_data()
-
mysqlnd_plugin_get_plugin_protocol_data()
-
mysqlnd_conn_get_methods()
-
mysqlnd_result_get_methods()
-
mysqlnd_result_meta_get_methods()
-
mysqlnd_stmt_get_methods()
-
mysqlnd_net_get_methods()
-
mysqlnd_protocol_get_methods()
There is no formal definition of what a plugin is and how a plugin mechanism works.
Components often found in plugins mechanisms are:
-
A plugin manager
-
A plugin API
-
Application services (or modules)
-
Application service APIs (or module APIs)
The mysqlnd plugin concept employs these features, and additionally enjoys an open architecture.
No Restrictions
A plugin has full access to the inner workings of mysqlnd. There are no security limits or restrictions. Everything can be overwritten to implement friendly or hostile algorithms. It is recommended you only deploy plugins from a trusted source.
As discussed previously, plugins can use pointers freely. These pointers are not restricted in any way, and can point into another plugin's data. Simple offset arithmetic can be used to read another plugin's data.
It is recommended that you write cooperative plugins, and that you always call the parent method. The plugins should always cooperate with mysqlnd itself.
Issues: an example of chaining and cooperation
| Extension | mysqlnd.query() pointer | call stack if calling parent |
| ext/mysqlnd | mysqlnd.query() | mysqlnd.query |
| ext/mysqlnd_cache | mysqlnd_cache.query() |
|
| ext/mysqlnd_monitor | mysqlnd_monitor.query() |
|
In this scenario, a cache (ext/mysqlnd_cache) and a monitor (ext/mysqlnd_monitor) plugin are loaded. Both subclass Connection::query(). Plugin registration happens at MINIT using the logic shown previously. PHP calls extensions in alphabetical order by default. Plugins are not aware of each other and do not set extension dependencies.
By default the plugins call the parent implementation of the query method in their derived version of the method.
PHP Extension Recap
This is a recap of what happens when using an example plugin, ext/mysqlnd_plugin, which exposes the mysqlnd C plugin API to PHP:
-
Any PHP MySQL application tries to establish a connection to 192.168.2.29
-
The PHP application will either use ext/mysql, ext/mysqli or PDO_MYSQL. All three PHP MySQL extensions use mysqlnd to establish the connection to 192.168.2.29.
-
Mysqlnd calls its connect method, which has been subclassed by ext/mysqlnd_plugin.
-
ext/mysqlnd_plugin calls the userspace hook proxy::connect() registered by the user.
-
The userspace hook changes the connection host IP from 192.168.2.29 to 127.0.0.1 and returns the connection established by parent::connect().
-
ext/mysqlnd_plugin performs the equivalent of parent::connect(127.0.0.1) by calling the original mysqlnd method for establishing a connection.
-
ext/mysqlnd establishes a connection and returns to ext/mysqlnd_plugin. ext/mysqlnd_plugin returns as well.
-
Whatever PHP MySQL extension had been used by the application, it receives a connection to 127.0.0.1. The PHP MySQL extension itself returns to the PHP application. The circle is closed.
Getting started building a mysqlnd plugin
It is important to remember that a mysqlnd plugin is itself a PHP extension.
The following code shows the basic structure of the MINIT function that will be used in the typical mysqlnd plugin:
/* my_php_mysqlnd_plugin.c */
static PHP_MINIT_FUNCTION(mysqlnd_plugin) {
/* globals, ini entries, resources, classes */
/* register mysqlnd plugin */
mysqlnd_plugin_id = mysqlnd_plugin_register();
conn_m = mysqlnd_get_conn_methods();
memcpy(org_conn_m, conn_m,
sizeof(struct st_mysqlnd_conn_methods));
conn_m->query = MYSQLND_METHOD(mysqlnd_plugin_conn, query);
conn_m->connect = MYSQLND_METHOD(mysqlnd_plugin_conn, connect);
}
/* my_mysqlnd_plugin.c */
enum_func_status MYSQLND_METHOD(mysqlnd_plugin_conn, query)(/* ... */) {
/* ... */
}
enum_func_status MYSQLND_METHOD(mysqlnd_plugin_conn, connect)(/* ... */) {
/* ... */
}
Task analysis: from C to userspace
class proxy extends mysqlnd_plugin_connection {
public function connect($host, ...) { .. }
}
mysqlnd_plugin_set_conn_proxy(new proxy());
Process:
-
PHP: user registers plugin callback
-
PHP: user calls any PHP MySQL API to connect to MySQL
-
C: ext/*mysql* calls mysqlnd method
-
C: mysqlnd ends up in ext/mysqlnd_plugin
-
C: ext/mysqlnd_plugin
-
Calls userspace callback
-
Or orginal mysqlnd method, if userspace callback not set
-
You need to carry out the following:
-
Write a class "mysqlnd_plugin_connection" in C
-
Accept and register proxy object through "mysqlnd_plugin_set_conn_proxy()"
-
Call userspace proxy methods from C (optimization - zend_interfaces.h)
Userspace object methods can either be called using call_user_function() or you can operate at a level closer to the Zend Engine and use zend_call_method().
Optimization: calling methods from C using zend_call_method
The following code snippet shows the prototype for the zend_call_method function, taken from zend_interfaces.h.
ZEND_API zval* zend_call_method( zval **object_pp, zend_class_entry *obj_ce, zend_function **fn_proxy, char *function_name, int function_name_len, zval **retval_ptr_ptr, int param_count, zval* arg1, zval* arg2 TSRMLS_DC );
Zend API supports only two arguments. You may need more, for example:
enum_func_status (*func_mysqlnd_conn__connect)( MYSQLND *conn, const char *host, const char * user, const char * passwd, unsigned int passwd_len, const char * db, unsigned int db_len, unsigned int port, const char * socket, unsigned int mysql_flags TSRMLS_DC );
To get around this problem you will need to make a copy of zend_call_method() and add a facility for additional parameters. You can do this by creating a set of MY_ZEND_CALL_METHOD_WRAPPER macros.
Calling PHP userspace
This code snippet shows the optimized method for calling a userspace function from C:
/* my_mysqlnd_plugin.c */
MYSQLND_METHOD(my_conn_class,connect)(
MYSQLND *conn, const char *host /* ... */ TSRMLS_DC) {
enum_func_status ret = FAIL;
zval * global_user_conn_proxy = fetch_userspace_proxy();
if (global_user_conn_proxy) {
/* call userspace proxy */
ret = MY_ZEND_CALL_METHOD_WRAPPER(global_user_conn_proxy, host, /*...*/);
} else {
/* or original mysqlnd method = do nothing, be transparent */
ret = org_methods.connect(conn, host, user, passwd,
passwd_len, db, db_len, port,
socket, mysql_flags TSRMLS_CC);
}
return ret;
}
Calling userspace: simple arguments
/* my_mysqlnd_plugin.c */
MYSQLND_METHOD(my_conn_class,connect)(
/* ... */, const char *host, /* ...*/) {
/* ... */
if (global_user_conn_proxy) {
/* ... */
zval* zv_host;
MAKE_STD_ZVAL(zv_host);
ZVAL_STRING(zv_host, host, 1);
MY_ZEND_CALL_METHOD_WRAPPER(global_user_conn_proxy, zv_retval, zv_host /*, ...*/);
zval_ptr_dtor(&zv_host);
/* ... */
}
/* ... */
}
Calling userspace: structs as arguments
/* my_mysqlnd_plugin.c */
MYSQLND_METHOD(my_conn_class, connect)(
MYSQLND *conn, /* ...*/) {
/* ... */
if (global_user_conn_proxy) {
/* ... */
zval* zv_conn;
ZEND_REGISTER_RESOURCE(zv_conn, (void *)conn, le_mysqlnd_plugin_conn);
MY_ZEND_CALL_METHOD_WRAPPER(global_user_conn_proxy, zv_retval, zv_conn, zv_host /*, ...*/);
zval_ptr_dtor(&zv_conn);
/* ... */
}
/* ... */
}
The first argument of many mysqlnd methods is a C "object". For example, the first argument of the connect() method is a pointer to MYSQLND. The struct MYSQLND represents a mysqlnd connection object.
The mysqlnd connection object pointer can be compared to a standard I/O file handle. Like a standard I/O file handle a mysqlnd connection object shall be linked to the userspace using the PHP resource variable type.
From C to userspace and back
class proxy extends mysqlnd_plugin_connection {
public function connect($conn, $host, ...) {
/* "pre" hook */
printf("Connecting to host = '%s'\n", $host);
debug_print_backtrace();
return parent::connect($conn);
}
public function query($conn, $query) {
/* "post" hook */
$ret = parent::query($conn, $query);
printf("Query = '%s'\n", $query);
return $ret;
}
}
mysqlnd_plugin_set_conn_proxy(new proxy());
PHP users must be able to call the parent implementation of an overwritten method.
As a result of subclassing it is possible to refine only selected methods and you can choose to have "pre" or "post" hooks.
Buildin class: mysqlnd_plugin_connection::connect()
/* my_mysqlnd_plugin_classes.c */
PHP_METHOD("mysqlnd_plugin_connection", connect) {
/* ... simplified! ... */
zval* mysqlnd_rsrc;
MYSQLND* conn;
char* host; int host_len;
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "rs",
&mysqlnd_rsrc, &host, &host_len) == FAILURE) {
RETURN_NULL();
}
ZEND_FETCH_RESOURCE(conn, MYSQLND* conn, &mysqlnd_rsrc, -1,
"Mysqlnd Connection", le_mysqlnd_plugin_conn);
if (PASS == org_methods.connect(conn, host, /* simplified! */ TSRMLS_CC))
RETVAL_TRUE;
else
RETVAL_FALSE;
}
Mysqlnd replication and load balancing plugin
Wstęp
The mysqlnd replication and load balancing plugin (mysqlnd_ms) adds easy to use MySQL replication support to all PHP MySQL extensions that use mysqlnd.
As of version PHP 5.3.3 the MySQL native driver for PHP (mysqlnd) features an internal plugin C API. C plugins, such as the replication and load balancing plugin, can extend the functionality of mysqlnd.
The MySQL native driver for PHP is a C library that ships together with PHP as of PHP 5.3.0. It serves as a drop-in replacement for the MySQL Client Library (libmysql/libmysqlclient). Using mysqlnd has several advantages: no extra downloads are required because it's bundled with PHP, it's under the PHP license, there is lower memory consumption in certain cases, and it contains new functionality such as asynchronous queries.
Mysqlnd plugins like mysqlnd_ms operate, for the most part, transparently from a user perspective. The replication and load balancing plugin supports all PHP applications, and all MySQL PHP extensions. It does not change existing APIs. Therefore, it can easily be used with existing PHP applications.
Informacja:
The mysqlnd replication and load balancing plugin is a beta plugin, and is not feature complete.
Key Features
The key features of PECL/mysqlnd_ms are as follows.
-
Transparent and therefore easy to use.
-
Supports all of the PHP MySQL extensions.
-
SSL support.
-
A consistent API.
-
Little to no application changes required, dependent on the required usage scenario.
-
Lazy connections: connections to master and slave servers are not opened before a SQL statement is executed.
-
Optional: automatic use of master after the first write in a web request, to lower the possible impact of replication lag.
-
-
Featured read-write split strategies
-
Automatic detection of SELECT.
-
Supports SQL hints to overrule automatism.
-
User-defined.
-
Can be disabled for, for example, when using synchronous clusters such as MySQL Cluster.
-
-
Featured load balancing strategies
-
Round Robin: choose a different slave in round-robin fashion for every slave request.
-
Random: choose a random slave for every slave request.
-
Random once (sticky): choose a random slave once to run all slave requests for the duration of a web request.
-
User-defined. The application can register callbacks with mysqlnd_ms.
-
PHP 5.4.0 or newer: transaction aware when using API calls only to control transactions.
-
-
Global transaction ID
-
Client-side emulation. Makes manual master server failover and slave promotion easier with asynchronous clusters, such as MySQL Replication.
-
Support for built-in global transaction identifier feature of MySQL 5.6.5-m8 or newer.
-
Supports using transaction ids to identify up-to-date asynchronous slaves for reading when session consistency is required.
-
-
Service and consistency levels
-
Applications can request eventual, session and strong consistency service levels for connections. Appropriate cluster nodes will be searched automatically.
-
Eventual consistent MySQL Replication slave accesses can be replaced with fast local cache accesses transparently to reduce server load.
-
Limitations
The plugin does not support MySQL replication setups with more than one master server. The experimental configuration setting mysqlnd_ms.multi_master was introduced in version 1.1.0-beta, to help find ways to remove this limitation and to enable the use of synchronous clusters, such as MySQL Cluster.
The built-in read/write-split mechanism is very basic. Every query which starts with SELECT is considered a read request to be sent to a MySQL slave server. All other queries (such as SHOW statements) are considered as write requests that are sent to the MySQL master server. The build-in behavior can be overruled using SQL hints, or a user-defined callback function.
The read/write splitter is not aware of multi-statements. Multi-statements are considered as one statement. The decision of where to run the statement will be based on the beginning of the statement string. For example, if using mysqli_multi_query() to execute the multi-statement SELECT id FROM test ; INSERT INTO test(id) VALUES (1), the statement will be redirected to a slave server because it begins with SELECT. The INSERT statement, which is also part of the multi-statement, will not be redirected to a master server.
Prior to version 1.1.0-beta, the plugin did not support native prepared statements. Please note that PDO_MySQL uses client-side prepared statement emulation by default. Client-side emulated prepared statements are fully supported by any version of the replication and load balancing plugin because the emulation is not using native prepared statements. If you are using PHP based database abstraction, please consult the vendor manual to learn if a client-side prepared statement emulation is used.
Informacja:
Applications must be aware of the consequences of connection switches that are performed for load balancing purposes. Please check the documentation on connection pooling and switching, transaction handling, failover load balancing i read-write splitting.
On the name
The shortcut mysqlnd_ms stands for mysqlnd master slave plugin. The name was chosen for a quick-and-dirty proof-of-concept. In the beginning the developers did not expect to continue using the code base.
Quickstart and Examples
Spis treści
- Setup
- Running statements
- Connection state
- SQL Hints
- Transactions
- Service level and consistency
- Global transaction IDs
- Cache integration
The mysqlnd replication load balancing plugin is easy to use. This quickstart will demo typical use-cases, and provide practical advice on getting started.
It is strongly recommended to read the reference sections in addition to the quickstart. The quickstart tries to avoid discussing theoretical concepts and limitations. Instead, it will link to the reference sections. It is safe to begin with the quickstart. However, before using the plugin in mission critical environments we urge you to read additionally the background information from the reference sections.
The focus is on using PECL mysqlnd_ms for work with an asynchronous MySQL cluster, namelys MySQL replication. Generally speaking an asynchronous cluster is more difficult to use than a synchronous one. Thus, users of, for example, MySQL Cluster will find more information than needed.
Informacja:
The documentation has been updated to show the syntax used as of version 1.1.0-beta. PECL/mysqlnd_ms 1.1.0-beta introduces many changes. Among others, it is using a new JSON based plugin configuration file format.
Setup
The plugin is implemented as a PHP extension. See also the installation instructions to install the » PECL/mysqlnd_ms extension.
Compile or configure the PHP MySQL extension (API) (mysqli, PDO_MYSQL, mysql) that you plan to use with support for the mysqlnd library. PECL/mysqlnd_ms is a plugin for the mysqlnd library. To use the plugin with any of the PHP MySQL extensions, the extension has to use the mysqlnd library.
Then, load the extension into PHP and activate the plugin in the PHP configuration file using the PHP configuration directive named mysqlnd_ms.enable.
Przykład #1 Enabling the plugin (php.ini)
mysqlnd_ms.enable=1 mysqlnd_ms.ini_file=/path/to/mysqlnd_ms_plugin.ini
The plugin uses its own configuration file. Use the PHP configuration directive mysqlnd_ms.ini_file to set the full file path to the plugin-specific configuration file. This file must be readable by PHP (e.g., the web server user).
Create a plugin-specific configuration file. Save the file to the path set by the PHP configuration directive mysqlnd_ms.ini_file.
The plugins configuration file is JSON based. It is divided into one or more sections. Each section has a name, for example, myapp. Every section makes its own set of configuration settings.
A section must, at a minimum, list the MySQL replication master server, and set a list of slaves. The plugin supports using only one master server per section. Multi-master MySQL replication setups are not yet fully supported. Use the configuration setting master to set the hostname, and the port or socket of the MySQL master server. MySQL slave servers are configured using the slave keyword.
Przykład #2 Minimal plugin-specific configuration file (mysqlnd_ms_plugin.ini)
{
"myapp": {
"master": {
"master_0": {
"host": "localhost"
}
},
"slave": [
]
}
}
Configuring a MySQL slave server list is required, although it may contain an empty list. It is recommended to always configure at least one slave server.
Server lists can use anonymous or non-anonymous syntax. Non-anonymous lists include alias names for the servers, such as master_0 for the master in the above example. The quickstart uses the more verbose non-anonymous syntax.
Przykład #3 Recommended minimal plugin-specific config (mysqlnd_ms_plugin.ini)
{
"myapp": {
"master": {
"master_0": {
"host": "localhost",
"socket": "\/tmp\/mysql.sock"
}
},
"slave": {
"slave_0": {
"host": "192.168.2.27",
"port": "3306"
}
}
}
}
If there are at least two servers in total, the plugin can start to load balance and switch connections. Switching connections is not always transparent and can cause issues in certain cases. The reference sections about connection pooling and switching, transaction handling, fail over load balancing and read-write splitting all provide more details. And potential pitfalls are described later in this guide.
It is the responsibility of the application to handle potential issues caused by connection switches, by configuring a master with at least one slave server, which allows switching to work therefore related problems can be found.
The MySQL master and MySQL slave servers, which you configure, do not need to be part of MySQL replication setup. For testing purpose you can use single MySQL server and make it known to the plugin as a master and slave server as shown below. This could help you to detect many potential issues with connection switches. However, such a setup will not be prone to the issues caused by replication lag.
Przykład #4 Using one server as a master and as a slave (testing only!)
{
"myapp": {
"master": {
"master_0": {
"host": "localhost",
"socket": "\/tmp\/mysql.sock"
}
},
"slave": {
"slave_0": {
"host": "127.0.0.1",
"port": "3306"
}
}
}
}
Running statements
The plugin can be used with any PHP MySQL extension (mysqli, mysql, and PDO_MYSQL) that is compiled to use the mysqlnd library. PECL/mysqlnd_ms plugs into the mysqlnd library. It does not change the API or behavior of those extensions.
Whenever a connection to MySQL is being opened, the plugin compares the host parameter value of the connect call, with the section names from the plugin specific configuration file. If, for example, the plugin specific configuration file has a section myapp then the section should be referenced by opening a MySQL connection to the host myapp
Przykład #1 Plugin specific configuration file (mysqlnd_ms_plugin.ini)
{
"myapp": {
"master": {
"master_0": {
"host": "localhost",
"socket": "\/tmp\/mysql.sock"
}
},
"slave": {
"slave_0": {
"host": "192.168.2.27",
"port": "3306"
}
}
}
}
Przykład #2 Opening a load balanced connection
<?php
/* Load balanced following "myapp" section rules from the plugins config file */
$mysqli = new mysqli("myapp", "username", "password", "database");
$pdo = new PDO('mysql:host=myapp;dbname=database', 'username', 'password');
$mysql = mysql_connect("myapp", "username", "password");
?>
The connection examples above will be load balanced. The plugin will send read-only statements to the MySQL slave server with the IP 192.168.2.27 and will listen on port 3306 for the MySQL client connection. All other statements will be directed to the MySQL master server running on the host localhost. If on Unix like operating systems, the master on localhost will be accepting MySQL client connections on the Unix domain socket /tmp/mysql.sock, while TCP/IP is the default port on Windows. The plugin will use the user name username and the password password to connect to any of the MySQL servers listed in the section myapp of the plugins configuration file. Upon connect, the plugin will select database as the current schemata.
The username, password and schema name are taken from the connect API calls and used for all servers. In other words: you must use the same username and password for every MySQL server listed in a plugin configuration file section. The is not a general limitation. As of PECL/mysqlnd_ms 1.1.0, it is possible to set the username and password for any server in the plugins configuration file, to be used instead of the credentials passed to the API call.
The plugin does not change the API for running statements. Read-write splitting works out of the box. The following example assumes that there is no significant replication lag between the master and the slave.
Przykład #3 Executing statements
<?php
/* Load balanced following "myapp" section rules from the plugins config file */
$mysqli = new mysqli("myapp", "username", "password", "database");
if (mysqli_connect_errno())
/* Of course, your error handling is nicer... */
die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
/* Statements will be run on the master */
if (!$mysqli->query("DROP TABLE IF EXISTS test")) {
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}
if (!$mysqli->query("CREATE TABLE test(id INT)")) {
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}
if (!$mysqli->query("INSERT INTO test(id) VALUES (1)")) {
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}
/* read-only: statement will be run on a slave */
if (!($res = $mysqli->query("SELECT id FROM test")) {
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
} else {
$row = $res->fetch_assoc();
$res->close();
printf("Slave returns id = '%s'\n", $row['id'];
}
$mysqli->close();
?>
Powyższy przykład wyświetli coś podobnego do:
Slave returns id = '1'
Connection state
The plugin changes the semantics of a PHP MySQL connection handle. A new connection handle represents a connection pool, instead of a single MySQL client-server network connection. The connection pool consists of a master connection, and optionally any number of slave connections.
Every connection from the connection pool has its own state. For example, SQL user variables, temporary tables and transactions are part of the state. For a complete list of items that belong to the state of a connection, see the connection pooling and switching concepts documentation. If the plugin decides to switch connections for load balancing, the application could be given a connection which has a different state. Applications must be made aware of this.
Przykład #1 Plugin config with one slave and one master
{
"myapp": {
"master": {
"master_0": {
"host": "localhost",
"socket": "\/tmp\/mysql.sock"
}
},
"slave": {
"slave_0": {
"host": "192.168.2.27",
"port": "3306"
}
}
}
}
Przykład #2 Pitfall: connection state and SQL user variables
<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli)
/* Of course, your error handling is nicer... */
die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
/* Connection 1, connection bound SQL user variable, no SELECT thus run on master */
if (!$mysqli->query("SET @myrole='master'")) {
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}
/* Connection 2, run on slave because SELECT */
if (!($res = $mysqli->query("SELECT @myrole AS _role"))) {
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
} else {
$row = $res->fetch_assoc();
$res->close();
printf("@myrole = '%s'\n", $row['_role']);
}
$mysqli->close();
?>
Powyższy przykład wyświetli:
@myrole = ''
The example opens a load balanced connection and executes two statements. The first statement SET @myrole='master' does not begin with the string SELECT. Therefore the plugin does not recognize it as a read-only query which shall be run on a slave. The plugin runs the statement on the connection to the master. The statement sets a SQL user variable which is bound to the master connection. The state of the master connection has been changed.
The next statement is SELECT @myrole AS _role. The plugin does recognize it as a read-only query and sends it to the slave. The statement is run on a connection to the slave. This second connection does not have any SQL user variables bound to it. It has a different state than the first connection to the master. The requested SQL user variable is not set. The example script prints @myrole = ''.
It is the responsibility of the application developer to take care of the connection state. The plugin does not monitor all connection state changing activities. Monitoring all possible cases would be a very CPU intensive task, if it could be done at all.
The pitfalls can easily be worked around using SQL hints.
SQL Hints
SQL hints can force a query to choose a specific server from the connection pool. It gives the plugin a hint to use a designated server, which can solve issues caused by connection switches and connection state.
SQL hints are standard compliant SQL comments. Because SQL comments are supposed to be ignored by SQL processing systems, they do not interfere with other programs such as the MySQL Server, the MySQL Proxy, or a firewall.
Three SQL hints are supported by the plugin:
The MYSQLND_MS_MASTER_SWITCH hint makes the plugin run a statement
on the master, MYSQLND_MS_SLAVE_SWITCH enforces the use
of the slave, and MYSQLND_MS_MASTER_SWITCH will run a
statement on the same server that was used for the previous statement.
The plugin scans the beginning of a statement for the existence of an SQL hint. SQL hints are only recognized if they appear at the beginning of the statement.
Przykład #1 Plugin config with one slave and one master
{
"myapp": {
"master": {
"master_0": {
"host": "localhost",
"socket": "\/tmp\/mysql.sock"
}
},
"slave": {
"slave_0": {
"host": "192.168.2.27",
"port": "3306"
}
}
}
}
Przykład #2 SQL hints to prevent connection switches
<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (mysqli_connect_errno())
/* Of course, your error handling is nicer... */
die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
/* Connection 1, connection bound SQL user variable, no SELECT thus run on master */
if (!$mysqli->query("SET @myrole='master'")) {
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}
/* Connection 1, run on master because of SQL hint */
if (!($res = $mysqli->query(sprintf("/*%s*/SELECT @myrole AS _role", MYSQLND_MS_LAST_USED_SWITCH)))) {
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
} else {
$row = $res->fetch_assoc();
$res->close();
printf("@myrole = '%s'\n", $row['_role']);
}
$mysqli->close();
?>
Powyższy przykład wyświetli:
@myrole = 'master'
In the above example, using MYSQLND_MS_LAST_USED_SWITCH prevents
session switching from the master to a slave when running the SELECT
statement.
SQL hints can also be used to run SELECT statements on the MySQL master server. This may be desired if the MySQL slave servers are typically behind the master, but you need current data from the cluster.
In version 1.2.0 the concept of a service level has been introduced to address cases when current data is required. Using a service level requires less attention and removes the need of using SQL hints for this use case. Please, find more information below in the service level and consistency section.
Przykład #3 Fighting replication lag
<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli)
/* Of course, your error handling is nicer... */
die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
/* Force use of master, master has always fresh and current data */
if (!$mysqli->query(sprintf("/*%s*/SELECT critical_data FROM important_table", MYSQLND_MS_MASTER_SWITCH))) {
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}
?>
A use case may include the creation of tables on a slave.
If an SQL hint is not given, then the plugin will send CREATE
and INSERT statements to the master. Use the
SQL hint MYSQLND_MS_SLAVE_SWITCH if you want to
run any such statement on a slave, for example, to build temporary
reporting tables.
Przykład #4 Table creation on a slave
<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli)
/* Of course, your error handling is nicer... */
die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
/* Force use of slave */
if (!$mysqli->query(sprintf("/*%s*/CREATE TABLE slave_reporting(id INT)", MYSQLND_MS_SLAVE_SWITCH))) {
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}
/* Continue using this particular slave connection */
if (!$mysqli->query(sprintf("/*%s*/INSERT INTO slave_reporting(id) VALUES (1), (2), (3)", MYSQLND_MS_LAST_USED_SWITCH))) {
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}
/* Don't use MYSQLND_MS_SLAVE_SWITCH which would allow switching to another slave! */
if ($res = $mysqli->query(sprintf("/*%s*/SELECT COUNT(*) AS _num FROM slave_reporting", MYSQLND_MS_LAST_USED_SWITCH))) {
$row = $res->fetch_assoc();
$res->close();
printf("There are %d rows in the table 'slave_reporting'", $row['_num']);
} else {
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}
$mysqli->close();
?>
The SQL hint MYSQLND_MS_LAST_USED forbids switching a
connection, and forces use of the previously used connection.
Transactions
The current version of the plugin is not transaction safe by default, because it is not transaction aware. SQL transactions are units of work to be run on a single server. The plugin does not know when the unit of work starts and when it ends. Therefore, the plugin may decide to switch connections in the middle of a transaction.
You can either use SQL hints to work around this limitation. Alternatively, you can activate transaction API call monitoring. In the latter case you must use API calls only to control transactins, see below.
Przykład #1 Plugin config with one slave and one master
[myapp]
{
"myapp": {
"master": {
"master_0": {
"host": "localhost",
"socket": "\/tmp\/mysql.sock"
}
},
"slave": {
"slave_0": {
"host": "192.168.2.27",
"port": "3306"
}
}
}
}
Przykład #2 Using SQL hints for transactions
<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli)
/* Of course, your error handling is nicer... */
die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
/* Not a SELECT, will use master */
if (!$mysqli->query("START TRANSACTION")) {
/* Please use better error handling in your code */
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
/* Prevent connection switch! */
if (!$mysqli->query(sprintf("/*%s*/INSERT INTO test(id) VALUES (1)", MYSQLND_MS_LAST_USED_SWITCH)))) {
/* Please do proper ROLLBACK in your code, don't just die */
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
if ($res = $mysqli->query(sprintf("/*%s*/SELECT COUNT(*) AS _num FROM test", MYSQLND_MS_LAST_USED_SWITCH)))) {
$row = $res->fetch_assoc();
$res->close();
if ($row['_num'] > 1000) {
if (!$mysqli->query(sprintf("/*%s*/INSERT INTO events(task) VALUES ('cleanup')", MYSQLND_MS_LAST_USED_SWITCH)))) {
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
}
} else {
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
if (!$mysqli->query(sprintf("/*%s*/UPDATE log SET last_update = NOW()", MYSQLND_MS_LAST_USED_SWITCH)))) {
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
if (!$mysqli->query(sprintf("/*%s*/COMMIT", MYSQLND_MS_LAST_USED_SWITCH)))) {
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
$mysqli->close();
?>
Starting with PHP 5.4.0, the mysqlnd library allows the plugin to monitor the status of the autocommit mode, if the mode is set by API calls instead of using SQL statements such as SET AUTOCOMMIT=0. This makes it possible for the plugin to become transaction aware.
If using PHP 5.4.0 or newer, API calls that enable autocommit mode, and when setting the plugin configuration option trx_stickiness=master, the plugin can automatically disable load balancing and connection switches for SQL transactions. In this configuration, the plugin stops load balancing if autocommit is disabled and directs all statements to the master. This prevents connection switches in the middle of a transaction. Once autocommit is re-enabled, the plugin starts to load balance statements again.
Przykład #3 Transaction aware load balancing: trx_stickiness setting
{
"myapp": {
"master": {
"master_0": {
"host": "localhost",
"socket": "\/tmp\/mysql.sock"
}
},
"slave": {
"slave_0": {
"host": "127.0.0.1",
"port": "3306"
}
},
"trx_stickiness": "master"
}
}
Przykład #4 Transaction aware
<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli)
/* Of course, your error handling is nicer... */
die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
/* Disable autocommit, plugin will run all statements on the master */
$mysqli->autocommit(FALSE);
if (!$mysqli->query("INSERT INTO test(id) VALUES (1)")) {
/* Please do proper ROLLBACK in your code, don't just die */
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
if ($res = $mysqli->query("SELECT COUNT(*) AS _num FROM test")) {
$row = $res->fetch_assoc();
$res->close();
if ($row['_num'] > 1000) {
if (!$mysqli->query("INSERT INTO events(task) VALUES ('cleanup')")) {
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
}
} else {
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
if (!$mysqli->query("UPDATE log SET last_update = NOW()")) {
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
if (!$mysqli->commit()) {
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
/* Plugin assumes that the transaction has ended and starts load balancing again */
$mysqli->autocommit(TRUE);
$mysqli->close();
?>
Informacja: Version requirement
The plugin configuration option trx_stickiness=master requires PHP 5.4.0 or newer.
Service level and consistency
Informacja: Version requirement
Service levels have been introduced in PECL mysqlnd_ms version 1.2.0-alpha. mysqlnd_ms_set_qos() is available with PHP 5.4.0 or newer.
Different types of MySQL cluster solutions offer different service and data consistency levels to their users. An asynchronous MySQL replication cluster offers eventual consistency by default. A read executed on an asynchronous slave may return current, stale or no data at all, depending on whether the slave has replayed all changesets from the master or not.
Applications using an MySQL replication cluster need to be designed to work correctly with eventual consistent data. In some cases, however, stale data is not acceptable. In those cases only certain slaves or even only master accesses are allowed to achieve the required quality of service from the cluster.
As of PECL mysqlnd_ms 1.2.0 the plugin is capable of selecting MySQL replication nodes automatically that deliver session consistency or strong consistency. Session consistency means that one client can read its writes. Other clients may or may not see the clients' write. Strong consistency means that all clients will see all writes from the client.
Przykład #1 Session consistency: read your writes
{
"myapp": {
"master": {
"master_0": {
"host": "localhost",
"socket": "\/tmp\/mysql.sock"
}
},
"slave": {
"slave_0": {
"host": "127.0.0.1",
"port": "3306"
}
}
}
}
Przykład #2 Requesting session consistency
<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli)
/* Of course, your error handling is nicer... */
die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
/* read-write splitting: master used */
if (!$mysqli->query("INSERT INTO orders(order_id, item) VALUES (1, 'christmas tree, 1.8m')")) {
/* Please use better error handling in your code */
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
/* Request session consistency: read your writes */
if (!mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_SESSION))
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
/* Plugin picks a node which has the changes, here: master */
if (!$res = $mysqli->query("SELECT item FROM orders WHERE order_id = 1"))
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
var_dump($res->fetch_assoc());
/* Back to eventual consistency: stale data allowed */
if (!mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL))
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
/* Plugin picks any slave, stale data is allowed */
if (!$res = $mysqli->query("SELECT item, price FROM specials"))
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
?>
Service levels can be set in the plugins configuration file and at runtime using mysqlnd_ms_set_qos(). In the example the function is used to enforce session consistency (read your writes) for all future statements until further notice. The SELECT statement on the orders table is run on the master to ensure the previous write can be seen by the client. Read-write splitting logic has been adapted to fulfill the service level.
After the application has read its changes from the orders table it returns to the default service level, which is eventual consistency. Eventual consistency puts no restrictions on choosing a node for statement execution. Thus, the SELECT statement on the specials table is executed on a slave.
The new functionality supersedes the use of SQL hints and the master_on_write configuration option. In many cases mysqlnd_ms_set_qos() is easier to use, more powerful improves portability.
Przykład #3 Maximum age/slave lag
{
"myapp": {
"master": {
"master_0": {
"host": "localhost",
"socket": "\/tmp\/mysql.sock"
}
},
"slave": {
"slave_0": {
"host": "127.0.0.1",
"port": "3306"
}
},
"failover" : "master"
}
}
Przykład #4 Limiting slave lag
<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli)
/* Of course, your error handling is nicer... */
die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
/* Read from slaves lagging no more than four seconds */
$ret = mysqlnd_ms_set_qos($mysqli,
MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL,
MYSQLND_MS_QOS_OPTION_AGE, 4);
if (!$ret)
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
/* Plugin picks any slave, which may or may not have the changes */
if (!$res = $mysqli->query("SELECT item, price FROM daytrade"))
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
/* Back to default: use of all slaves and masters permitted */
if (!mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL))
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
?>
The eventual consistency service level can be used with an optional parameter to set a maximum slave lag for choosing slaves. If set, the plugin checks SHOW SLAVE STATUS for all configured slaves. In case of the example, only slaves for which Slave_IO_Running=Yes, Slave_SQL_Running=Yes and Seconds_Behind_Master <= 4 is true are considered for executing the statement SELECT item, price FROM daytrade.
Checking SHOW SLAVE STATUS is done transparently from an applications perspective. Errors, if any, are reported as warnings. No error will be set on the connection handle. Even if all SHOW SLAVE STATUS SQL statements executed by the plugin fail, the execution of the users statement is not stopped, given that master fail over is enabled. Thus, no application changes are required.
Informacja: Expensive and slow operation
Checking SHOW SLAVE STATUS for all slaves adds overhead to the application. It is an expensive and slow background operation. Try to minimize the use of it. Unfortunately, a MySQL replication cluster does not give clients the possibility to request a list of candidates from a central instance. Thus, a more efficient way of checking the slaves lag is not available.
Please, note the limitations and properties of SHOW SLAVE STATUS as explained in the MySQL reference manual.
To prevent mysqlnd_ms from emitting a warning if no slaves can be found that lag no more than the defined number of seconds behind the master, it is necessary to enable master fail over in the plugins configuration file. If no slaves can be found and fail over is turned on, the plugin picks a master for executing the statement.
If no slave can be found and fail over is turned off, the plugin emits a warning, it does not execute the statement and it sets an error on the connection.
Przykład #5 Fail over not set
{
"myapp": {
"master": {
"master_0": {
"host": "localhost",
"socket": "\/tmp\/mysql.sock"
}
},
"slave": {
"slave_0": {
"host": "127.0.0.1",
"port": "3306"
}
}
}
}
Przykład #6 No slave within time limit
<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli)
/* Of course, your error handling is nicer... */
die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
/* Read from slaves lagging no more than four seconds */
$ret = mysqlnd_ms_set_qos($mysqli,
MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL,
MYSQLND_MS_QOS_OPTION_AGE, 4);
if (!$ret)
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
/* Plugin picks any slave, which may or may not have the changes */
if (!$res = $mysqli->query("SELECT item, price FROM daytrade"))
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
/* Back to default: use of all slaves and masters permitted */
if (!mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL))
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
?>
Powyższy przykład wyświetli:
PHP Warning: mysqli::query(): (mysqlnd_ms) Couldn't find the appropriate slave connection. 0 slaves to choose from. Something is wrong in %s on line %d PHP Warning: mysqli::query(): (mysqlnd_ms) No connection selected by the last filter in %s on line %d [2000] (mysqlnd_ms) No connection selected by the last filter
Informacja: Fail over logic is work in progress
The details of the fail over logic may change in future versions.
Global transaction IDs
Informacja: Version requirement
A client-side global transaction ID injection has been introduced in mysqlnd_ms version 1.2.0-alpha. The feature is not required for synchronous clusters, such as MySQL Cluster. Use it with asynchronous clusters such as classical MySQL replication.
As of MySQL 5.6.5-m8 the MySQL server features built-in global transaction identifiers. The MySQL built-in global transaction ID feature is supported by PECL/mysqlnd_ms 1.3.0-alpha or later.
PECL/mysqlnd_ms can either use its own global transaction ID emulation or the global transaction ID feature built-in to MySQL 5.6.5-m8 or later. From a developer perspective the client-side and server-side approach offer the same features with regards to service levels provided by PECL/mysqlnd_ms. Their differences are discussed in the concepts section.
The quickstart first demonstrates the use of the client-side global transaction ID emulation built-in to PECL/mysqlnd_ms before its show how to use the server-side counterpart. The order ensures that the underlying idea is discussed first.
Idea and client-side emulation
In its most basic form a global transaction ID (GTID) is a counter in a table on the master. The counter is incremented whenever a transaction is comitted on the master. Slaves replicate the table. The counter serves two puposes. In case of a master failure, it helps the database administrator to identify the most recent slave for promoting it to the new master. The most recent slave is the one with the highest counter value. Applications can use the global transaction ID to search for slaves which have replicated a certain write (identified by a global transaction ID) already.
PECL/mysqlnd_ms can inject SQL for every comitted transaction to increment a GTID counter. The so created GTID is accessible by the application to identify an applications write operation. This enables the plugin to deliver session consistency (read your writes) service level by not only quering masters but also slaves which have replicated the change already. Read load is taken away from the master.
Client-side global transaction ID emulation has some limitations. Please, read the concepts section carefully to fully understand the principles and ideas behind it, before using in production environments. The background knowledge is not required to continue with the quickstart.
First, create a counter table on your master server and insert a record into it. The plugin does not assist creating the table. Database administrators must make sure it exists. Depending on the error reporting mode, the plugin will silently ignore the lack of the table or bail out.
Przykład #1 Create counter table on master
CREATE TABLE `trx` ( `trx_id` int(11) DEFAULT NULL, `last_update` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP ) ENGINE=InnoDB DEFAULT CHARSET=latin1 INSERT INTO `trx`(`trx_id`) VALUES (1);
In the plugins configuration file set the SQL to update the global transaction ID table using on_commit from the global_transaction_id_injection section. Make sure the table name used for the UPDATE statement is fully qualified. In the example, test.trx is used to refer to table trx in the schema (database) test. Use the table that was created in the previous step. It is important to set the fully qualified table name because the connection on which the injection is done may use a different default database. Make sure the user that opens the connection is allowed to execute the UPDATE.
Enable reporting of errors that may occur when mysqlnd_ms does global transaction ID injection.
Przykład #2 Plugin config: SQL for client-side GTID injection
{
"myapp": {
"master": {
"master_0": {
"host": "localhost",
"socket": "\/tmp\/mysql.sock"
}
},
"slave": {
"slave_0": {
"host": "127.0.0.1",
"port": "3306"
}
},
"global_transaction_id_injection":{
"on_commit":"UPDATE test.trx SET trx_id = trx_id + 1",
"report_error":true
}
}
}
Przykład #3 Transparent global transaction ID injection
<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli)
/* Of course, your error handling is nicer... */
die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
/* auto commit mode, transaction on master, GTID must be incremented */
if (!$mysqli->query("DROP TABLE IF EXISTS test"))
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
/* auto commit mode, transaction on master, GTID must be incremented */
if (!$mysqli->query("CREATE TABLE test(id INT)"))
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
/* auto commit mode, transaction on master, GTID must be incremented */
if (!$mysqli->query("INSERT INTO test(id) VALUES (1)"))
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
/* auto commit mode, read on slave, no increment */
if (!($res = $mysqli->query("SELECT id FROM test")))
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
var_dump($res->fetch_assoc());
?>
Powyższy przykład wyświetli:
array(1) {
["id"]=>
string(1) "1"
}
The example runs three statements in auto commit mode on the master, causing three transactions on the master. For every such statement, the plugin will inject the configured UPDATE transparently before executing the users SQL statement. When the script ends the global transaction ID counter on the master has been incremented by three.
The fourth SQL statement executed in the example, a SELECT, does not trigger an increment. Only transactions (writes) executed on a master shall increment the GTID counter.
Informacja: SQL for global transaction ID: efficient solution wanted!
The SQL used for the client-side global transaction ID emulation is inefficient. It is optimized for clearity not for performance. Do not use it for production environments. Please, help finding an efficient solution for inclusion in the manual. We appreciate your input.
Przykład #4 Plugin config: SQL for fetching GTID
{
"myapp": {
"master": {
"master_0": {
"host": "localhost",
"socket": "\/tmp\/mysql.sock"
}
},
"slave": {
"slave_0": {
"host": "127.0.0.1",
"port": "3306"
}
},
"global_transaction_id_injection":{
"on_commit":"UPDATE test.trx SET trx_id = trx_id + 1",
"fetch_last_gtid" : "SELECT MAX(trx_id) FROM test.trx",
"report_error":true
}
}
}
Przykład #5 Obtaining GTID after injection
<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli)
/* Of course, your error handling is nicer... */
die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
/* auto commit mode, transaction on master, GTID must be incremented */
if (!$mysqli->query("DROP TABLE IF EXISTS test"))
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
printf("GTID after transaction %s\n", mysqlnd_ms_get_last_gtid($mysqli));
/* auto commit mode, transaction on master, GTID must be incremented */
if (!$mysqli->query("CREATE TABLE test(id INT)"))
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
printf("GTID after transaction %s\n", mysqlnd_ms_get_last_gtid($mysqli));
?>
Powyższy przykład wyświetli:
GTID after transaction 7 GTID after transaction 8
Applications can ask PECL mysqlnd_ms for a global transaction ID which belongs to the last write operation performed by the application. The function mysqlnd_ms_get_last_gtid() returns the GTID obtained when executing the SQL statement from the fetch_last_gtid entry of the global_transaction_id_injection section from the plugins configuration file. The function may be called after the GTID has been incremented.
Applications are adviced not to run the SQL statement themselves as this bares the risk of accidently causing an implicit GTID increment. Also, if the function is used, it is easy to migrate an application from one SQL statement for fetching a transaction ID to another, for example, if any MySQL server ever features built-in global transaction ID support.
The quickstart shows a SQL statement which will return a GTID equal or greater to that created for the previous statement. It is exactly the GTID created for the previous statement if no other clients have incremented the GTID in the time span between the statement execution and the SELECT to fetch the GTID. Otherwise, it is greater.
Przykład #6 Plugin config: Checking for a certain GTID
{
"myapp": {
"master": {
"master_0": {
"host": "localhost",
"socket": "\/tmp\/mysql.sock"
}
},
"slave": {
"slave_0": {
"host": "127.0.0.1",
"port": "3306"
}
},
"global_transaction_id_injection":{
"on_commit":"UPDATE test.trx SET trx_id = trx_id + 1",
"fetch_last_gtid" : "SELECT MAX(trx_id) FROM test.trx",
"check_for_gtid" : "SELECT trx_id FROM test.trx WHERE trx_id >= #GTID",
"report_error":true
}
}
}
Przykład #7 Session consistency service level and GTID combined
<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli)
/* Of course, your error handling is nicer... */
die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
/* auto commit mode, transaction on master, GTID must be incremented */
if (!$mysqli->query("DROP TABLE IF EXISTS test") ||
!$mysqli->query("CREATE TABLE test(id INT)") ||
!$mysqli->query("INSERT INTO test(id) VALUES (1)"))
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
/* GTID as an identifier for the last write */
$gtid = mysqlnd_ms_get_last_gtid($mysqli);
/* Session consistency (read your writes): try to read from slaves not only master */
if (false == mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_SESSION, MYSQLND_MS_QOS_OPTION_GTID, $gtid)) {
die(sprintf("[006] [%d] %s\n", $mysqli->errno, $mysqli->error));
}
/* Either run on master or a slave which has replicated the INSERT */
if (!($res = $mysqli->query("SELECT id FROM test"))) {
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
var_dump($res->fetch_assoc());
?>
A GTID returned from mysqlnd_ms_get_last_gtid() can be used as an option for the session consistency service level. Session consistency delivers read your writes. Session consistency can be requested by calling mysqlnd_ms_set_qos(). In the example, the plugin will execute the SELECT statement either on the master or on a slave which has replicated the previous INSERT already.
PECL mysqlnd_ms will transparently check every configured slave if it has replicated the INSERT by checking the slaves GTID table. The check is done running the SQL set with the check_for_gtid option from the global_transaction_id_injection section of the plugins configuration file. Please note, that this is a slow and expensive procedure. Applications should try to use it sparsely and only if read load on the master becomes to high otherwise.
Use of the server-side global transaction ID feature
Starting with MySQL 5.6.5-m8 the MySQL Replication system features server-side global transaction IDs. Transaction identifiers are automatically generated and maintained by the server. Users do not need to take care of maintaining them. There is no need to setup any tables in advance, or for setting on_commit. A client-side emulation is no longer needed.
Clients can continue to use global transaction identifier to achieve session consistency when reading from MySQL Replication slaves. The algorithm works as described above. Different SQL statements must be configured for fetch_last_gtid and check_for_gtid. The statements are given below. Please note, MySQL 5.6.5-m8 is a development version. Details of the server implementation may change in the future and require adoption of the SQL statements shown.
Using the following configuration any of the above described functionality can be used together with the server-side global transaction ID feature. mysqlnd_ms_get_last_gtid() and mysqlnd_ms_set_qos() continue to work as described above. The only difference is that the server does not use a simple sequence number but a string containing of a server identifier and a sequence number. Thus, users cannot easily derive an order from GTIDs returned by mysqlnd_ms_get_last_gtid().
Przykład #8 Plugin config: using MySQL 5.6.5-m8 built-in GTID feature
{
"myapp": {
"master": {
"master_0": {
"host": "localhost",
"socket": "\/tmp\/mysql.sock"
}
},
"slave": {
"slave_0": {
"host": "127.0.0.1",
"port": "3306"
}
},
"global_transaction_id_injection":{
"fetch_last_gtid" : "SELECT @@GLOBAL.GTID_DONE AS trx_id FROM DUAL",
"check_for_gtid" : "SELECT GTID_SUBSET('#GTID', @@GLOBAL.GTID_DONE) AS trx_id FROM DUAL",
"report_error":true
}
}
}
Cache integration
Informacja: Version requirement and dependencies
Cache integration is available as of PECL/mysqlnd_ms 1.3.0-beta (under development). PECL/mysqlnd_qc 1.1.0 (under development) or newer is used as a cache. Both plugins must be installed. PECL/mysqlnd_ms must be compiled to support the cache feature. Use of PHP 5.4.0 or newer is mandatory.
Databases clusters can deliver different levels of consistency. As of PECL/mysqlnd_ms 1.2.0 it is possible to advice the plugin to consider only cluster nodes that can deliver the consistency level requested. For example, if using asynchronous MySQL Replication with its cluster-wide eventual consistency, it is possible to request session consistency (read your writes) at any time using mysqlnd_ms_set_quos(). Please, see also the service level and consistency introduction.
Przykład #1 Recap: quality of service to request read your writes
/* Request session consistency: read your writes */
if (!mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_SESSION))
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
Assuming PECL/mysqlnd has been explicitly told to deliver no consistency level higher than eventual consistency, it is possible to replace a database node read access with a client-side cache using time-to-live (TTL) as its invalidation strategy. Both the database node and the cache may or may not serve current data as this is what eventual consistency defines.
Replacing a database node read access with a local cache access can improve overall performance and lower the database load. If the cache entry is every reused by other clients than the one creating the cache entry, a database access is saved and thus database load is lowered. Furthermore, system performance can become better if computation and delivery of a database query is slower than a local cache access.
Przykład #2 Plugin config: no special entries for caching
{
"myapp": {
"master": {
"master_0": {
"host": "localhost",
"socket": "\/tmp\/mysql.sock"
}
},
"slave": {
"slave_0": {
"host": "127.0.0.1",
"port": "3306"
}
},
}
}
Przykład #3 Caching a slave request
<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli)
/* Of course, your error handling is nicer... */
die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
if (!$mysqli->query("DROP TABLE IF EXISTS test") ||
!$mysqli->query("CREATE TABLE test(id INT)") ||
!$mysqli->query("INSERT INTO test(id) VALUES (1)"))
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
/* Explicitly allow eventual consistency and caching (TTL <= 60 seconds) */
if (false == mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL, MYSQLND_MS_QOS_OPTION_CACHE, 60)) {
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
/* To make this example work, we must wait for a slave to catch up. Brute force style. */
$attempts = 0;
do {
/* check if slave has the table */
if ($res = $mysqli->query("SELECT id FROM test")) {
break;
} else if ($mysqli->errno) {
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
/* wait for slave to catch up */
usleep(200000);
} while ($attempts++ < 10);
/* Query has been run on a slave, result is in the cache */
assert($res);
var_dump($res->fetch_assoc());
/* Served from cache */
$res = $mysqli->query("SELECT id FROM test");
?>
The example shows how to use the cache feature. First, you have to set the quality of service to eventual consistency and explicitly allow for caching. This is done by calling mysqlnd_ms_set_qos(). Then, the result set of every read-only statement is cached for upto that many seconds as allowed with mysqlnd_ms_set_qos().
The actual TTL is lower or equal to the value set with mysqlnd_ms_set_qos(). The value passed to the function sets the maximum age (seconds) of the data delivered. To calculate the actual TTL value the replication lag on a slave is checked and substracted from the given value. If, for example, the maximum age is set to 60 seconds and the slave reports a lag of 10 seconds the resulting TTL is 50 seconds. The TTL is calculated individually for every cached query.
Przykład #4 Read your writes and caching combined
<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli)
/* Of course, your error handling is nicer... */
die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
if (!$mysqli->query("DROP TABLE IF EXISTS test") ||
!$mysqli->query("CREATE TABLE test(id INT)") ||
!$mysqli->query("INSERT INTO test(id) VALUES (1)"))
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
/* Explicitly allow eventual consistency and caching (TTL <= 60 seconds) */
if (false == mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL, MYSQLND_MS_QOS_OPTION_CACHE, 60)) {
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
/* To make this example work, we must wait for a slave to catch up. Brute force style. */
$attempts = 0;
do {
/* check if slave has the table */
if ($res = $mysqli->query("SELECT id FROM test")) {
break;
} else if ($mysqli->errno) {
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
/* wait for slave to catch up */
usleep(200000);
} while ($attempts++ < 10);
assert($res);
/* Query has been run on a slave, result is in the cache */
var_dump($res->fetch_assoc());
/* Served from cache */
if (!($res = $mysqli->query("SELECT id FROM test")))
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
var_dump($res->fetch_assoc());
/* Update on master */
if (!$mysqli->query("UPDATE test SET id = 2"))
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
/* Read your writes */
if (false == mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_SESSION)) {
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
}
/* Fetch latest data */
if (!($res = $mysqli->query("SELECT id FROM test")))
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
var_dump($res->fetch_assoc());
?>
The quality of service can be changed at any time to avoid further cache usage. If needed, you can switch to read your writes (session consistency). In that case, the cache will not be used and fresh data is read.
Concepts
Spis treści
- Architecture
- Connection pooling and switching
- Transaction handling
- Error handling
- Failover
- Load balancing
- Read-write splitting
- Filter
- Service level and consistency
- Global transaction IDs
- Cache integration
- Supported clusters
This explains the architecture and related concepts for this plugin, and describes the impact that MySQL replication and this plugin have on developmental tasks while using a database cluster. Reading and understanding these concepts is required, in order to use this plugin with success.
Architecture
The mysqlnd replication and load balancing plugin is implemented as a PHP extension. It is written in C and operates under the hood of PHP. During the startup of the PHP interpreter, in the module init phase of the PHP engine, it gets registered as a mysqlnd plugin to replace selected mysqlnd C methods.
At PHP runtime, it inspects queries sent from mysqlnd (PHP) to the MySQL server. If a query is recognized as read-only, it will be sent to one of the configured slave servers. Statements are considered read-only if they either start with SELECT, the SQL hint /*ms=slave*/ or a slave had been chosen for running the previous query, and the query started with the SQL hint /*ms=last_used*/. In all other cases, the query will be sent to the MySQL replication master server.
For better portability, applications should use the
MYSQLND_MS_MASTER_SWITCH,
MYSQLND_MS_SLAVE_SWITCH, and
MYSQLND_MS_LAST_USED_SWITCH
predefined mysqlnd_ms constants,
instead of their literal values, such as /*ms=slave*/.
The plugin handles the opening and closing of database connections to both master and slave servers. From an application point of view, there continues to be only one connection handle. However, internally, this one public connection handle represents a pool of network connections that are managed by the plugin. The plugin proxies queries to the master server, and to the slaves using multiple connections.
Database connections have a state consisting of, for example, transaction status, transaction settings, character set settings, and temporary tables. The plugin will try to maintain the same state among all internal connections, whenever this can be done in an automatic and transparent way. In cases where it is not easily possible to maintain state among all connections, such as when using BEGIN TRANSACTION, the plugin leaves it to the user to handle.
Connection pooling and switching
The replication and load balancing plugin changes the semantics of a PHP MySQL connection handle. The existing API of the PHP MySQL extensions (mysqli, mysql, and PDO_MYSQL) are not changed in a way that functions are added or removed. But their behaviour changes when using the plugin. Existing applications do not need to be adapted to a new API, but they may need to be modified because of the behaviour changes.
The plugin breaks the one-by-one relationship between a mysqli, mysql, and PDO_MYSQL connection handle and a MySQL network connection. And a mysqli, mysql, and PDO_MYSQL connection handle represents a local pool of connections to the configured MySQL replication master and MySQL replication slave servers. The plugin redirects queries to the master and slave servers. At some point in time one and the same PHP connection handle may point to the MySQL master server. Later on, it may point to one of the slave servers or still the master. Manipulating and replacing the network connection referenced by a PHP MySQL connection handle is not a transparent operation.
Every MySQL connection has a state. The state of the connections in the connection pool of the plugin can differ. Whenever the plugin switches from one wire connection to another, the current state of the user connection may change. The applications must be aware of this.
The following list shows what the connection state consists of. The list may not be complete.
- Transaction status
- Temporary tables
- Table locks
- Session system variables and session user variables
- The current database set using USE and other state chaining SQL commands
- Prepared statements
- HANDLER variables
- Locks acquired with GET_LOCK()
Connection switches happen right before queries are executed. The plugin does not switch the current connection until the next statement is executed.
Informacja: Replication issues
See also the MySQL reference manual chapter about » replication features and related issues. Some restrictions may not be related to the PHP plugin, but are properties of the MySQL replication system.
Broadcasted messages
The plugins philosophy is to align the state of connections in the pool only if the state is under full control of the plugin, or if it is necessary for security reasons. Just a few actions that change the state of the connection fall into this category.
The following is a list of connection client library calls that change state, and are broadcasted to all open connections in the connection pool.
If any of the listed calls below are to be executed, the plugin loops over all open master and slave connections. The loop continues until all servers have been contacted, and the loop does not break if a server indicates a failure. If possible, the failure will propagate to the called user API function, which may be detected depending on which underlying library function was triggered.
| Library call | Notes | Version |
|---|---|---|
| change_user() | Called by the mysqli_change_user() user API call. Also triggered upon reuse of a persistent mysqli connection. | Since 1.0.0. |
| select_db | Called by the following user API calls: mysql_select_db(), mysql_list_tables(), mysql_db_query(), mysql_list_fields(), mysqli_select_db(). Note, that SQL USE is not monitored. | Since 1.0.0. |
| set_charset() | Called by the following user API calls: mysql_set_charset(). mysqli_set_charset(). Note, that SQL SET NAMES is not monitored. | Since 1.0.0. |
| set_server_option() | Called by the following user API calls: mysqli_multi_query(), mysqli_real_query(), mysqli_query(), mysql_query(). | Since 1.0.0. |
| set_client_option() | Called by the following user API calls: mysqli_options(), mysqli_ssl_set(), mysqli_connect(), mysql_connect(), mysql_pconnect(). | Since 1.0.0. |
| set_autocommit() | Called by the following user API calls: mysqli_autocommit(), PDO::setAttribute(PDO::ATTR_AUTOCOMMIT). | Since 1.0.0. PHP >= 5.4.0. |
| ssl_set() | Called by the following user API calls: mysqli_ssl_set(). | Since 1.1.0. |
Broadcasting and lazy connections
The plugin does not proxy or "remember" all settings to apply them on connections opened in the future. This is important to remember, if using lazy connections. Lazy connections are connections which are not opened before the client sends the first connection. Use of lazy connections is the default plugin action.
The following connection library calls each changed state, and their execution is recorded for later use when lazy connections are opened. This helps ensure that the connection state of all connections in the connection pool are comparable.
| Library call | Notes | Version |
|---|---|---|
| change_user() | User, password and database recorded for future use. | Since 1.1.0. |
| select_db | Database recorded for future use. | Since 1.1.0. |
| set_charset() | Calls set_client_option(MYSQL_SET_CHARSET_NAME, charset) on lazy connection to ensure charset will be used upon opening the lazy connection. | Since 1.1.0. |
| set_autocommit() | Adds SET AUTOCOMMIT=0|1 to the list of init commands of a lazy connection using set_client_option(MYSQL_INIT_COMMAND, "SET AUTOCOMMIT=...%quot;). | Since 1.1.0. PHP >= 5.4.0. |
Connection state
The connection state is not only changed by API calls. Thus, even if PECL mysqlnd_ms monitors all API calls, the application must still be aware. Ultimately, it is the applications responsibility to maintain the connection state, if needed.
Transaction handling
Transaction handling is fundamentally changed. An SQL transaction is a unit of work that is run on one database server. The unit of work consists of one or more SQL statements.
By default the plugin is not aware of SQL transactions. The plugin may switch connections for load balancing at any point in time. Connection switches may happen in the middle of a transaction. This is against the nature of an SQL transaction. By default, the plugin is not transaction safe.
At the time of writing, applications using SQL transactions together with the plugin must use SQL hints to disable connection switches in the middle of a SQL transaction. See also the examples section.
Informacja: Added features as of PHP 5.4.0
The mysqlnd library allows this plugin to subclass the library C API call set_autocommit(), to detect the status of autocommit mode.
Added support for trx_stickiness=master
The PHP MySQL extensions either issue a query (such as SET AUTOCOMMIT=0|1), or use the mysqlnd library call set_autcommit() to control the autocommit setting. If an extension makes use of set_autocommit(), the plugin can be made transaction aware. Transaction awareness cannot be achieved if using SQL to set the autocommit mode. The library function set_autocommit() is called by the mysqli_autocommit() and PDO::setAttribute(PDO::ATTR_AUTOCOMMIT) user API calls.
The plugin configuration option trx_stickiness=master can be used to make the plugin transactional aware. In this mode, the plugin stops load balancing if autocommit becomes disabled, and directs all statements to the master until autocommit gets enabled.
Error handling
Applications using PECL/mysqlnd_ms should implement proper error handling for all user API calls. And because the plugin changes the semantics of a connection handle, API calls may return unexpected errors. If using the plugin on a connection handle that no longer represents an individual network connection, but a connection pool, an error code and error message will be set on the connection handle whenever an error occurs on any of the network connections behind.
If using lazy connections, which is the default, connections are not opened until they are needed for query execution. Therefore, an API call for a statement execution may return a connection error. In the example below, an error is provoked when trying to run a statement on a slave. Opening a slave connection fails because the plugin configuration file lists an invalid host name for the slave.
Przykład #1 Provoking a connection error
{
"myapp": {
"master": {
"master_0": {
"host": "localhost",
"socket": "\/tmp\/mysql.sock"
}
},
"slave": {
"slave_0": {
"host": "invalid_host_name",
}
},
"lazy_connections": 1
}
}
The explicit activation of lazy connections is for demonstration purpose only.
Przykład #2 Connection error on query execution
<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (mysqli_connect_errno())
/* Of course, your error handling is nicer... */
die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
/* Connection 1, connection bound SQL user variable, no SELECT thus run on master */
if (!$mysqli->query("SET @myrole='master'")) {
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}
/* Connection 2, run on slave because SELECT, provoke connection error */
if (!($res = $mysqli->query("SELECT @myrole AS _role"))) {
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
} else {
$row = $res->fetch_assoc();
$res->close();
printf("@myrole = '%s'\n", $row['_role']);
}
$mysqli->close();
?>
Powyższy przykład wyświetli coś podobnego do:
PHP Warning: mysqli::query(): php_network_getaddresses: getaddrinfo failed: Name or service not known in %s on line %d PHP Warning: mysqli::query(): [2002] php_network_getaddresses: getaddrinfo failed: Name or service not known (trying to connect via tcp://invalid_host_name:3306) in %s on line %d [2002] php_network_getaddresses: getaddrinfo failed: Name or service not known
Applications are expected to handle possible connection errors by implementing proper error handling.
Depending on the use case, applications may want to handle connection errors differently from other errors. Typical connection errors are 2002 (CR_CONNECTION_ERROR) - Can't connect to local MySQL server through socket '%s' (%d), 2003 (CR_CONN_HOST_ERROR) - Can't connect to MySQL server on '%s' (%d) and 2005 (CR_UNKNOWN_HOST) - Unknown MySQL server host '%s' (%d). For example, the application may test for the error codes and manually perform a fail over. The plugins philosophy is not to offer automatic fail over, beyond master fail over, because fail over is not a transparent operation.
Przykład #3 Provoking a connection error
{
"myapp": {
"master": {
"master_0": {
"host": "localhost"
}
},
"slave": {
"slave_0": {
"host": "invalid_host_name"
},
"slave_1": {
"host": "192.168.78.136"
}
},
"lazy_connections": 1,
"filters": {
"roundrobin": [
]
}
}
}
Explicitly activating lazy connections is done for demonstration purposes, as is round robin load balancing as opposed to the default random once type.
Przykład #4 Most basic failover
<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
if (mysqli_connect_errno())
/* Of course, your error handling is nicer... */
die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
/* Connection 1, connection bound SQL user variable, no SELECT thus run on master */
if (!$mysqli->query("SET @myrole='master'")) {
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}
/* Connection 2, first slave */
$res = $mysqli->query("SELECT VERSION() AS _version");
/* Hackish manual fail over */
if (2002 == $mysqli->errno || 2003 == $mysqli->errno || 2004 == $mysqli->errno) {
/* Connection 3, first slave connection failed, trying next slave */
$res = $mysqli->query("SELECT VERSION() AS _version");
}
if (!$res) {
printf("ERROR, [%d] '%s'\n", $mysqli->errno, $mysqli->error);
} else {
/* Error messages are taken from connection 3, thus no error */
printf("SUCCESS, [%d] '%s'\n", $mysqli->errno, $mysqli->error);
$row = $res->fetch_assoc();
$res->close();
printf("version = %s\n", $row['_version']);
}
$mysqli->close();
?>
Powyższy przykład wyświetli coś podobnego do:
[1045] Access denied for user 'username'@'localhost' (using password: YES) PHP Warning: mysqli::query(): php_network_getaddresses: getaddrinfo failed: Name or service not known in %s on line %d PHP Warning: mysqli::query(): [2002] php_network_getaddresses: getaddrinfo failed: Name or service not known (trying to connect via tcp://invalid_host_name:3306) in %s on line %d SUCCESS, [0] '' version = 5.6.2-m5-log
In some cases, it may not be easily possible to retrieve all errors that occur on all network connections through a connection handle. For example, let's assume a connection handle represents a pool of three open connections. One connection to a master and two connections to the slaves. The application changes the current database using the user API call mysqli_select_db(), which then calls the mysqlnd library function to change the schemata. mysqlnd_ms monitors the function, and tries to change the current database on all connections to harmonize their state. Now, assume the master succeeds in changing the database, and both slaves fail. Upon the initial error from the first slave, the plugin will set an appropriate error on the connection handle. The same is done when the second slave fails to change the database. The error message from the first slave is lost.
Such cases can be debugged by either checking for errors of the type E_WARNING (see above) or, if no other option, investigation of the mysqlnd_ms debug and trace log.
Failover
Connection failover handling is left to the user. The application is responsible for checking return values of the database functions it calls and reacting to possible errors. If, for example, the plugin recognizes a query as a read-only query to be sent to the slave servers, and the slave server selected by the plugin is not available, the plugin will raise an error after not executing the statement.
It is up to the application to handle the error and, if required, re-issue the query to trigger the selection of another slave server for statement execution. The plugin will make no attempts to failover automatically, because the plugin cannot ensure that an automatic failover will not change the state of the connection. For example, the application may have issued a query which depends on SQL user variables which are bound to a specific connection. Such a query might return incorrect results if the plugin would switch the connection implicitly as part of automatic failover. To ensure correct results, the application must take care of the failover, and rebuild the required connection state. Therefore, by default, no automatic failover is performed by the plugin.
A user that does not change the connection state after opening a connection may activate automatic master failover.
The failover policy is configured in the plugins configuration file, by using the failover configuration directive.
A basic manual failover example is provided within the error handling section.
Please note, if using a primary copy cluster, such as MySQL Replication, it is difficult to do connection failover in case of a master failure. At any there there is only one master in the cluster for a given dataset. The master is a single point of failure. If the master fails, clients have no target to fail over write requests. In case of a master outage the database administrator must take care of the situation and eventually update the client configurations, if need be.
Load balancing
Four load balancing strategies are supported to distribute statements over the configured MySQL slave servers:
- random
-
Chooses a random server whenever a statement is executed.
- random once (default)
-
Chooses a random server after the first statement is executed, and uses the decision for the rest of the PHP request.
It is the default, and the lowest impact on the connection state.
- round robin
-
Iterates over the list of configured servers.
- user-defined via callback
-
Is used to implement any other strategy.
The load balancing policy is configured in the plugins configuration file using the random, roundrobin, and user filters.
Read-write splitting
The plugin executes read-only statements on the configured MySQL slaves, and
all other queries on the MySQL master. Statements are
considered read-only if they either start with SELECT,
the SQL hint /*ms=slave*/, or if a slave had been chosen for
running the previous query and the query starts with the SQL hint
/*ms=last_used*/. In all other cases, the query will
be sent to the MySQL replication master server. It is recommended to
use the constants MYSQLND_MS_SLAVE_SWITCH,
MYSQLND_MS_MASTER_SWITCH and MYSQLND_MS_LAST_USED_SWITCH
instead of /*ms=slave*/. See also the
list of mysqlnd_ms constants.
SQL hints are a special kind of standard compliant SQL comments. The plugin does check every statement for certain SQL hints. The SQL hints are described within the mysqlnd_ms constants documentation, constants that are exported by the extension. Other systems involved with the statement processing, such as the MySQL server, SQL firewalls, and SQL proxies, are unaffected by the SQL hints, because those systems are designed to ignore SQL comments.
The built-in read-write splitter can be replaced by a user-defined filter, see also the user filter documentation.
A user-defined read-write splitter can request the built-in logic to send a statement to a specific location, by invoking mysqlnd_ms_is_select().
Informacja:
The built-in read-write splitter is not aware of multi-statements. Multi-statements are seen as one statement. The splitter will check the beginning of the statement to decide where to run the statement. If, for example, a multi-statement begins with SELECT 1 FROM DUAL; INSERT INTO test(id) VALUES (1); ... the plugin will run it on a slave although the statement is not read-only.
Filter
Informacja: Version requirement
Filters exist as of mysqlnd_ms version 1.1.0-beta.
filters. PHP applications that implement a MySQL replication cluster must first identify a group of servers in the cluster which could execute a statement before the statement is executed by one of the candidates. In other words: a defined list of servers must be filtered until only one server is available.
The process of filtering may include using one or more filters, and filters can be chained. And they are executed in the order they are defined in the plugins configuration file.
Informacja: Explanation: comparing filter chaining to pipes
The concept of chained filters can be compared to using pipes to connect command line utilities on an operating system command shell. For example, an input stream is passed to a processor, filtered, and then transferred to be output. Then, the output is passed as input to the next command, which is connected to the previous using the pipe operator.
Available filters:
- Load balancing filters: random and roundrobin.
- Selection filter: user, user_multi, quality_of_service.
The random filter implements the 'random' and 'random once' load balancing policies. The 'round robin' load balancing can be configured through the roundrobin filter. Setting a 'user defined callback' for server selection is possible with the user filter. The quality_of_service filter finds cluster nodes capable of delivering a certain service, for example, read-your-writes or, not lagging more seconds behind the master than allowed.
Filters can accept parameters to change their behaviour. The random filter accepts an optional sticky parameter. If set to true, the filter changes load balancing from random to random once. Random picks a random server every time a statement is to be executed. Random once picks a random server when the first statement is to be executed and uses the same server for the rest of the PHP request.
One of the biggest strength of the filter concept is the possibility to chain filters. This strength does not become immediately visible because tje random, roundrobin and user filters are supposed to output no more than one server. If a filter reduces the list of candidates for running a statement to only one server, it makes little sense to use that one server as input for another filter for further reduction of the list of candidates.
An example filter sequence that will fail:
- Statement to be executed: SELECT 1 FROM DUAL. Passed to all filters.
- All configured nodes are passed as input to the first filter. Master nodes: master_0. Slave nodes:slave_0, slave_1
- Filter: random, argument sticky=1. Picks a random slave once to be used for the rest of the PHP request. Output: slave_0.
- Output of slave_0 and the statement to be executed is passed as input to the next filter. Here: roundrobin, server list passed to filter is: slave_0.
- Filter: roundrobin. Server list consists of one server only, round robin will always return the same server.
A second type of filter exists: multi filter. A multi filter emits zero, one or multiple servers after processing. The quality_of_service filter is an example. If the service quality requested sets an upper limit for the slave lag and more than one slave is lagging behind less than the allowed number of seconds, the filter returns more than one cluster node. A multi filter must be followed by other to further reduce the list of candidates for statement execution until a candidate is found.
A filter sequence with the quality_of_service multi filter followed by a load balancing filter.
- Statement to be executed: SELECT sum(price) FROM orders WHERE order_id = 1. Passed to all filters.
- All configured nodes are passed as input to the first filter. Master nodes: master_0. Slave nodes: slave_0, slave_1, slave_2, slave_3
- Filter: quality_of_service, rule set: session_consistency (read-your-writes) Output: master_0
- Output of master_0 and the statement to be executed is passed as input to the next filter, which is roundrobin.
- Filter: roundrobin. Server list consists of one server. Round robin selects master_0.
A filter sequence must not end with a multi filter. If trying to use a filter sequence which ends with a multi filter the plugin may emit a warning like (mysqlnd_ms) Error in configuration. Last filter is multi filter. Needs to be non-multi one. Stopping in %s on line %d. Furthermore, an appropriate error on the connection handle may be set.
Informacja: Speculation towards the future: MySQL replication filtering
In future versions, there may be additional multi filters. For example, there may be a table filter to support MySQL replication filtering. This would allow you to define rules for which database or table is to be replicated to which node of a replication cluster. Assume your replication cluster consists of four slaves (slave_0, slave_1, slave_2, slave_3) two of which replicate a database named sales (slave_0, slave_1). If the application queries the database slaves, the hypothetical table filter reduces the list of possible servers to slave_0 and slave_1. Because the output and list of candidates consists of more than one server, it is necessary and possible to add additional filters to the candidate list, for example, using a load balancing filter to identify a server for statement execution.
Service level and consistency
Informacja: Version requirement
Service levels have been introduced in mysqlnd_ms version 1.2.0-alpha. mysqlnd_ms_set_qos() requires PHP 5.4.0 or newer.
The plugin can be used with different kinds of MySQL database clusters. Different clusters can deliver different levels of service to applications. The service levels can be grouped by the data consistency levels that can be achieved. The plugin knows about:
- eventual consistency
- session consistency
- strong consistency
Depending how a cluster is used it may be possible to achieve higher service levels than the default one. For example, a read from an asynchronous MySQL replication slave is eventual consistent. Thus, one may say the default consistency level of a MySQL replication cluster is eventual consistency. However, if the master only is used by a client for reading and writing during a session, session consistency (read your writes) is given. PECL mysqlnd 1.2.0 abstracts the details of choosing an appropriate node for any of the above service levels from the user.
Service levels can be set through the qualify-of-service filter in the plugins configuration file and at runtime using the function mysqlnd_ms_set_qos().
The plugin defines the different service levels as follows.
Eventual consistency is the default service provided by an asynchronous cluster, such as classical MySQL replication. A read operation executed on an arbitrary node may or may not return stale data. The applications view of the data is eventual consistent.
Session consistency is given if a client can always read its own writes. An asynchronous MySQL replication cluster can deliver session consistency if clients always use the master after the first write or never query a slave which has not yet replicated the clients write operation.
The plugins understanding of strong consistency is that all clients always see the comitted writes of all other clients. This is the default when using MySQL Cluster or any other cluster offering synchronous data distribution.
Service level parameters
Eventual consistency and session consistency service level accept parameters.
Eventual consistency is the service provided by classical MySQL replication. By default, all nodes qualify for read requests. An optional age parameter can be given to filter out nodes which lag more than a certain number of seconds behind the master. The plugin is using SHOW SLAVE STATUS to measure the lag. Please, see the MySQL reference manual to learn about accuracy and reliability of the SHOW SLAVE STATUS command.
Session consistency (read your writes) accepts an optional GTID parameter to consider reading not only from the master but also from slaves which already have replicated a certain write described by its transaction identifier. This way, when using asynchronous MySQL replication, read requests may be load balanced over slaves while still ensuring session consistency.
The latter requires the use of client-side global transaction id injection.
Advantages of the new approach
The new approach supersedes the use of SQL hints and the configuration option master_on_write in some respects. If an application running on top of an asynchonous MySQL replication cluster cannot accept stale data for certain reads, it is easier to tell the plugin to choose appropriate nodes than prefixing all read statements in question with the SQL hint to enforce the use of the master. Furthermore, the plugin may be able to use selected slaves for reading.
The master_on_write configuration option makes the plugin use the master after the first write (session consistency, read your writes). In some cases, session consistency may not be needed for the rest of the session but only for some, few read operations. Thus, master_on_write may result in more read load on the master than necessary. In those cases it is better to request a higher than default service level only for those reads that actually need it. Once the reads are done, the application can return to default service level. Switching between service levels is only possible using mysqlnd_ms_set_qos().
Performance considerations
A MySQL replication cluster cannot tell clients which slaves are capable of delivering which level of service. Thus, in some cases, clients need to query the slaves to check their status. PECL mysqlnd_ms transparently runs the necessary SQL in the background. However, this is an expensive and slow operation. SQL statements are run if eventual consistency is combined with an age (slave lag) limit and if session consistency is combined with a global transaction ID.
If eventual consistency is combined with an maximum age (slave lag), the plugin selects candidates for statement execution and load balancing for each statement as follows. If the statement is a write all masters are considered as candidates. Slaves are not checked and not considered as candidates. If the statement is a read, the plugin transparently executes SHOW SLAVE STATUS on every slaves connection. It will loop over all connections, send the statement and then start checking for results. Usually, this is slighly faster than a loop over all connections in which for every connection a query is send and the plugin waits for its results. A slave is considered a candidate if SHOW SLAVE STATUS reports Slave_IO_Running=Yes, Slave_SQL_Running=Yes and Seconds_Behind_Master is less or equal than the allowed maximum age. In case of an SQL error, the plugin emits a warning but does not set an error on the connection. The error is not set to make it possible to use the plugin as a drop-in.
If session consistency is combined with a global transaction ID, the plugin executes the SQL statement set with the fetch_last_gtid entry of the global_transaction_id_injection section from the plugins configuration file. Further details are identical to those described above.
In version 1.2.0 no additional optimizations are done for executing background queries. Future versions may contain optimizations, depending on user demand.
If no parameters and options are set, no SQL is needed. In that case, the plugin consider all nodes of the type shown below.
- eventual consistency, no further options set: all masters, all slaves
- session consistency, no further options set: all masters
- strong consistency (no options allowed): all masters
Global transaction IDs
Informacja: Version requirement
Client side global transaction ID injection exists as of mysqlnd_ms version 1.2.0-alpha. Transaction boundaries are detected by monitoring API calls. This is possible as of PHP 5.4.0. Please, see also Transaction handling.
As of MySQL 5.6.5-m8 the MySQL server features built-in global transaction identifiers. The MySQL built-in global transaction ID feature is supported by PECL/mysqlnd_ms 1.3.0-alpha or later. Neither are client-side transaction boundary monitoring nor any setup activities required if using the server feature.
Idea and client-side emulation
PECL/mysqlnd_ms can do client-side transparent global transaction ID injection. In its most basic form, a global transaction identifier is a counter which is incremented for every transaction executed on the master. The counter is held in a table on the master. Slaves replicate the counter table.
In case of a master failure a database administrator can easily identify the most recent slave for promiting it as a new master. The most recent slave has the highest transaction identifier.
Application developers can ask the plugin for the global transaction identifier (GTID) for their last successful write operation. The plugin will return an identifier that refers to an transaction no older than that of the clients last write operation. Then, the GTID can be passed as a parameter to the quality of service (QoS) filter as an option for session consistency. Session consistency ensures read your writes. The filter ensures that all reads are either directed to a master or a slave which has replicated the write referenced by the GTID.
When injection is done
The plugin transparently maintains the GTID table on the master. In autocommit mode the plugin injects an UPDATE statement before executing the users statement for every master use. In manual transaction mode, the injection is done before the application calls commit() to close a transaction. The configuration option report_error of the GTID section in the plugins configuration file is used to control whether a failed injection shall abort the current operation or be ignored silently (default).
Please note, the PHP version requirements for transaction boundary monitoring and their limits.
Limitations
Client-side global transaction ID injection has shortcomings. The potential issues are not specific to PECL/mysqlnd_ms but are rather of general nature.
- Global transaction ID tables must be deployed on all masters and replicas.
- The GTID can have holes. Only PHP clients using the plugin will maintain the table. Other clients will not.
- Client-side transaction boundary detection is based on API calls only.
- Client-side transaction boundary detection does not take implicit commit into account. Some MySQL SQL statements cause an implicit commit and cannot be rolled back.
Using server-side global transaction identifier
Starting with PECL/mysqlnd_ms 1.3.0-alpha the MySQL 5.6.5-m8 or newer built-in global transaction identifier feature is supported. Use of the server feature lifts all of the above listed limitations. Please, see the MySQL Reference Manual for limitations and preconditions for using server built-in global transaction identifiers.
Whether to use the client-side emulation or the server built-in functionality is a question not directly related to the plugin, thus it is not discussed in depth. There are no plans to remove the client-side emulation and you can continue to use it, if the server-side solution is no option. This may be the case in heterogenous environments with old MySQL server or, if any of the server-side solution limitations is not acceptable.
From an applications perspective there is hardly a difference in using one or the other approach. The following properties differ.
- Client-side emulation, as shown in the manual, is using an easy to compare sequence number for global transactions. Multi-master is not handled to keep the manual examples easy. Server-side built-in feature is using a combination of a server identifier and a sequence number as a global transaction identifier. Comparison cannot use numeric algebra. Instead a SQL function must be used. Please, see the MySQL Reference Manual for details.
- Plugin global transaction ID statistics are only available with client-side emulation because they monitor the emulation.
Informacja: Global transaction identifiers in distributed systems
Global transaction identifiers can serve multiple purposes in the context of distributed systems, such as a database cluster. Global transaction identifiers can be used for, for example, system wide identification of transactions, global ordering of transactions, hearthbeat mechanism and for checking the replication status of replicas. PECL/mysqlnd_ms, a clientside driver based software, does focus on using GTIDs for tasks that can be handled at the client, such as checking the replication status of replicas for asynchronous replication setups.
Cache integration
Informacja: Version requirement
The feature requires used of PECL/mysqlnd_ms 1.3.0-beta or later and PECL/mysqlnd_qc 1.1.0-alpha or new. PECL/mysqlnd_ms must be compiled to support the feature. PHP 5.4.0 or newer is required.
Informacja: Suitable MySQL clusters
The feature is targetted for use with MySQL Replication (primary copy). Currently, no other kinds of MySQL clusters are supported. Users of such cluster must control PECL/mysqlnd_qc manually if they are interested in client-side query caching.
Support for MySQL replication clusters (asynchronous primary copy) is the main focus of PECL/mysqlnd_ms. The slaves of a MySQL replication cluster may or may not reflect the latest updates from the master. Slaves are asynchronous and can lag behind the master. A read from a slave is eventual consistent from a cluster-wide perspective.
The same level of consistency is offered by a local cache using time-to-live (TTL) invalidation strategy. Current data or stale data may be served. Eventually, data searched for in the cache is not available and the source of the cache needs to be accessed.
Given that both a MySQL Replication slave (asynchronous secondary) and a local TTL-driven cache deliver the same level of service it is possible to transparently replace a remote database access with a local cache access to gain better possiblity.
As of PECL/mysqlnd_ms 1.3.0-beta the plugin is capable of transparently controlling PECL/mysqlnd_ms 1.1.0-alpha or newer to cache a read-only query if explicitly allowed by setting an appropriate quality of service through mysqlnd_ms_set_qos(). Please, see the quickstart for a code example. Both plugins must be installed, PECL/mysqlnd_ms must be compiled to support the cache feature and PHP 5.4.0 or newer has to be used.
Applications have full control of cache usage and can request fresh data at any time, if need be. Thec ache usage can be enabled and disabled time during the execution of a script. The cache will be used if mysqlnd_ms_set_qos() sets the quality of service to eventual consistency and enables cache usage. Cache usage is disabled by requesting higher consistency levels, for example, session consistency (read your writes). Once the quality of service has been relaxed to eventual consistency the cache can be used again.
If caching is enabled for a read-only statement, PECL/mysqlnd_ms may inject SQL hints to control caching by PECL/mysqlnd_qc. It may modify the SQL statement it got from the application. Subsequent SQL processors are supposed to ignore the SQL hints. A SQL hint is a SQL comment. Comments must not be ignored, for example, by the database server.
The TTL of a cache entry is computed on a per statement basis. Applications set an maximum age for the data they want to retrieve using mysqlnd_ms_set_qos(). The age sets an approximate upper limit of how many seconds the data returned may lag behind the master.
The following logic is used to compute the actual TTL if caching is enabled. The logic takes the estimated slave lag into account for choosing a TTL. If, for example, there are two slaves lagging 5 and 10 seconds behind and the maximum age allowed is 60 seconds, the TTL is set to 50 seconds. Please note, the age setting is no more than an estimated guess.
- Check whether the statement is read-only. If not, don't cache.
- If caching is enabled, check the slave lag of all configured slaves. Establish slave connections if none exist so far and lazy connections are used.
- Send SHOW SLAVE STATUS to all slaves. Do not wait for the first slave to reply before sending to the second slave. Clients often wait long for replies, thus we send out all requests in a burst before fetching in a second stage.
- Loop over all slaves. For every slave wait for its reply. Do not start checking another slave before the currently waited for slave has replied. Check for Slave_IO_Running=Yes and Slave_SQL_Running=Yes. If both conditions hold true, fetch the value of Seconds_Behind_Master. In case of any errors or if conditions fail, set an error on the slave connection. Skip any such slave connection for the rest of connection filtering.
- Search for the maximum value of Seconds_Behind_Master from all slaves that passed the previous conditions. Substract the value from the maximum age provided by the user with mysqlnd_ms_set_qos(). Use the result as a TTL.
- The filtering may sort out all slaves. If so, the maximum age is used as TTL, because the maximum lag found equals zero. It is perfectly valid to sort out all slaves. In the following it is up to subsequent filter to decide what to do. The built-in load balancing filter will pick the master.
- Inject the appropriate SQL hints to enable caching by PECL/mysqlnd_qc.
- Proceed with the connection filtering, e.g. apply load balancing rules to pick a slave.
- PECL/mysqlnd_qc is loaded after PECL/mysqlnd_ms by PHP. Thus, it will see all query modifications of PECL/mysqlnd_ms and cache the query if instructed to do so.
The algorithm may seem expensive. SHOW SLAVE STATUS is a very fast operation. Given a sufficient number of requests and cache hits per second the cost of checking the slaves lag can easily outweight the costs of the cache decision.
Suggestions on a better algorithm are always welcome.
Supported clusters
Any application using any kind of MySQL cluster is faced with the same tasks:
- Identify nodes capable of executing a given statement with the required service level
- Load balance requests within the list of candidates
- Automatic fail over within candidates, if needed
The plugin is optimized for fulfilling these tasks in the context of a classical asynchronous MySQL replication cluster consisting of a single master and many slaves (primary copy). When using classical, asynchronous MySQL replication all of the above listed tasks need to be mastered at the client side.
Other types of MySQL cluster may have lower requirements on the application side. For example, if all nodes in the cluster can answer read and write requests, no read-write splitting needs to be done (multi-master, update-all). If all nodes in the cluster are synchronous, they automatically provide the higest possible quality of service which makes choosing a node easier. In this case, the plugin may serve the application after some reconfiguration to disable certain features, such as built-in read-write splitting.
Informacja: Documentation focus
The documentation focusses describing the use of the plugin with classical asynchronous MySQL replication clusters (primary copy). Support for this kind of cluster has been the original development goal. Use of other clusters is briefly described below. Please note, that this is still work in progress.
Using asynchronous clusters with single master
Primary use case of the plugin. Follow the hints given in the descriptions of each feature.
Informacja: Version requirement
The following cluster may require use of settings not available before mysqlnd_ms 1.2.0-alpha.
Using asynchronous clusters with multiple masters
This setup is currently unsupported.
The plugin has no built-in functionality to direct certain writes to certain masters. It is considered to add table filtering to future versions. Table filter would allow restricting both read and writes to certain slaves and masters based on the database/schema and table used by a statement.
A table filtering feature is prepared in the plugins source code. However, it is instable and must not be used. Bug reports on table filtering will be rejected.
Using synchronous clusters such as MySQL Cluster
MySQL Cluster is a synchronous cluster solution. All cluster nodes accept read and write requests. In the context of the plugin, all nodes shall be considered as masters.
Use the load balancing and fail over features only.
- Disable the plugins built-in read-write splitting.
- Configure masters only.
- Consider random once load balancing strategy, which is the plugins default. If random once is used, only masters are configured and no SQL hints are used to force using a certain node, no connection switches will happen for the duration of a web request. Thus, no special handling is required for transactions. The plugin will pick one master at the beginning of the PHP script and use it until the script terminates.
- Do not set the quality of service. All nodes have all the data. This automatically gives you the highest possible service quality (strong consistency).
- Do not enable client-side global transaction injection. It is neither required to help with server-side fail over nor to assist the quality of service filter choosing an appropiate node.
Disabling built-in read-write splitting.
- Set mysqlnd_ms.disable_rw_split=1
- Do not use SQL hints to enforce the use of slaves
Configure masters only.
- Set mysqlnd_ms.multi_master=1
- Do not configure any slaves
- Set failover=master in the plugins configuration file to avoid warnings about the empty slave list
Instalacja/Konfiguracja
Spis treści
- Wymagania
- Instalacja
- Konfiguracja wykonawcza
- Plugin configuration file (>=1.1.x)
- Plugin configuration file (<= 1.0.x)
- Testing
- Debugging and Tracing
- Monitoring
Wymagania
PHP 5.3.6 or newer. Some advanced functionality requires PHP 5.4.0 or newer.
The mysqlnd_ms replication and load balancing plugin supports all PHP applications and all available PHP MySQL extensions (mysqli, mysql, PDO_MYSQL). The PHP MySQL extension must be configured to use mysqlnd in order to be able to use the mysqlnd_ms plugin for mysqlnd.
Instalacja
To rozszerzenie » PECL nie jest dołączane do PHP.
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/mysqlnd_ms
DLL z tym rozszerzeniem PECL można pobrać zarówno ze strony » PHP Downloads lub z » http://pecl4win.php.net/
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| mysqlnd_ms.enable | 0 | PHP_INI_SYSTEM | |
| mysqlnd_ms.force_config_usage | 0 | PHP_INI_SYSTEM | |
| mysqlnd_ms.ini_file | "" | PHP_INI_SYSTEM | |
| mysqlnd_ms.collect_statistics | 0 | PHP_INI_SYSTEM | |
| mysqlnd_ms.multi_master | 0 | PHP_INI_SYSTEM | |
| mysqlnd_ms.disable_rw_split | 0 | PHP_INI_SYSTEM |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
mysqlnd_ms.enableinteger -
Enables or disables the plugin. If disabled, the extension will not plug into mysqlnd to proxy internal mysqlnd C API calls.
-
mysqlnd_ms.force_config_usageinteger -
If enabled, the plugin checks if the host (server) parameters value of any MySQL connection attempt, matches a section name from the plugin configuration file. If not, the connection attempt is blocked.
-
mysqlnd_ms.ini_filestring -
Plugin specific configuration file.
-
mysqlnd_ms.collect_statisticsinteger -
Enables or disables the collection of statistics. The collection of statistics is disabled by default for performance reasons. Statistics are returned by the function mysqlnd_ms_get_stats().
-
mysqlnd_ms.multi_masterinteger -
Enables or disables support of MySQL multi master replication setups. Please, see also supported clusters.
-
mysqlnd_ms.disable_rw_splitinteger -
Enables or disables built-in read write splitting.
Controls whether load balancing and lazy connection functionality can be used independently of read write splitting. If read write splitting is disabled, only servers from the master list will be used for statement execution. All configured slave servers will be ignored.
The SQL hint MYSQLND_MS_USE_SLAVE will not be recognized. If found, the statement will be redirected to a master.
Disabling read write splitting impacts the return value of mysqlnd_ms_query_is_select(). The function will no longer propose query execution on slave servers.
Informacja: Multiple master servers
Setting mysqlnd_ms.multi_master=1 allows the plugin to use multiple master servers, instead of only the first master server of the master list.
Please, see also supported clusters.
Plugin configuration file (>=1.1.x)
Informacja: Changelog: Feature was added in PECL/mysqlnd_ms 1.1.0-beta
The below description applies to PECL/mysqlnd_ms >= 1.1.0-beta. It is not valid for prior versions.
The plugin uses its own configuration file. The configuration file holds information about the MySQL replication master server, the MySQL replication slave servers, the server pick (load balancing) policy, the failover strategy, and the use of lazy connections.
The plugin loads its configuration file at the beginning of a web request. It is then cached in memory and used for the duration of the web request. This way, there is no need to restart PHP after deploying the configuration file. Configuration file changes will become active almost instantly.
The PHP configuration directive mysqlnd_ms.ini_file is used to set the plugins configuration file. Please note, that the PHP configuration directive may not be evaluated for every web request. Therefore, changing the plugins configuration file name or location may require a PHP restart. However, no restart is required to read changes if an already existing plugin configuration file is updated.
Using and parsing JSON is efficient, and using JSON makes it easier to express hierarchical data structures than the standard php.ini format.
Przykład #1 Converting a PHP array (hash) into JSON format
Or alternatively, a developer may be more familiar with the PHP array syntax, and prefer it. This example demonstrates how a developer might convert a PHP array to JSON.
<?php
$config = array(
"myapp" => array(
"master" => array(
"master_0" => array(
"host" => "localhost",
"socket" => "/tmp/mysql.sock",
),
),
"slave" => array(),
),
);
file_put_contents("mysqlnd_ms.ini", json_encode($config, JSON_PRETTY_PRINT));
printf("mysqlnd_ms.ini file created...\n");
printf("Dumping file contents...\n");
printf("%s\n", str_repeat("-", 80));
echo file_get_contents("mysqlnd_ms.ini");
printf("\n%s\n", str_repeat("-", 80));
?>
Powyższy przykład wyświetli:
mysqlnd_ms.ini file created...
Dumping file contents...
--------------------------------------------------------------------------------
{
"myapp": {
"master": {
"master_0": {
"host": "localhost",
"socket": "\/tmp\/mysql.sock"
}
},
"slave": [
]
}
}
--------------------------------------------------------------------------------
A plugin configuration file consists of one or more sections. Sections are represented by the top-level object properties of the object encoded in the JSON file. Sections could also be called configuration names.
Applications reference sections by their name. Applications use section names as the host (server) parameter to the various connect methods of the mysqli, mysql and PDO_MYSQL extensions. Upon connect, the mysqlnd plugin compares the hostname with all of the section names from the plugin configuration file. If the hostname and section name match, then the plugin will load the settings for that section.
Przykład #2 Using section names example
{
"myapp": {
"master": {
"master_0": {
"host": "localhost"
}
},
"slave": {
"slave_0": {
"host": "192.168.2.27"
},
"slave_1": {
"host": "192.168.2.27",
"port": 3306
}
}
},
"localhost": {
"master": [
{
"host": "localhost",
"socket": "\/path\/to\/mysql.sock"
}
],
"slave": [
{
"host": "192.168.3.24",
"port": "3305"
},
{
"host": "192.168.3.65",
"port": "3309"
}
]
}
}
<?php
/* All of the following connections will be load balanced */
$mysqli = new mysqli("myapp", "username", "password", "database");
$pdo = new PDO('mysql:host=myapp;dbname=database', 'username', 'password');
$mysql = mysql_connect("myapp", "username", "password");
$mysqli = new mysqli("localhost", "username", "password", "database");
?>
Section names are strings. It is valid to use a section name such as 192.168.2.1, 127.0.0.1 or localhost. If, for example, an application connects to localhost and a plugin configuration section localhost exists, the semantics of the connect operation are changed. The application will no longer only use the MySQL server running on the host localhost, but the plugin will start to load balance MySQL queries following the rules from the localhost configuration section. This way you can load balance queries from an application without changing the applications source code. Please keep in mind, that such a configuration may not contribute to overall readability of your applications source code. Using section names that can be mixed up with host names should be seen as a last resort.
Each configuration section contains, at a minimum, a list of master servers
and a list of slave servers. The master list is configured with the keyword
master, while the slave list is configured with the
slave keyword. Failing to provide a slave list will result
in a fatal E_ERROR level error, although a slave list
may be empty. It is possible to allow no slaves. However, this is only recommended
with synchronous clusters, please see also
supported clusters.
The main part of the documentation focusses on the use
of aynchronous MySQL replication clusters.
The master and slave server lists can be optionally indexed by symbolic names for the servers they describe. Alternatively, an array of descriptions for slave and master servers may be used.
Przykład #3 List of anonymous slaves
"slave": [
{
"host": "192.168.3.24",
"port": "3305"
},
{
"host": "192.168.3.65",
"port": "3309"
}
]
An anonymous server list is encoded by the JSON array type. Optionally, symbolic names may be used for indexing the slave or master servers of a server list, and done so using the JSON object type.
Przykład #4 Master list using symbolic names
"master": {
"master_0": {
"host": "localhost"
}
}
It is recommended to index the server lists with symbolic server names. The alias names will be shown in error messages.
The order of servers is preserved and taken into account by mysqlnd_ms. If, for example, you configure round robin load balancing strategy, the first SELECT statement will be executed on the slave that appears first in the slave server list.
A configured server can be described with the host, port, socket, db, user, password and connect_flags. It is mandatory to set the database server host using the host keyword. All other settings are optional.
Przykład #5 Keywords to configure a server
{
"myapp": {
"master": {
"master_0": {
"host": "db_server_host",
"port": "db_server_port",
"socket": "db_server_socket",
"db": "database_resp_schema",
"user": "user",
"password": "password",
"connect_flags": 0
}
},
"slave": {
"slave_0": {
"host": "db_server_host",
"port": "db_server_port",
"socket": "db_server_socket"
}
}
}
}
If a setting is omitted, the plugin will use the value provided by the user API call used to open a connection. Please, see the using section names example above.
The configuration file format has been changed in version 1.1.0-beta to allow for chained filters. Filters are responsible for filtering the configured list of servers to identify a server for execution of a given statement. Filters are configured with the filter keyword. Filters are executed by mysqlnd_ms in the order of their appearance. Defining filters is optional. A configuration section in the plugins configuration file does not need to have a filters entry.
Filters replace the pick[] setting from prior versions. The new random and roundrobin provide the same functionality.
Przykład #6 New roundrobin filter, old functionality
{
"myapp": {
"master": {
"master_0": {
"host": "localhost"
}
},
"slave": {
"slave_0": {
"host": "192.168.78.136",
"port": "3306"
},
"slave_1": {
"host": "192.168.78.137",
"port": "3306"
}
},
"filters": {
"roundrobin": [
]
}
}
}
The function mysqlnd_ms_set_user_pick_server() has been removed. Setting a callback is now done with the user filter. Some filters accept parameters. The user filter requires and accepts a mandatory callback parameter to set the callback previously set through the function mysqlnd_ms_set_user_pick_server().
Przykład #7 The user filter replaces mysqlnd_ms_set_user_pick_server()
"filters": {
"user": {
"callback": "pick_server"
}
}
Here is a short explanation of the configuration directives that can be used.
-
masterarray or object -
List of MySQL replication master servers. The list of either of the JSON type array to declare an anonymous list of servers or of the JSON type object. Please, see above for examples.
Setting at least one master server is mandatory. The plugin will issue an error of type E_ERROR if the user has failed to provide a master server list for a configuration section. The fatal error may read (mysqlnd_ms) Section [master] doesn't exist for host [name_of_a_config_section] in %s on line %d.
A server is described with the host, port, socket, db, user, password and connect_flags. It is mandatory to provide at a value for host. If any of the other values is not given, it will be taken from the user API connect call, please, see also: using section names example.
Table of server configuration keywords.
Keyword Description Version host Database server host. This is a mandatory setting. Failing to provide, will cause an error of type E_RECOVERABLE_ERROR when the plugin tries to connect to the server. The error message may read (mysqlnd_ms) Cannot find [host] in [%s] section in config in %s on line %d.
Since 1.1.0. port Database server TCP/IP port.
Since 1.1.0. socket Database server Unix domain socket.
Since 1.1.0. db Database (schemata).
Since 1.1.0. user MySQL database user.
Since 1.1.0. password MySQL database user password.
Since 1.1.0. connect_flags Connection flags.
Since 1.1.0. The plugin supports using only one master server. An experimental setting exists to enable multi-master support. The details are not documented. The setting is meant for development only.
-
slavearray or object -
List of one or more MySQL replication slave servers. The syntax is identical to setting master servers, please, see master above for details.
The plugin supports using one or more slave servers.
Setting a list of slave servers is mandatory. The plugin will report an error of the type E_ERROR if slave is not given for a configuration section. The fatal error message may read (mysqlnd_ms) Section [slave] doesn't exist for host [%s] in %s on line %d. Note, that it is valid to use an empty slave server list. The error has been introduced to prevent accidently setting no slaves by forgetting about the slave setting. A master-only setup is still possible using an empty slave server list.
If an empty slave list is configured and an attempt is made to execute a statement on a slave the plugin may emit a warning like mysqlnd_ms) Couldn't find the appropriate slave connection. 0 slaves to choose from. upon statement execution. It is possible that another warning follows such as (mysqlnd_ms) No connection selected by the last filter.
-
global_transaction_id_injectionarray or object -
Global transaction identifier configuration related to both the use of the server built-in global transaction ID feature and the client-side emulation.
Keyword Description Version fetch_last_gtid SQL statement for accessing the latest global transaction identifier. The SQL statement is run if the plugin needs to know the most recent global transaction identifier. This can be the case, for example, when checking MySQL Replication slave status. Also used with mysqlnd_ms_get_last_gtid().
Since 1.2.0. check_for_gtid SQL statement for checking if a replica has replicated all transactions up to and including ones searched for. The SQL statement is run when searching for replicas which can offer a higher level of consistency than eventual consistency. The statement must contain a placeholder #GTID which is to be replaced with the global transaction identifier searched for by the plugin. Please, check the quickstart for examples.
Since 1.2.0. report_errors Whether to emit an error of type warning if an issue occurs while executing any of the configured SQL statements.
Since 1.2.0. on_commit Client-side global transaction ID emulation only. SQL statement to run when a transaction finished to update the global transaction identifier sequence number on the master. Please, see the quickstart for examples.
Since 1.2.0. -
filtersobject -
List of filters. A filter is responsible to filter the list of available servers for executing a given statement. Filters can be chained. The random and roundrobin filter replace the pick[] directive used in prior version to select a load balancing policy. The user filter replaces the mysqlnd_ms_set_user_pick_server() function.
Filters may accept parameters to refine their actions.
If no load balancing policy is set, the plugin will default to random_once. The random_once policy picks a random slave server when running the first read-only statement. The slave server will be used for all read-only statements until the PHP script execution ends. No load balancing policy is set and thus, defaulting takes place, if neither the random nor the roundrobin are part of a configuration section.
If a filter chain is configured so that a filter which output no more than once server is used as input for a filter which should be given more than one server as input, the plugin may emit a warning upon opening a connection. The warning may read: (mysqlnd_ms) Error while creating filter '%s' . Non-multi filter '%s' already created. Stopping in %s on line %d. Futhermore an error of the error code 2000, the sql state HY000 and an error message similar to the warning may be set on the connection handle.
Przykład #8 Invalid filter sequence
{ "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": { "slave_0": { "host": "192.168.78.136", "port": "3306" } }, "filters": [ "roundrobin", "random" ] } }<?php
$link = new mysqli("myapp", "root", "", "test");
printf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error());
$link->query("SELECT 1 FROM DUAL");
?>Powyższy przykład wyświetli:
PHP Warning: mysqli::mysqli(): (HY000/2000): (mysqlnd_ms) Error while creating filter 'random' . Non-multi filter 'roundrobin' already created. Stopping in filter_warning.php on line 1 [2000] (mysqlnd_ms) Error while creating filter 'random' . Non-multi filter 'roundrobin' already created. Stopping PHP Warning: mysqli::query(): Couldn't fetch mysqli in filter_warning.php on line 3
-
Filter:
randomobject -
The random filter features the random and random once load balancing policies, set through the pick[] directive in older versions.
The random policy will pick a random server whenever a read-only statement is to be executed. The random once strategy picks a random slave server once and continues using the slave for the rest of the PHP web request. Random once is a default, if load balancing is not configured through a filter.
If the random filter is not given any arguments, it stands for random load balancing policy.
Przykład #9 Random load balancing with random filter
{ "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": { "slave_0": { "host": "192.168.78.136", "port": "3306" }, "slave_1": { "host": "192.168.78.137", "port": "3306" } }, "filters": [ "random" ] } }Optionally, the sticky argument can be passed to the filter. If the parameter sticky is set to the string 1, the filter follows the random once load balancing strategy.
Przykład #10 Random once load balancing with random filter
{ "filters": { "random": { "sticky": "1" } } }Unknown arguments are ignored. No warning or error is given.
Expects one or more servers as input. Outputs one server. A filter sequence such as random, roundrobin may cause a warning and an error message to be set on the connection handle when executing a statement.
-
Filter:
roundrobinobject -
If using the roundrobin filter, the plugin iterates over the list of configured slave servers to pick a server for statement execution. If the plugin reaches the end of the list, it wraps around to the beginning of the list and picks the first configured slave server.
Przykład #11 roundrobin filter
{ "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": { "slave_0": { "host": "192.168.78.136", "port": "3306" } }, "filters": [ "roundrobin" ] } }Expects one or more servers as input. Outputs one server. A filter sequence such as roundrobin, random may cause a warning and an error message to be set on the connection handle when executing a statement.
-
Filter:
userobject -
The user replaces mysqlnd_ms_set_user_pick_server() function, which was removed in 1.1.0-beta. The filter sets a callback for user-defined read/write splitting and server selection.
The plugins built-in read/write query split mechanism decisions can be overwritten in two ways. The easiest way is to prepend a query string with the SQL hints
MYSQLND_MS_MASTER_SWITCH,MYSQLND_MS_SLAVE_SWITCHorMYSQLND_MS_LAST_USED_SWITCH. Using SQL hints one can control, for example, whether a query shall be send to the MySQL replication master server or one of the slave servers. By help of SQL hints it is not possible to pick a certain slave server for query execution.Full control on server selection can be gained using a callback function. Use of a callback is recommended to expert users only because the callback has to cover all cases otherwise handled by the plugin.
The plugin will invoke the callback function for selecting a server from the lists of configured master and slave servers. The callback function inspects the query to run and picks a server for query execution by returning the hosts URI, as found in the master and slave list.
If the lazy connections are enabled and the callback choses a slave server for which no connection has been established so far and establishing the connection to the slave fails, the plugin will return an error upon the next action on the failed connection, for example, when running a query. It is the responsibility of the application developer to handle the error. For example, the application can re-run the query to trigger a new server selection and callback invocation. If so, the callback must make sure to select a different slave, or check slave availability, before returning to the plugin to prevent an endless loop.
Przykład #12 Setting a callback
{ "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": { "slave_0": { "host": "192.168.78.136", "port": "3306" } }, "filters": { "user": { "callback": "pick_server" } } } }The callback is supposed to return a host to run the query on. The host URI is to be taken from the master and slave connection lists passed to the callback function. If callback returns a value neither found in the master nor in the slave connection lists the plugin will emit an error of the type E_RECOVERABLE_ERROR The error may read like (mysqlnd_ms) User filter callback has returned an unknown server. The server 'server that is not in master or slave list' can neither be found in the master list nor in the slave list. If the application catches the error to ignore it, follow up errors may be set on the connection handle, for example, (mysqlnd_ms) No connection selected by the last filter with the error code 2000 and the sqlstate HY000. Furthermore a warning may be emitted.
Referencing a non-existing function as a callback will result in any error of the type E_RECOVERABLE_ERROR whenever the plugin tries to callback function. The error message may reads like: (mysqlnd_ms) Specified callback (pick_server) is not a valid callback. If the application catches the error to ignore it, follow up errors may be set on the connection handle, for example, (mysqlnd_ms) Specified callback (pick_server) is not a valid callback with the error code 2000 and the sqlstate HY000. Furthermore a warning may be emitted.
The following parameters are passed from the plugin to the callback.
Parameter Description Version connected_host URI of the currently connected database server.
Since 1.1.0. query Query string of the statement for which a server needs to be picked.
Since 1.1.0. masters List of master servers to choose from. Note, that the list of master servers may not be identical to the list of configured master servers if the filter is not the first in the filter chain. Previously run filters may have reduced the master list already.
Since 1.1.0. slaves List of slave servers to choose from. Note, that the list of master servers may not be identical to the list of configured master servers if the filter is not the first in the filter chain. Previously run filters may have reduced the master list already.
Since 1.1.0. last_used_connection URI of the server of the connection used to execute the previous statement on.
Since 1.1.0. in_transaction Boolean flag indicating wheter the statement is part of an open transaction. If autocommit mode is turned off, this will be set to
TRUE. Otherwise it is set toFALSE.Transaction detection is based on monitoring the mysqlnd library call set_autocommit. Monitoring is not possible beofre PHP 5.4.0. Please, see connection pooling and switching concepts discussion for further details.
Since 1.1.0. Przykład #13 Using a callback
{ "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": { "slave_0": { "host": "192.168.2.27", "port": "3306" }, "slave_1": { "host": "192.168.78.136", "port": "3306" } }, "filters": { "user": { "callback": "pick_server" } } } }<?php
function pick_server($connected, $query, $masters, $slaves, $last_used_connection, $in_transaction)
{
static $slave_idx = 0;
static $num_slaves = NULL;
if (is_null($num_slaves))
$num_slaves = count($slaves);
/* default: fallback to the plugins build-in logic */
$ret = NULL;
printf("User has connected to '%s'...\n", $connected);
printf("... deciding where to run '%s'\n", $query);
$where = mysqlnd_ms_query_is_select($query);
switch ($where)
{
case MYSQLND_MS_QUERY_USE_MASTER:
printf("... using master\n");
$ret = $masters[0];
break;
case MYSQLND_MS_QUERY_USE_SLAVE:
/* SELECT or SQL hint for using slave */
if (stristr($query, "FROM table_on_slave_a_only"))
{
/* a table which is only on the first configured slave */
printf("... access to table available only on slave A detected\n");
$ret = $slaves[0];
}
else
{
/* round robin */
printf("... some read-only query for a slave\n");
$ret = $slaves[$slave_idx++ % $num_slaves];
}
break;
case MYSQLND_MS_QUERY_LAST_USED:
printf("... using last used server\n");
$ret = $last_used_connection;
break;
}
printf("... ret = '%s'\n", $ret);
return $ret;
}
$mysqli = new mysqli("myapp", "root", "", "test");
if (!($res = $mysqli->query("SELECT 1 FROM DUAL")))
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
else
$res->close();
if (!($res = $mysqli->query("SELECT 2 FROM DUAL")))
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
else
$res->close();
if (!($res = $mysqli->query("SELECT * FROM table_on_slave_a_only")))
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
else
$res->close();
$mysqli->close();
?>Powyższy przykład wyświetli:
User has connected to 'myapp'... ... deciding where to run 'SELECT 1 FROM DUAL' ... some read-only query for a slave ... ret = 'tcp://192.168.2.27:3306' User has connected to 'myapp'... ... deciding where to run 'SELECT 2 FROM DUAL' ... some read-only query for a slave ... ret = 'tcp://192.168.78.136:3306' User has connected to 'myapp'... ... deciding where to run 'SELECT * FROM table_on_slave_a_only' ... access to table available only on slave A detected ... ret = 'tcp://192.168.2.27:3306'
-
Filter:
user_multiobject -
The user_multi differs from the user only in one aspect. Otherwise, their syntax is identical. The user filter must pick and return exactly one node for statement execution. A filter chain usually ends with a filter that emits only one node. The filter chain shall reduce the list of candidates for statement execution down to one. This, only one node left, is the case after the user filter has been run.
The user_multi filter is a multi filter. It returns a list of slave and a list of master servers. This list needs further filtering to identify exactly one node for statement execution. A multi filter is typically placed at the top of the filter chain. The quality_of_service filter is another example of a multi filter.
The return value of the callback set for user_multi must be an an array with two elements. The first element holds a list of selected master servers. The second element contains a list of selected slave servers. The lists shall contain the keys of the slave and master servers as found in the slave and master lists passed to the callback. The below example returns random master and slave lists extracted from the functions input.
Przykład #14 Returning random masters and slaves
<?php
function pick_server($connected, $query, $masters, $slaves, $last_used_connection, $in_transaction)
{
$picked_masters = array()
foreach ($masters as $key => $value) {
if (mt_rand(0, 2) > 1)
$picked_masters[] = $key;
}
$picked_slaves = array()
foreach ($slaves as $key => $value) {
if (mt_rand(0, 2) > 1)
$picked_slaves[] = $key;
}
return array($picked_masters, $picked_slaves);
}
?>The plugin will issue an error of type E_RECOVERABLE if the callback fails to return a server list. The error may read (mysqlnd_ms) User multi filter callback has not returned a list of servers to use. The callback must return an array in %s on line %d. In case the server list is not empty but has invalid servers key/ids in it, an error of type E_RECOVERABLE will the thrown with an error message like (mysqlnd_ms) User multi filter callback has returned an invalid list of servers to use. Server id is negative in %s on line %d, or similar.
Whether an error is emitted in case of an empty slave or master list depends on the configuration. If an empty master list is returned for a write operation, it is likely that the plugin will emit a warning that may read (mysqlnd_ms) Couldn't find the appropriate master connection. 0 masters to choose from. Something is wrong in %s on line %d. Typically a follow up error of type E_ERROR will happen. In case of a read operation and an empty slave list the behviour depends on the fail over configuration. If fail over to master is enabled, no error should appear. If fail over to master is deactivated the plugin will emit a warning that may read (mysqlnd_ms) Couldn't find the appropriate slave connection. 0 slaves to choose from. Something is wrong in %s on line %d.
-
Filter:
quality_of_serviceobject -
The quality_of_service identifies cluster nodes capable of delivering a certain quality of service. It is a multi filter which returns zero, one or multiple of its input servers. Thus, it must be followed by other filters to reduce the number of candidates down to one for statement execution.
The quality_of_service filter has been introduced in 1.2.0-alpha. In the 1.2 series the filters focus is on the consistency aspect of service quality. Different types of clusters offer different default data consistencies. For example, an asynchronous MySQL replication slave offers eventual consistency. The slave may not be able to deliver requested data because it has not replicated the write, it may serve stale database because its lagging behind or it may serve current information. Often, this is acceptable. In some cases higher consistency levels are needed for the application to work correct. In those cases, the quality_of_service can filter out cluster nodes which cannot deliver the necessary quality of service.
The quality_of_service filter can be replaced or created at runtime. A successful call to mysqlnd_ms_set_qos() removes all existing qos filter entries from the filter list and installs a new one at the very beginning. All settings that can be made through mysqlnd_ms_set_qos() can also be in the plugins configuration file. However, use of the function is by far the most common use case. Instead of setting session consistency and strong consistency service levels in the plugins configuration file it is recommended to define only masters and no slaves. Both service levels will force the use of masters only. Using an empty slave list shortens the configuration file, thus improving readability. The only service level for which there is a case of defining in the plugins configuration file is the combination of eventual consistency and maximum slave lag.
Keyword Description Version eventual_consistency Request eventual consistency. Allows the use of all master and slave servers. Data returned may or may not be current.
Eventual consistency accepts an optional age parameter. If age is given the plugin considers only slaves for reading for which MySQL replication reports a slave lag less or equal to age. The repliation lag is measure using SHOW SLAVE STATUS. If the plugin fails to fetch the replication lag, the slave tested is skipped. Implementation details and tipps are given in the quality of service concepts section.
Please note, if a filter chain generates an empty slave list and the PHP configuration directive mysqlnd_ms.multi_master=0 is used, the plugin may emit a warning.
Przykład #15 Global limit on slave lag
{ "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": { "slave_0": { "host": "192.168.2.27", "port": "3306" }, "slave_1": { "host": "192.168.78.136", "port": "3306" } }, "filters": { "quality_of_service": { "eventual_consistency": { "age":123 } } } } }Since 1.2.0. session_consistency Request session consistency (read your writes). Allows use of all masters and all slaves which are in sync with the master. If no further parameters are given slaves are filtered out as there is no reliable way to test if a slave has caugth up to the master or is lagging behind. Please note, if a filter chain generates an empty slave list and the PHP configuration directive mysqlnd_ms.multi_master=0 is used, the plugin may emit a warning.
Session consistency temporarily requested using mysqlnd_ms_set_qos() is a valuable alternative to using master_on_write. master_on_write is likely to send more statements to the master than needed. The application may be able to contiue operation at a lower consistency level after it has done some critial reads.
Since 1.1.0. strong_consistency Request strong consistency. Only masters will be used.
Since 1.2.0. -
failoverstring -
Failover policy. Supported policies: disabled (default), master.
If no failover policy is set, the plugin will not do any automatic failover (failover=disabled). Whenever the plugin fails to connect a server it will emit a warning and set the connections error code and message. Thereafter it is up to the application to handle the error and, for example, resent the last statement to trigger the selection of another server.
If using failover=master the plugin will implicitly failover to a slave, if available. Please check the concepts documentation to learn about potential pitfalls and risks of using failover=master.
Przykład #16 Optional master failover when failing to connect to slave
{ "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": { "slave_0": { "host": "192.168.78.136", "port": "3306" } }, "failover": "master" } }Setting failover to any other value but disabled or master will not emit any warning or error.
-
lazy_connectionsbool -
Controls the use of lazy connections. Lazy connections are connections which are not opened before the client sends the first connection. Lazy connections are a default.
It is strongly recommended to use lazy connections. Lazy connections help to keep the number of open connections low. If you disable lazy connections and, for example, configure one MySQL replication master server and two MySQL replication slaves, the plugin will open three connections upon the first call to a connect function although the application might use the master connection only.
Lazy connections bare a risk if you make heavy use of actions which change the state of a connection. The plugin does not dispatch all state changing actions to all connections from the connection pool. The few dispatched actions are applied to already opened connections only. Lazy connections opened in the future are not affected. Only some settings are "remembered" and applied when lazy connections are opened.
Przykład #17 Disabling lazy connection
{ "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": { "slave_0": { "host": "192.168.78.136", "port": "3306" } }, "lazy_connections": 0 } } -
master_on_writebool -
If set, the plugin will use the master server only after the first statement has been executed on the master. Applications can still send statements to the slaves using SQL hints to overrule the automatic decision.
The setting may help with replication lag. If an application runs an INSERT the plugin will, by default, use the master to execute all following statements, including SELECT statements. This helps to avoid problems with reads from slaves which have not replicated the INSERT yet.
Przykład #18 Master on write for consistent reads
{ "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": { "slave_0": { "host": "192.168.78.136", "port": "3306" } }, "master_on_write": 1 } }Please, note the quality_of_service filter introduced in version 1.2.0-alpha. It gives finer control, for example, for achieving read-your-writes and, it offers additional functionality introducing service levels.
-
trx_stickinessstring -
Transaction stickiness policy. Supported policies: disabled (default), master.
The setting requires 5.4.0 or newer. If used with PHP older than 5.4.0, the plugin will emit a warning like (mysqlnd_ms) trx_stickiness strategy is not supported before PHP 5.3.99.
If no transaction stickiness policy is set or, if setting trx_stickiness=disabled, the plugin is not transaction aware. Thus, the plugin may load balance connections and switch connections in the middle of a transaction. The plugin is not transaction safe. SQL hints must be used avoid connection switches during a transaction.
As of PHP 5.4.0 the mysqlnd library allows the plugin to monitor the autocommit mode set by calls to the libraries set_autocommit() function. If setting set_stickiness=master and autocommit gets disabled by a PHP MySQL extension invoking the mysqlnd library internal function call set_autocommit(), the plugin is made aware of the begin of a transaction. Then, the plugin stops load balancing and directs all statements to the master server until autocommit is enabled. Thus, no SQL hints are required.
An example of a PHP MySQL API function calling the mysqlnd library internal function call set_autocommit() is mysqli_autocommit().
Although setting ser_stickiness=master, the plugin cannot be made aware of autocommit mode changes caused by SQL statements such as SET AUTOCOMMIT=0.
Przykład #19 Using master to execute transactions
{ "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": { "slave_0": { "host": "192.168.78.136", "port": "3306" } }, "trx_stickiness": "master" } }
Plugin configuration file (<= 1.0.x)
Informacja:
The below description applies to PECL/mysqlnd_ms < 1.1.0-beta. It is not valid for later versions.
The plugin is using its own configuration file. The configuration file holds information on the MySQL replication master server, the MySQL replication slave servers, the server pick (load balancing) policy, the failover strategy and the use of lazy connections.
The PHP configuration directive mysqlnd_ms.ini_file is used to set the plugins configuration file.
The configuration file mimics standard the php.ini format. It consists of one or more sections. Every section defines its own unit of settings. There is no global section for setting defaults.
Applications reference sections by their name. Applications use section names as the host (server) parameter to the various connect methods of the mysqli, mysql and PDO_MYSQL extensions. Upon connect the mysqlnd plugin compares the hostname with all section names from the plugin configuration file. If hostname and section name match, the plugin will load the sections settings.
Przykład #1 Using section names example
[myapp] master[] = localhost slave[] = 192.168.2.27 slave[] = 192.168.2.28:3306 [localhost] master[] = localhost:/tmp/mysql/mysql.sock slave[] = 192.168.3.24:3305 slave[] = 192.168.3.65:3309
<?php
/* All of the following connections will be load balanced */
$mysqli = new mysqli("myapp", "username", "password", "database");
$pdo = new PDO('mysql:host=myapp;dbname=database', 'username', 'password');
$mysql = mysql_connect("myapp", "username", "password");
$mysqli = new mysqli("localhost", "username", "password", "database");
?>
Section names are strings. It is valid to use a section name such as 192.168.2.1, 127.0.0.1 or localhost. If, for example, an application connects to localhost and a plugin configuration section [localhost] exists, the semantics of the connect operation are changed. The application will no longer only use the MySQL server running on the host localhost but the plugin will start to load balance MySQL queries following the rules from the [localhost] configuration section. This way you can load balance queries from an application without changing the applications source code.
The master[], slave[] and pick[] configuration directives use a list-like syntax. Configuration directives supporting list-like syntax may appear multiple times in a configuration section. The plugin maintains the order in which entries appear when interpreting them. For example, the below example shows two slave[] configuration directives in the configuration section [myapp]. If doing round-robin load balancing for read-only queries, the plugin will send the first read-only query to the MySQL server mysql_slave_1 because it is the first in the list. The second read-only query will be send to the MySQL server mysql_slave_2 because it is the second in the list. Configuration directives supporting list-like syntax result are ordered from top to bottom in accordance to their appearance within a configuration section.
Przykład #2 List-like syntax
[myapp] master[] = mysql_master_server slave[] = mysql_slave_1 slave[] = mysql_slave_2
Here is a short explanation of the configuration directives that can be used.
-
master[]string -
URI of a MySQL replication master server. The URI follows the syntax hostname[:port|unix_domain_socket].
The plugin supports using only one master server.
Setting a master server is mandatory. The plugin will report a warning upon connect if the user has failed to provide a master server for a configuration section. The warning may read (mysqlnd_ms) Cannot find master section in config. Furthermore the plugin may set an error code for the connection handle such as HY000/2000 (CR_UNKNOWN_ERROR). The corresponding error message depends on your language settings.
-
slave[]string -
URI of one or more MySQL replication slave servers. The URI follows the syntax hostname[:port|unix_domain_socket].
The plugin supports using one or more slave servers.
Setting a slave server is mandatory. The plugin will report a warning upon connect if the user has failed to provide at least one slave server for a configuration section. The warning may read (mysqlnd_ms) Cannot find slaves section in config. Furthermore the plugin may set an error code for the connection handle such as HY000/2000 (CR_UNKNOWN_ERROR). The corresponding error message depends on your language settings.
-
pick[]string -
Load balancing (server picking) policy. Supported policies: random, random_once (default), roundrobin, user.
If no load balancing policy is set, the plugin will default to random_once. The random_once policy picks a random slave server when running the first read-only statement. The slave server will be used for all read-only statements until the PHP script execution ends.
The random policy will pick a random server whenever a read-only statement is to be executed.
If using roundrobin the plugin iterates over the list of configured slave servers to pick a server for statement execution. If the plugin reaches the end of the list, it wraps around to the beginning of the list and picks the first configured slave server.
Setting more than one load balancing policy for a configuration section makes only sense in conjunction with user and mysqlnd_ms_set_user_pick_server(). If the user defined callback fails to pick a server, the plugin falls back to the second configured load balancing policy.
-
failoverstring -
Failover policy. Supported policies: disabled (default), master.
If no failover policy is set, the plugin will not do any automatic failover (failover=disabled). Whenever the plugin fails to connect a server it will emit a warning and set the connections error code and message. Thereafter it is up to the application to handle the error and, for example, resent the last statement to trigger the selection of another server.
If using failover=master the plugin will implicitly failover to a slave, if available. Please check the concepts documentation to learn about potential pitfalls and risks of using failover=master.
-
lazy_connectionsbool -
Controls the use of lazy connections. Lazy connections are connections which are not opened before the client sends the first connection.
It is strongly recommended to use lazy connections. Lazy connections help to keep the number of open connections low. If you disable lazy connections and, for example, configure one MySQL replication master server and two MySQL replication slaves, the plugin will open three connections upon the first call to a connect function although the application might use the master connection only.
Lazy connections bare a risk if you make heavy use of actions which change the state of a connection. The plugin does not dispatch all state changing actions to all connections from the connection pool. The few dispatched actions are applied to already opened connections only. Lazy connections opened in the future are not affected. If, for example, the connection character set is changed using a PHP MySQL API call, the plugin will change the character set of all currently opened connection. It will not remember the character set change to apply it on lazy connections opened in the future. As a result the internal connection pool would hold connections using different character sets. This is not desired. Remember that character sets are taken into account for escaping.
-
master_on_writebool -
If set, the plugin will use the master server only after the first statement has been executed on the master. Applications can still send statements to the slaves using SQL hints to overrule the automatic decision.
The setting may help with replication lag. If an application runs an INSERT the plugin will, by default, use the master to execute all following statements, including SELECT statements. This helps to avoid problems with reads from slaves which have not replicated the INSERT yet.
-
trx_stickinessstring -
Transaction stickiness policy. Supported policies: disabled (default), master.
Experimental feature.
The setting requires 5.4.0 or newer. If used with PHP older than 5.4.0, the plugin will emit a warning like (mysqlnd_ms) trx_stickiness strategy is not supported before PHP 5.3.99.
If no transaction stickiness policy is set or, if setting trx_stickiness=disabled, the plugin is not transaction aware. Thus, the plugin may load balance connections and switch connections in the middle of a transaction. The plugin is not transaction safe. SQL hints must be used avoid connection switches during a transaction.
As of PHP 5.4.0 the mysqlnd library allows the plugin to monitor the autocommit mode set by calls to the libraries trx_autocommit() function. If setting trx_stickiness=master and autocommit gets disabled by a PHP MySQL extension invoking the mysqlnd library internal function call trx_autocommit(), the plugin is made aware of the begin of a transaction. Then, the plugin stops load balancing and directs all statements to the master server until autocommit is enabled. Thus, no SQL hints are required.
An example of a PHP MySQL API function calling the mysqlnd library internal function call trx_autocommit() is mysqli_autocommit().
Although setting trx_stickiness=master, the plugin cannot be made aware of autocommit mode changes caused by SQL statements such as SET AUTOCOMMIT=0.
Testing
Informacja:
The section applies to myslqnd_ms 1.1.0 or newer, not the 1.0 series.
The PECL/mysqlnd_ms test suite is in the tests/ directory of the source distribution. The test suite consists of standard phpt tests, which are described on the PHP Quality Assurance Teams website.
Running the tests requires setting up one to four MySQL servers. Some tests don't connect to MySQL at all. Others require one server for testing. Some require two distict servers. In some cases two servers are used to emulate a replication setup. In other cases a master and a slave of an existing MySQL replication setup are required for testing. The tests will try to detect how many servers and what kind of servers are given. If the required servers are not found, the test will be skipped automatically.
Before running the tests, edit tests/config.inc to configure the MySQL servers to be used for testing.
The most basic configuration is as follows.
putenv("MYSQL_TEST_HOST=localhost");
putenv("MYSQL_TEST_PORT=3306");
putenv("MYSQL_TEST_USER=root");
putenv("MYSQL_TEST_PASSWD=");
putenv("MYSQL_TEST_DB=test");
putenv("MYSQL_TEST_ENGINE=MyISAM");
putenv("MYSQL_TEST_SOCKET=");
putenv("MYSQL_TEST_SKIP_CONNECT_FAILURE=1");
putenv("MYSQL_TEST_CONNECT_FLAGS=0");
putenv("MYSQL_TEST_EXPERIMENTAL=0");
/* replication cluster emulation */
putenv("MYSQL_TEST_EMULATED_MASTER_HOST=". getenv("MYSQL_TEST_HOST"));
putenv("MYSQL_TEST_EMULATED_SLAVE_HOST=". getenv("MYSQL_TEST_HOST"));
/* real replication cluster */
putenv("MYSQL_TEST_MASTER_HOST=". getenv("MYSQL_TEST_EMULATED_MASTER_HOST"));
putenv("MYSQL_TEST_SLAVE_HOST=". getenv("MYSQL_TEST_EMULATED_SLAVE_HOST"));
MYSQL_TEST_HOST, MYSQL_TEST_PORT and MYSQL_TEST_SOCKET define the hostname, TCP/IP port and Unix domain socket of the default database server. MYSQL_TEST_USER and MYSQL_TEST_PASSWD contain the user and password needed to connect to the database/schema configured with MYSQL_TEST_DB. All configured servers must have the same database user configured to give access to the test database.
Using host, host:port or host:/path/to/socket syntax one can set an alternate host, host and port or host and socket for any of the servers.
putenv("MYSQL_TEST_SLAVE_HOST=192.168.78.136:3307"));
putenv("MYSQL_TEST_MASTER_HOST=myserver_hostname:/path/to/socket"));
Debugging and Tracing
The mysqlnd debug log can be used to debug and trace the actitivities of PECL/mysqlnd_ms. As a mysqlnd PECL/mysqlnd_ms adds trace information to the mysqlnd library debug file. Please, see the mysqlnd.debug PHP configuration directive documentation for a detailed description on how to configure the debug log.
Configuration setting example to activate the debug log:
mysqlnd.debug=d:t:x:O,/tmp/mysqlnd.trace
Informacja:
This feature is only available with a debug build of PHP. Works on Microsoft Windows if using a debug build of PHP and PHP was built using Microsoft Visual C version 9 and above.
The debug log shows mysqlnd library and PECL/mysqlnd_ms plugin function calls, similar to a trace log. Mysqlnd library calls are usually prefixed with mysqlnd_. PECL/mysqlnd internal calls begin with mysqlnd_ms.
Example excerpt from the debug log (connect):
[...] >mysqlnd_connect | info : host=myapp user=root db=test port=3306 flags=131072 | >mysqlnd_ms::connect | | >mysqlnd_ms_config_json_section_exists | | | info : section=[myapp] len=[5] | | | >mysqlnd_ms_config_json_sub_section_exists | | | | info : section=[myapp] len=[5] | | | | info : ret=1 | | | <mysqlnd_ms_config_json_sub_section_exists | | | info : ret=1 | | <mysqlnd_ms_config_json_section_exists [...]
The debug log is not only useful for plugin developers but also to find the cause of user errors. For example, if your application does not do proper error handling and fails to record error messages, checking the debug and trace log may help finding the cause. Use of the debug log to debug application issues should be considered only if no other option is available. Writing the debug log to disk is a slow operation and may have negative impact on the application performance.
Example excerpt from the debug log (connection failure):
[...] | | | | | | | info : adding error [Access denied for user 'root'@'localhost' (using password: YES)] to the list | | | | | | | info : PACKET_FREE(0) | | | | | | | info : PACKET_FREE(0x7f3ef6323f50) | | | | | | | info : PACKET_FREE(0x7f3ef6324080) | | | | | | <mysqlnd_auth_handshake | | | | | | info : switch_to_auth_protocol=n/a | | | | | | info : conn->error_info.error_no = 1045 | | | | | <mysqlnd_connect_run_authentication | | | | | info : PACKET_FREE(0x7f3ef63236d8) | | | | | >mysqlnd_conn::free_contents | | | | | | >mysqlnd_net::free_contents | | | | | | <mysqlnd_net::free_contents | | | | | | info : Freeing memory of members | | | | | | info : scheme=unix:///tmp/mysql.sock | | | | | | >mysqlnd_error_list_pdtor | | | | | | <mysqlnd_error_list_pdtor | | | | | <mysqlnd_conn::free_contents | | | | <mysqlnd_conn::connect [...]
The trace log can also be used to verify correct behaviour of PECL/mysqlnd_ms itself, for example, to check which server has been selected for query execution and why.
Example excerpt from the debug log (plugin decision):
[...] >mysqlnd_ms::query | info : query=DROP TABLE IF EXISTS test | >_mysqlnd_plugin_get_plugin_connection_data | | info : plugin_id=5 | <_mysqlnd_plugin_get_plugin_connection_data | >mysqlnd_ms_pick_server_ex | | info : conn_data=0x7fb6a7d3e5a0 *conn_data=0x7fb6a7d410d0 | | >mysqlnd_ms_select_servers_all | | <mysqlnd_ms_select_servers_all | | >mysqlnd_ms_choose_connection_rr | | | >mysqlnd_ms_query_is_select [...] | | | <mysqlnd_ms_query_is_select [...] | | | info : Init the master context | | | info : list(0x7fb6a7d3f598) has 1 | | | info : Using master connection | | | >mysqlnd_ms_advanced_connect | | | | >mysqlnd_conn::connect | | | | | info : host=localhost user=root db=test port=3306 flags=131072 persistent=0 state=0
In this case the statement DROP TABLE IF EXISTS test has been executed. Note that the statement string is shown in the log file. You may want to take measures to restrict access to the log for security considerations.
The statement has been load balanced using round robin policy, as you can easily guess from the functions name >mysqlnd_ms_choose_connection_rr. It has been sent to a master server running on host=localhost user=root db=test port=3306 flags=131072 persistent=0 state=0.
Monitoring
Plugin activity can be monitored using the mysqlnd trace log, mysqlnd statistics, mysqlnd_ms plugin statistics and external PHP debugging tools. Use of the trace log should be limited to debugging. It is recommended to use the plugins statistics for monitoring.
Writing a trace log is a slow operation. If using an external PHP debugging tool, please refer to the vendors manual about its perfomance impact and the type of information collected. In many cases, external debugging tools will provide call stacks. Often, a call stack or a trace log is more difficult to interpret than the statistics provided by the plugin.
Plugin statistics tell how often which kind of cluster node has been used (slave or master), why the node was used, if lazy connections have been used and if global transaction ID injection has been performed. The monitoring information provided enables user to verify plugin decisions and to plan their cluster resources based on usage pattern. The function mysqlnd_ms_get_stats() is used to access the statistics. Please, see the functions description for a list of available statistics.
Statistics are collected on a per PHP process basis. Their scope is a PHP process. Depending on the PHP deployment model a process may serve one or multiple web requests. If using CGI model, a PHP process serves one web request. If using FastCGI or pre-fork web server models, a PHP process usually serves multiple web requests. The same is the case with a threaded web server. Please, note that threads running in parallel can update the statistics in parallel. Thus, if using a threaded PHP deployment model, statistics can be changed by more than one script at a time. A script cannot rely on the fact that it sees only its own changes to statistics.
Przykład #1 Verify plugin activity in a non-threaded deployment model
mysqlnd_ms.enable=1 mysqlnd_ms.collect_statistics=1
<?php
/* Load balanced following "myapp" section rules from the plugins config file (not shown) */
$mysqli = new mysqli("myapp", "username", "password", "database");
if (mysqli_connect_errno())
/* Of course, your error handling is nicer... */
die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
$stats_before = mysqlnd_ms_get_stats();
if ($res = $mysqli->query("SELECT 'Read request' FROM DUAL")) {
var_dump($res->fetch_all());
}
$stats_after = mysqlnd_ms_get_stats();
if ($stats_after['use_slave'] <= $stats_before['use_slave']) {
echo "According to the statistics the read request has not been run on a slave!";
}
?>
Statistics are aggregated for all plugin activities and all connections handled by the plugin. It is not possible to tell how much a certain connection handle has contributed to the overall statistics.
Utilizing PHPs register_shutdown_function() function or the auto_append_file PHP configuration directive it is easily possible to dump statistics into, for example, a log file when a script finishes. Instead of using a log file it is also possible to send the statistics to an external monitoring tool for recording and display.
Przykład #2 Recording statistics during shutdown
mysqlnd_ms.enable=1 mysqlnd_ms.collect_statistics=1 error_log=/tmp/php_errors.log
<?php
function check_stats() {
$msg = str_repeat("-", 80) . "\n";
$msg .= var_export(mysqlnd_ms_get_stats(), true) . "\n";
$msg .= str_repeat("-", 80) . "\n";
error_log($msg);
}
register_shutdown_function("check_stats");
?>
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
SQL hint related
The mysqlnd replication and load balancing plugin (mysqlnd_ms) performs read/write splitting. This directs write queries to a MySQL master server, and read-only queries to the MySQL slave servers. The plugin has a built-in read/write split logic. All queries which start with SELECT are considered read-only queries, which are then sent to a MySQL slave server that is listed in the plugin configuration file. All other queries are directed to the MySQL master server that is also specified in the plugin configuration file.
User supplied SQL hints can be used to overrule automatic read/write splitting, to gain full control on the process. SQL hints are standards compliant SQL comments. The plugin will scan the beginning of a query string for an SQL comment for certain commands, which then control query redirection. Other systems involved in the query processing are unaffected by the SQL hints because other systems will ignore the SQL comments.
The plugin supports three SQL hints to direct queries to either the MySQL slave servers, the MySQL master server, or the last used MySQL server. SQL hints must be placed at the beginning of a query to be recognized by the plugin.
For better portability, it is recommended to use the string constants
MYSQLND_MS_MASTER_SWITCH,
MYSQLND_MS_SLAVE_SWITCH and
MYSQLND_MS_LAST_USED_SWITCH instead of their literal
values.
<?php
/* Use constants for maximum portability */
$master_query = "/*" . MYSQLND_MS_MASTER_SWITCH . "*/SELECT id FROM test";
/* Valid but less portable: using literal instead of constant */
$slave_query = "/*ms=slave*/SHOW TABLES";
printf("master_query = '%s'\n", $master_query);
printf("slave_query = '%s'\n", $slave_query);
?>
Powyższe przykłady wyświetlą:
master_query = /*ms=master*/SELECT id FROM test slave_query = /*ms=slave*/SHOW TABLES
-
MYSQLND_MS_MASTER_SWITCH(string) - SQL hint used to send a query to the MySQL replication master server.
-
MYSQLND_MS_SLAVE_SWITCH(string) - SQL hint used to send a query to one of the MySQL replication slave servers.
-
MYSQLND_MS_LAST_USED_SWITCH(string) - SQL hint used to send a query to the last used MySQL server. The last used MySQL server can either be a master or a slave server in a MySQL replication setup.
mysqlnd_ms_query_is_select() related
-
MYSQLND_MS_QUERY_USE_MASTER(integer) -
If mysqlnd_ms_is_select() returns
MYSQLND_MS_QUERY_USE_MASTERfor a given query, the built-in read/write split mechanism recommends sending the query to a MySQL replication master server. -
MYSQLND_MS_QUERY_USE_SLAVE(integer) -
If mysqlnd_ms_is_select() returns
MYSQLND_MS_QUERY_USE_SLAVEfor a given query, the built-in read/write split mechanism recommends sending the query to a MySQL replication slave server. -
MYSQLND_MS_QUERY_USE_LAST_USED(integer) -
If mysqlnd_ms_is_select() returns
MYSQLND_MS_QUERY_USE_LAST_USEDfor a given query, the built-in read/write split mechanism recommends sending the query to the last used server.
mysqlnd_ms_set_qos(), quality of service filter and service level related
-
MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL(integer) - Use to request the service level eventual consistency from the mysqlnd_ms_set_qos(). Eventual consistency is the default quality of service when reading from an asynchronous MySQL replication slave. Data returned in this service level may or may not be stale, depending on whether the selected slaves happens to have replicated the lastest changes from the MySQL replication master or not.
-
MYSQLND_MS_QOS_CONSISTENCY_SESSION(integer) - Use to request the service level session consistency from the mysqlnd_ms_set_qos(). Session consistency is defined as read your writes. The client is guaranteed to see his latest changes.
-
MYSQLND_MS_QOS_CONSISTENCY_STRONG(integer) - Use to request the service level strong consistency from the mysqlnd_ms_set_qos(). Strong consistency is used to ensure all clients see each others changes.
-
MYSQLND_MS_QOS_OPTION_GTID(integer) - Used as a service level option with mysqlnd_ms_set_qos() to parameterize session consistency.
-
MYSQLND_MS_QOS_OPTION_AGE(integer) - Used as a service level option with mysqlnd_ms_set_qos() to parameterize eventual consistency.
Other
The plugins version number can be obtained using
MYSQLND_MS_VERSION or
MYSQLND_MS_VERSION_ID.
MYSQLND_MS_VERSION
is the string representation of the numerical version number
MYSQLND_MS_VERSION_ID, which is an integer such as 10000.
Developers can calculate the version number as follows.
| Version (part) | Example |
|---|---|
| Major*10000 | 1*10000 = 10000 |
| Minor*100 | 0*100 = 0 |
| Patch | 0 = 0 |
| MYSQLND_MS_VERSION_ID | 10000 |
Mysqlnd_ms Funkcje
mysqlnd_ms_get_last_gtid
(PECL mysqlnd_ms >= 1.2.0)
mysqlnd_ms_get_last_gtid — Returns the latest global transaction ID
Opis
Returns a global transaction identifier which belongs to a write operation no older than the last write performed by the client. It is not guaranteed that the global transaction identifier is identical to that one created for the last write transaction performed by the client.
Parametry
Zwracane wartości
Returns a global transaction ID (GTID) on success.
Otherwise, returns FALSE.
The function mysqlnd_ms_get_last_gtid() returns the GTID obtained when executing the SQL statement from the fetch_last_gtid entry of the global_transaction_id_injection section from the plugins configuration file.
The function may be called after the GTID has been incremented.
Notatki
Informacja:
mysqlnd_ms_get_last_gtid() requires PHP >= 5.4.0 and PECL mysqlnd_ms >= 1.2.0. Internally, it is using a mysqlnd library C functionality not available with PHP 5.3.
Przykłady
Przykład #1 mysqlnd_ms_get_last_gtid() example
<?php
/* Open mysqlnd_ms connection using mysqli, PDO_MySQL or mysql extension */
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli)
/* Of course, your error handling is nicer... */
die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
/* auto commit mode, transaction on master, GTID must be incremented */
if (!$mysqli->query("DROP TABLE IF EXISTS test"))
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
printf("GTID after transaction %s\n", mysqlnd_ms_get_last_gtid($mysqli));
/* auto commit mode, transaction on master, GTID must be incremented */
if (!$mysqli->query("CREATE TABLE test(id INT)"))
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
printf("GTID after transaction %s\n", mysqlnd_ms_get_last_gtid($mysqli));
?>
mysqlnd_ms_get_last_used_connection
(PECL mysqlnd_ms >= 1.1.0)
mysqlnd_ms_get_last_used_connection — Returns an array which describes the last used connection
Opis
Returns an array which describes the last used connection from the plugins connection pool currently pointed to by the user connection handle. If using the plugin, a user connection handle represents a pool of database connections. It is not possible to tell from the user connection handles properties to which database server from the pool the user connection handle points.
The function can be used to debug or monitor PECL mysqlnd_ms.
Parametry
Zwracane wartości
FALSE on error. Otherwise, an
array which describes the connection used to
execute the last statement on.
Array which describes the connection.
| Property | Description | Version |
|---|---|---|
| scheme | Connection scheme. Either tcp://host:port or unix://host:socket. If you want to distinguish connections from each other use a combination of scheme and thread_id as a unique key. Neither scheme nor thread_id alone are sufficient to distinguish two connections from each other. Two servers may assign the same thread_id to two different connections. Thus, connections in the pool may have the same thread_id. Also, do not rely on uniqueness of scheme in a pool. Your QA engineers may use the same MySQL server instance for two distinct logical roles and add it multiple times to the pool. This hack is used, for example, in the test suite. | Since 1.1.0. |
| host | Database server host used with the connection. The host is only set with TCP/IP connections. It is empty with Unix domain or Windows named pipe connections, | Since 1.1.0. |
| host_info | A character string representing the server hostname and the connection type. | Since 1.1.2. |
| port | Database server port used with the connection. | Since 1.1.0. |
| socket_or_pipe | Unix domain socket or Windows named pipe used with the connection. The value is empty for TCP/IP connections. | Since 1.1.2. |
| thread_id | Connection thread id. | Since 1.1.0. |
| last_message | Info message obtained from the MySQL C API function mysql_info(). Please, see mysqli_info() for a description. | Since 1.1.0. |
| errno | Error code. | Since 1.1.0. |
| error | Error message. | Since 1.1.0. |
| sqlstate | Error SQLstate code. | Since 1.1.0. |
Notatki
Informacja:
mysqlnd_ms_get_last_used_connection() requires PHP >= 5.4.0 and PECL mysqlnd_ms >> 1.1.0. Internally, it is using a mysqlnd library C call not available with PHP 5.3.
Przykłady
The example assumes that myapp refers to a plugin configuration file section and represents a connection pool.
Przykład #1 mysqlnd_ms_get_last_used_connection() example
<?php
$link = new mysqli("myapp", "user", "password", "database");
$res = $link->query("SELECT 1 FROM DUAL");
var_dump(mysqlnd_ms_get_last_used_connection($link));
?>
Powyższy przykład wyświetli:
array(10) {
["scheme"]=>
string(22) "unix:///tmp/mysql.sock"
["host_info"]=>
string(25) "Localhost via UNIX socket"
["host"]=>
string(0) ""
["port"]=>
int(3306)
["socket_or_pipe"]=>
string(15) "/tmp/mysql.sock"
["thread_id"]=>
int(46253)
["last_message"]=>
string(0) ""
["errno"]=>
int(0)
["error"]=>
string(0) ""
["sqlstate"]=>
string(5) "00000"
}
mysqlnd_ms_get_stats
(PECL mysqlnd_ms >= 1.0.0)
mysqlnd_ms_get_stats — Returns query distribution and connection statistics
Opis
Returns an array of statistics collected by the replication and load balancing plugin.
The PHP configuration setting mysqlnd_ms.collect_statistics controls the collection of statistics. The collection of statistics is disabled by default for performance reasons.
The scope of the statistics is the PHP process. Depending on your deployment model a PHP process may handle one or multiple requests.
Statistics are aggregated for all connections and all storage handler. It is not possible to tell how much queries originating from mysqli, PDO_MySQL or mysql API calls have contributed to the aggregated data values.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns NULL if
the PHP configuration directive
mysqlnd_ms.enable
has disabled the plugin. Otherwise, returns array of statistics.
Array of statistics
| Statistic | Description | Version |
|---|---|---|
| use_slave |
The semantics of this statistic has changed between 1.0.1 - 1.1.0. The meaning for version 1.0.1 is as follows. Number of statements considered as read-only by the built-in query analyzer. Neither statements which begin with a SQL hint to force use of slave nor statements directed to a slave by an user-defined callback are included. The total number of statements sent to the slaves is use_slave + use_slave_sql_hint + use_slave_callback. PECL/mysqlnd_ms 1.1.0 introduces a new concept of chained filters. The statictics is now set by the internal load balancing filter. With version 1.1.0 the load balancing filter is always the last in the filter chain, if used. In future versions a load balancing filter may be followed by other filters causing another change in the meaning of the statistic. If, in the future, a load balancing filter is followed by another filter it is no longer guaranteed that the satement, whichs increments use_slave, will be executed on the slaves. The meaning for version 1.1.0 is as follows. Number of statements sent to the slaves. Statements directed to a slave by the user filter (an user-defined callback) are not included. The latter are counted by use_slave_callback. |
Since 1.0.0. |
| use_master |
The semantics of this statistic has changed between 1.0.1 - 1.1.0. The meaning for version 1.0.1 is as follows. Number of statements not considered as read-only by the built-in query analyzer. Neither statements which begin with a SQL hint to force use of master nor statements directed to a master by an user-defined callback are included. The total number of statements sent to the master is use_master + use_master_sql_hint + use_master_callback. PECL/mysqlnd_ms 1.1.0 introduces a new concept of chained filters. The statictics is now set by the internal load balancing filter. With version 1.1.0 the load balancing filter is always the last in the filter chain, if used. In future versions a load balancing filter may be followed by other filters causing another change in the meaning of the statistic. If, in the future, a load balancing filter is followed by another filter it is no longer guaranteed that the satement, whichs increments use_master, will be executed on the slaves. The meaning for version 1.1.0 is as follows. Number of statements sent to the masters. Statements directed to a master by the user filter (an user-defined callback) are not included. The latter are counted by use_master_callback. |
Since 1.0.0. |
| use_slave_guess | Number of statements the built-in query analyzer recommends sending to a slave because they contain no SQL hint to force use of a certain server. The recommendation may be overruled in the following. It is not guaranteed whether the statement will be excuted on a slave or not. This is how often the internal is_select function has guessed that a slave shall be used. Please, see also the user space function mysqlnd_ms_query_is_select(). | Since 1.1.0. |
| use_master_guess | Number of statements the built-in query analyzer recommends sending to a master because they contain no SQL hint to force use of a certain server. The recommendation may be overruled in the following. It is not guaranteed whether the statement will be excuted on a slave or not. This is how often the internal is_select function has guessed that a master shall be used. Please, see also the user space function mysqlnd_ms_query_is_select(). | Since 1.1.0. |
| use_slave_sql_hint | Number of statements sent to a slave because statement begins with the SQL hint to force use of slave. | Since 1.0.0. |
| use_master_sql_hint | Number of statements sent to a master because statement begins with the SQL hint to force use of master. | Since 1.0.0. |
| use_last_used_sql_hint | Number of statements sent to server which has run the previous statement, because statement begins with the SQL hint to force use of previously used server. | Since 1.0.0. |
| use_slave_callback | Number of statements sent to a slave because an user-defined callback has chosen a slave server for statement execution. | Since 1.0.0. |
| use_master_callback | Number of statements sent to a master because an user-defined callback has chosen a master server for statement execution. | Since 1.0.0. |
| non_lazy_connections_slave_success | Number of successfully opened slave connections from configurations not using lazy connections. The total number of successfully opened slave connections is non_lazy_connections_slave_success + lazy_connections_slave_success | Since 1.0.0. |
| non_lazy_connections_slave_failure | Number of failed slave connection attempts from configurations not using lazy connections. The total number of failed slave connection attempts is non_lazy_connections_slave_failure + lazy_connections_slave_failure | Since 1.0.0. |
| non_lazy_connections_master_success | Number of successfully opened master connections from configurations not using lazy connections. The total number of successfully opened master connections is non_lazy_connections_master_success + lazy_connections_master_success | Since 1.0.0. |
| non_lazy_connections_master_failure | Number of failed master connection attempts from configurations not using lazy connections. The total number of failed master connection attempts is non_lazy_connections_master_failure + lazy_connections_master_failure | Since 1.0.0. |
| lazy_connections_slave_success | Number of successfully opened slave connections from configurations using lazy connections. | Since 1.0.0. |
| lazy_connections_slave_failure | Number of failed slave connection attempts from configurations using lazy connections. | Since 1.0.0. |
| lazy_connections_master_success | Number of successfully opened master connections from configurations using lazy connections. | Since 1.0.0. |
| lazy_connections_master_failure | Number of failed master connection attempts from configurations using lazy connections. | Since 1.0.0. |
| trx_autocommit_on | Number of autocommit mode activations via API calls. This figure may be used to monitor activity related to the plugin configuration setting trx_stickiness. If, for example, you want to know if a certain API call invokes the mysqlnd library function trx_autocommit(), which is a requirement for trx_stickiness, you may call the user API function in question and check if the statistic has changed. The statistic is modified only by the plugins internal subclassed trx_autocommit() method. | Since 1.0.0. |
| trx_autocommit_off | Number of autocommit mode deactivations via API calls. | Since 1.0.0. |
| trx_master_forced | Number of statemens redirected to the master while trx_stickiness=master and autocommit mode is disabled. | Since 1.0.0. |
| gtid_autocommit_injections_success | Number of successful SQL injections in autocommit mode as part of the plugins client-side global transaction id emulation. | Since 1.2.0. |
| gtid_autocommit_injections_failure | Number of failed SQL injections in autocommit mode as part of the plugins client-side global transaction id emulation. | Since 1.2.0. |
| gtid_commit_injections_success | Number of successful SQL injections in commit mode as part of the plugins client-side global transaction id emulation. | Since 1.2.0. |
| gtid_commit_injections_failure | Number of failed SQL injections in commit mode as part of the plugins client-side global transaction id emulation. | Since 1.2.0. |
| gtid_implicit_commit_injections_success | Number of successful SQL injections when implicit commit is detected as part of the plugins client-side global transaction id emulation. Implicit commit happens, for example, when autocommit has been turned off, a query is executed and autocommit is enabled again. In that case, the statement will be committed by the server and SQL to maintain is injected before the autocommit is re-enabled. | Since 1.2.0. |
| gtid_implicit_commit_injections_failure | Number of failed SQL injections when implicit commit is detected as part of the plugins client-side global transaction id emulation. Implicit commit happens, for example, when autocommit has been turned off, a query is executed and autocommit is enabled again. In that case, the statement will be committed by the server and SQL to maintain is injected before the autocommit is re-enabled. | Since 1.2.0. |
Przykłady
Przykład #1 mysqlnd_ms_get_stats() example
<?php
printf("mysqlnd_ms.enable = %d\n", ini_get("mysqlnd_ms.enable"));
printf("mysqlnd_ms.collect_statistics = %d\n", ini_get("mysqlnd_ms.collect_statistics"));
var_dump(mysqlnd_ms_get_stats());
?>
Powyższy przykład wyświetli:
mysqlnd_ms.enable = 1
mysqlnd_ms.collect_statistics = 1
array(26) {
["use_slave"]=>
string(1) "0"
["use_master"]=>
string(1) "0"
["use_slave_guess"]=>
string(1) "0"
["use_master_guess"]=>
string(1) "0"
["use_slave_sql_hint"]=>
string(1) "0"
["use_master_sql_hint"]=>
string(1) "0"
["use_last_used_sql_hint"]=>
string(1) "0"
["use_slave_callback"]=>
string(1) "0"
["use_master_callback"]=>
string(1) "0"
["non_lazy_connections_slave_success"]=>
string(1) "0"
["non_lazy_connections_slave_failure"]=>
string(1) "0"
["non_lazy_connections_master_success"]=>
string(1) "0"
["non_lazy_connections_master_failure"]=>
string(1) "0"
["lazy_connections_slave_success"]=>
string(1) "0"
["lazy_connections_slave_failure"]=>
string(1) "0"
["lazy_connections_master_success"]=>
string(1) "0"
["lazy_connections_master_failure"]=>
string(1) "0"
["trx_autocommit_on"]=>
string(1) "0"
["trx_autocommit_off"]=>
string(1) "0"
["trx_master_forced"]=>
string(1) "0"
["gtid_autocommit_injections_success"]=>
string(1) "0"
["gtid_autocommit_injections_failure"]=>
string(1) "0"
["gtid_commit_injections_success"]=>
string(1) "0"
["gtid_commit_injections_failure"]=>
string(1) "0"
["gtid_implicit_commit_injections_success"]=>
string(1) "0"
["gtid_implicit_commit_injections_failure"]=>
string(1) "0"
}
mysqlnd_ms_match_wild
(PECL mysqlnd_ms >= 1.1.0)
mysqlnd_ms_match_wild — Finds whether a table name matches a wildcard pattern or not
Opis
$table_name
, string $wildcard
)Finds whether a table name matches a wildcard pattern or not.
This function is not of much practical relevance with PECL mysqlnd_ms 1.1.0 because the plugin does not support MySQL replication table filtering yet.
Parametry
-
table_name -
The table name to check if it is matched by the wildcard.
-
wildcard -
The wildcard pattern to check against the table name. The wildcard pattern supports the same placeholders as MySQL replication filters do.
MySQL replication filters can be configured by using the MySQL Server configuration options --replicate-wild-do-table and --replicate-wild-do-db. Please, consult the MySQL Reference Manual to learn more about this MySQL Server feature.
The supported placeholders are:
- % - zero or more literals
- % - one literal
Placeholders can be escaped using \.
Zwracane wartości
Returns TRUE table_name is
matched by wildcard.
Otherwise, returns FALSE
Przykłady
Przykład #1 mysqlnd_ms_match_wild() example
<?php
var_dump(mysqlnd_ms_match_wild("schema_name.table_name", "schema%"));
var_dump(mysqlnd_ms_match_wild("abc", "_"));
var_dump(mysqlnd_ms_match_wild("table1", "table_"));
var_dump(mysqlnd_ms_match_wild("asia_customers", "%customers"));
var_dump(mysqlnd_ms_match_wild("funny%table","funny\%table"));
var_dump(mysqlnd_ms_match_wild("funnytable", "funny%table"));
?>
Powyższy przykład wyświetli:
bool(true) bool(false) bool(true) bool(true) bool(true) bool(true)
mysqlnd_ms_query_is_select
(PECL mysqlnd_ms >= 1.0.0)
mysqlnd_ms_query_is_select — Find whether to send the query to the master, the slave or the last used MySQL server
Opis
$query
)Finds whether to send the query to the master, the slave or the last used MySQL server.
The plugins built-in read/write split mechanism will be used to analyze the query string to make a recommendation where to send the query. The built-in read/write split mechanism is very basic and simple. The plugin will recommend sending all queries to the MySQL replication master server but those which begin with SELECT, or begin with a SQL hint which enforces sending the query to a slave server. Due to the basic but fast algorithm the plugin may propose to run some read-only statements such as SHOW TABLES on the replication master.
Parametry
-
query -
Query string to test.
Zwracane wartości
A return value of MYSQLND_MS_QUERY_USE_MASTER
indicates that the query should be send to the MySQL replication
master server. The function returns a value of
MYSQLND_MS_QUERY_USE_SLAVE if the query can be run
on a slave because it is considered read-only. A value of
MYSQLND_MS_QUERY_USE_LAST_USED is returned to recommend
running the query on the last used server. This can either be a MySQL
replication master server or a MySQL replication slave server.
If read write splitting has been disabled by setting
mysqlnd_ms.disable_rw_split, the fucntion will
always return MYSQLND_MS_QUERY_USE_MASTER or
MYSQLND_MS_QUERY_USE_LAST_USED.
Przykłady
Przykład #1 mysqlnd_ms_query_is_select() example
<?php
function is_select($query)
{
switch (mysqlnd_ms_query_is_select($query))
{
case MYSQLND_MS_QUERY_USE_MASTER:
printf("'%s' should be run on the master.\n", $query);
break;
case MYSQLND_MS_QUERY_USE_SLAVE:
printf("'%s' should be run on a slave.\n", $query);
break;
case MYSQLND_MS_QUERY_USE_LAST_USED:
printf("'%s' should be run on the server that has run the previous query\n", $query);
break;
default:
printf("No suggestion where to run the '%s', fallback to master recommended\n", $query);
break;
}
}
is_select("INSERT INTO test(id) VALUES (1)");
is_select("SELECT 1 FROM DUAL");
is_select("/*" . MYSQLND_MS_LAST_USED_SWITCH . "*/SELECT 2 FROM DUAL");
?>
Powyższy przykład wyświetli:
INSERT INTO test(id) VALUES (1) should be run on the master. SELECT 1 FROM DUAL should be run on a slave. /*ms=last_used*/SELECT 2 FROM DUAL should be run on the server that has run the previous query
mysqlnd_ms_set_qos
(PECL mysqlnd_ms < 1.2.0)
mysqlnd_ms_set_qos — Sets the quality of service needed from the cluster
Opis
$connection
, int $service_level
[, int $service_level_option
[, mixed $option_value
]] )Sets the quality of service needed from the cluster. A database cluster delivers a certain quality of service to the user depending on its architecture. A major aspect of the quality of service is the consistency level the cluster can offer. An asynchronous MySQL replication cluster defaults to eventual consistency for slave reads: a slave may serve stale data, current data, or it may have not the requested data at all, because it is not synchronous to the master. In a MySQL replication cluster, only master accesses can give strong consistency, which promises that all clients see each others changes.
PECL/mysqlnd_ms hides the complexity of choosing appropriate nodes to achieve a certain level of service from the cluster. The "Quality of Service" filter implements the necessary logic. The filter can either be configured in the plugins configuration file, or at runtime using mysqlnd_ms_set_qos().
Similar results can be achieved with PECL mysqlnd_ms < 1.2.0, if using SQL hints to force the use of a certain type of node or using the master_on_write plugin configuration option. The first requires more code and causes more work on the application side. The latter is less refined than using the quality of service filter. Settings made through the function call can be reversed, as shown in the example below. The example temporarily switches to a higher service level (session consistency, read your writes) and returns back to the clusters default after it has performed all operations that require the better service. This way, read load on the master can be minimized compared to using master_on_write, which would continue using the master after the first write.
Parametry
-
connection -
A PECL/mysqlnd_ms connection handle to a MySQL server of the type PDO_MYSQL, mysqli> or ext/mysql for which a service level is to be set. The connection handle is obtained when opening a connection with a host name that matches a mysqlnd_ms configuration file entry using any of the above three MySQL driver extensions.
-
service_level -
The requested service level:
MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL,MYSQLND_MS_QOS_CONSISTENCY_SESSIONorMYSQLND_MS_QOS_CONSISTENCY_STRONG. -
service_level_option -
An option to parameterize the requested service level. The option can either be
MYSQLND_MS_QOS_OPTION_GTIDorMYSQLND_MS_QOS_OPTION_AGE.The option
MYSQLND_MS_QOS_OPTION_GTIDcan be used to refine the service levelMYSQLND_MS_QOS_CONSISTENCY_SESSION. It must be combined with a fourth function parameter, theoption_value. Theoption_valueshall be a global transaction ID obtained from mysqlnd_ms_get_last_gtid(). If set, the plugin considers both master servers and asynchronous slaves for session consistency (read your writes). Otherwise, only masters are used to achieve session consistency. A slave is considered up-to-date and checked if it has already replicated the global transaction ID fromoption_value. Please note, searching appropriate slaves is an expensive and slow operation. Use the feature sparsely, if the master cannot handle the read load alone.The
MYSQLND_MS_QOS_OPTION_AGEoption can be combined with theMYSQLND_MS_QOS_CONSISTENCY_EVENTUALservice level, to filter out asynchronous slaves that lag more seconds behind the master thanoption_value. If set, the plugin will only consider slaves for reading if SHOW SLAVE STATUS reports Slave_IO_Running=Yes, Slave_SQL_Running=Yes and Seconds_Behind_Master <= option_value. Please note, searching appropriate slaves is an expensive and slow operation. Use the feature sparsely in version 1.2.0. Future versions may improve the algorithm used to identify candidates. Please, see the MySQL reference manual about the precision, accuracy and limitations of the MySQL administrative command SHOW SLAVE STATUS. -
option_value -
Parameter value for the service level option. See also the
service_level_optionparameter.
Zwracane wartości
Returns TRUE if the connections service level
has been switched to the requested. Otherwise, returns FALSE
Notatki
Informacja:
mysqlnd_ms_set_qos() requires PHP >= 5.4.0 and PECL mysqlnd_ms >= 1.2.0. Internally, it is using a mysqlnd library C functionality not available with PHP 5.3.
Przykłady
Przykład #1 mysqlnd_ms_set_qos() example
<?php
/* Open mysqlnd_ms connection using mysqli, PDO_MySQL or mysql extension */
$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli)
/* Of course, your error handling is nicer... */
die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
/* Session consistency: read your writes */
$ret = mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_SESSION);
if (!$ret)
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
/* Will use master and return fresh data, client can see his last write */
if (!$res = $mysqli->query("SELECT item, price FROM orders WHERE order_id = 1"))
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
/* Back to default: use of all slaves and masters permitted, stale data can happen */
if (!mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL))
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
?>
Zobacz też:
- mysqlnd_ms_get_last_gtid() - Returns the latest global transaction ID
- Service level and consistency concept
- Filter concept
mysqlnd_ms_set_user_pick_server
(PECL mysqlnd_ms < 1.1.0)
mysqlnd_ms_set_user_pick_server — Sets a callback for user-defined read/write splitting
Opis
$function
)Sets a callback for user-defined read/write splitting. The plugin will call the callback only if pick[]=user is the default rule for server picking in the relevant section of the plugins configuration file.
The plugins built-in read/write query split mechanism decisions can be
overwritten in two ways. The easiest way is to prepend the query string
with the SQL hints MYSQLND_MS_MASTER_SWITCH,
MYSQLND_MS_SLAVE_SWITCH or
MYSQLND_MS_LAST_USED_SWITCH. Using SQL hints one can
control, for example, whether a query shall be send to the MySQL replication
master server or one of the slave servers. By help of SQL hints it is
not possible to pick a certain slave server for query execution.
Full control on server selection can be gained using a callback function. Use of a callback is recommended to expert users only because the callback has to cover all cases otherwise handled by the plugin.
The plugin will invoke the callback function for selecting a server from the lists of configured master and slave servers. The callback function inspects the query to run and picks a server for query execution by returning the hosts URI, as found in the master and slave list.
If the lazy connections are enabled and the callback choses a slave server for which no connection has been established so far and establishing the connection to the slave fails, the plugin will return an error upon the next action on the failed connection, for example, when running a query. It is the responsibility of the application developer to handle the error. For example, the application can re-run the query to trigger a new server selection and callback invocation. If so, the callback must make sure to select a different slave, or check slave availability, before returning to the plugin to prevent an endless loop.
Parametry
-
function -
The function to be called. Class methods may also be invoked statically using this function by passing array($classname, $methodname) to this parameter. Additionally class methods of an object instance may be called by passing array($objectinstance, $methodname) to this parameter.
Zwracane wartości
Host to run the query on. The host URI is to be taken from the master and slave connection lists passed to the callback function. If callback returns a value neither found in the master nor in the slave connection lists the plugin will fallback to the second pick method configured via the pick[] setting in the plugin configuration file. If not second pick method is given, the plugin falls back to the build-in default pick method for server selection.
Notatki
Informacja:
mysqlnd_ms_set_user_pick_server() is available with PECL mysqlnd_ms < 1.1.0. It has been replaced by the user filter. Please, check the Change History for upgrade notes.
Przykłady
Przykład #1 mysqlnd_ms_set_user_pick_server() example
[myapp] master[] = localhost slave[] = 192.168.2.27:3306 slave[] = 192.168.78.136:3306 pick[] = user
<?php
function pick_server($connected, $query, $master, $slaves, $last_used)
{
static $slave_idx = 0;
static $num_slaves = NULL;
if (is_null($num_slaves))
$num_slaves = count($slaves);
/* default: fallback to the plugins build-in logic */
$ret = NULL;
printf("User has connected to '%s'...\n", $connected);
printf("... deciding where to run '%s'\n", $query);
$where = mysqlnd_ms_query_is_select($query);
switch ($where)
{
case MYSQLND_MS_QUERY_USE_MASTER:
printf("... using master\n");
$ret = $master[0];
break;
case MYSQLND_MS_QUERY_USE_SLAVE:
/* SELECT or SQL hint for using slave */
if (stristr($query, "FROM table_on_slave_a_only"))
{
/* a table which is only on the first configured slave */
printf("... access to table available only on slave A detected\n");
$ret = $slaves[0];
}
else
{
/* round robin */
printf("... some read-only query for a slave\n");
$ret = $slaves[$slave_idx++ % $num_slaves];
}
break;
case MYSQLND_MS_QUERY_LAST_USED:
printf("... using last used server\n");
$ret = $last_used;
break;
}
printf("... ret = '%s'\n", $ret);
return $ret;
}
mysqlnd_ms_set_user_pick_server("pick_server");
$mysqli = new mysqli("myapp", "root", "root", "test");
if (!($res = $mysqli->query("SELECT 1 FROM DUAL")))
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
else
$res->close();
if (!($res = $mysqli->query("SELECT 2 FROM DUAL")))
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
else
$res->close();
if (!($res = $mysqli->query("SELECT * FROM table_on_slave_a_only")))
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
else
$res->close();
$mysqli->close();
?>
Powyższy przykład wyświetli:
User has connected to 'myapp'... ... deciding where to run 'SELECT 1 FROM DUAL' ... some read-only query for a slave ... ret = 'tcp://192.168.2.27:3306' User has connected to 'myapp'... ... deciding where to run 'SELECT 2 FROM DUAL' ... some read-only query for a slave ... ret = 'tcp://192.168.78.136:3306' User has connected to 'myapp'... ... deciding where to run 'SELECT * FROM table_on_slave_a_only' ... access to table available only on slave A detected ... ret = 'tcp://192.168.2.27:3306'
Zobacz też:
- mysqlnd_ms_query_is_select() - Find whether to send the query to the master, the slave or the last used MySQL server
- Filter concept
- user filter
Spis treści
- mysqlnd_ms_get_last_gtid — Returns the latest global transaction ID
- mysqlnd_ms_get_last_used_connection — Returns an array which describes the last used connection
- mysqlnd_ms_get_stats — Returns query distribution and connection statistics
- mysqlnd_ms_match_wild — Finds whether a table name matches a wildcard pattern or not
- mysqlnd_ms_query_is_select — Find whether to send the query to the master, the slave or the last used MySQL server
- mysqlnd_ms_set_qos — Sets the quality of service needed from the cluster
- mysqlnd_ms_set_user_pick_server — Sets a callback for user-defined read/write splitting
Change History
Spis treści
- PECL/mysqlnd_ms 1.3 series
- PECL/mysqlnd_ms 1.2 series
- PECL/mysqlnd_ms 1.1 series
- PECL/mysqlnd_ms 1.0 series
This change history is a high level summary of selected changes that may impact applications and/or break backwards compatibility.
See also the CHANGES file in the source distribution for a complete list of changes.
PECL/mysqlnd_ms 1.3 series
1.3.0-alpha
- Release dates: TBD
- Motto/theme: Query caching through quality-of-service concept
Informacja:
This is the current development series. All features are at an early stage. Changes may happen at any time without prior notice. Please, do not use this version in production environments.
The 1.3 series aims to improve the performance of applications and the overall load of an asynchronous MySQL cluster, for example, a MySQL cluster using MySQL Replication. This is done by transparently replacing a slave access with a local cache access, if the application allows it by setting an appropriate quality of service flag. When using MySQL replication a slave can serve stale data. An application using MySQL replication must continue to work correctly with stale data. Given that the application is know to work correctly with stale data, the slave access can transparently be replace with a local cache access.
PECL/mysqlnd_qc serves as a cache backend. PECL/mysqlnd_qc supports use of various storage locations, among others main memory, APC and MEMCACHE.
Feature changes
-
Added cache option to quality-of-service (QoS) filter.
- New configure option enable-mysqlnd-ms-cache-support
- New constant MYSQLND_MS_HAVE_CACHE_SUPPORT.
- New constant MYSQLND_MS_QOS_OPTION_CACHE to be used with mysqlnd_ms_set_qos().
-
Support for built-in global transaction identifier feature of MySQL 5.6.5-m8 or newer.
PECL/mysqlnd_ms 1.2 series
1.2.1-beta
- Release dates: 01/2012 (beta)
- Motto/theme: see 1.2.0-alpha
Minor test changes.
1.2.0-alpha
- Release dates: 11/2011 (alpha)
- Motto/theme: Global Transaction ID injection and quality-of-service concept
In version 1.2 the focus continues to be on supporting MySQL database clusters with asynchronous replication. The plugin tries to make using the cluster introducing a quality-of-service filter which applications can use to define what service quality they need from the cluster. Service levels provided are eventual consistency with optional maximum age/slave slag, session consistency and strong consistency.
Additionally the plugin can do client-side global transaction id injection to make manual master failover easier.
Feature changes
-
Introduced quality-of-service (QoS) filter. Service levels provided by QoS filter:
- eventual consistency, optional option slave lag
- session consistency, optional option GTID
- strong consistency
-
Added the mysqlnd_ms_set_qos() function to set the required connection quality at runtime. The new constants related to mysqlnd_ms_set_qos() are:
-
MYSQLND_MS_QOS_CONSISTENCY_STRONG -
MYSQLND_MS_QOS_CONSISTENCY_SESSION -
MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL -
MYSQLND_MS_QOS_OPTION_GTID -
MYSQLND_MS_QOS_OPTION_AGE
-
-
Added client-side global transaction id injection (GTID).
-
New statistics related to GTID:
- gtid_autocommit_injections_success
- gtid_autocommit_injections_failure
- gtid_commit_injections_success
- gtid_commit_injections_failure
- gtid_implicit_commit_injections_success
- gtid_implicit_commit_injections_failure
-
Added mysqlnd_ms_get_last_gtid() to fetch the last global transaction id.
-
Enabled support for multi master without slaves.
PECL/mysqlnd_ms 1.1 series
1.1.0
- Release date: 09/2011
- Motto/theme: Cover replication basics with production quality
The 1.1 and 1.0 series expose a similar feature set. Internally, the 1.1 series has been refactored to plan for future feature additions. A new configuration file format has been introduced, and limitations have been lifted. And the code quality and quality assurance has been improved.
Feature changes
-
Added the (chainable) filter concept:
- BC break: mysqlnd_ms_set_user_pick_server() has been removed. Thehttp://svn.php.net/viewvc/pecl/mysqlnd_ms/trunk/ user filter has been introduced to replace it. The filter offers similar functionality, but see below for an explanation of the differences.
- New powerful JSON based configuration syntax.
- Lazy connections improved: security relevant, and state changing commands are covered.
- Support for (native) prepared statements.
-
New statistics: use_master_guess, use_slave_guess.
- BC break: Semantics of statistics changed for use_slave, use_master. Future changes are likely. Please see, mysqlnd_ms_get_stats().
- List of broadcasted messages extended by ssl_set.
- Library calls now monitored to remember settings for lazy connections: change_user, select_db, set_charset, set_autocommit.
- Introduced mysqlnd_ms.disable_rw_split. The configuration setting allows using the load balancing and lazy connection functionality independently of read write splitting.
Bug fixes
- Fixed PECL #22724 - Server switching (mysqlnd_ms_query_is_select() case sensitive)
- Fixed PECL #22784 - Using mysql_connect and mysql_select_db did not work
- Fixed PECL #59982 - Unusable extension with --enable-mysqlnd-ms-table-filter. Use of the option is NOT supported. You must not used it. Added note to m4.
- Fixed Bug #60119 - host="localhost" lost in mysqlnd_ms_get_last_used_connection()
The mysqlnd_ms_set_user_pick_server() function was removed, and
replaced in favor of a new user filter. You can no longer set a
callback function using mysqlnd_ms_set_user_pick_server() at
runtime, but instead have to configure it in the plugins configuration file. The user
filter will pass the same arguments to the callback as before.
Therefore, you can continue to use the same procedural function as a callback.callback
It is no longer possible to use static class methods, or class methods of
an object instance, as a callback. Doing so will cause the function
executing a statement handled by the plugin to emit an
E_RECOVERABLE_ERROR level error, which might look like:
"(mysqlnd_ms) Specified callback (picker) is not a valid callback."
Note: this may halt your application.
PECL/mysqlnd_ms 1.0 series
1.0.1-alpha
- Release date: 04/2011
- Motto/theme: bug fix release
1.0.0-alpha
- Release date: 04/2011
- Motto/theme: Cover replication basics to test user feedback
The first release of practical use. It features basic automatic read-write splitting, SQL hints to overrule automatic redirection, load balancing of slave requests, lazy connections, and optional, automatic use of the master after the first write.
The public feature set is close to that of the 1.1 release.
1.0.0-pre-alpha
- Release date: 09/2010
- Motto/theme: Proof of concept
Initial check-in. Essentially a demo of the mysqlnd plugin API.
- Wstęp
- Quickstart and Examples
- Concepts
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Mysqlnd_ms Funkcje
- mysqlnd_ms_get_last_gtid — Returns the latest global transaction ID
- mysqlnd_ms_get_last_used_connection — Returns an array which describes the last used connection
- mysqlnd_ms_get_stats — Returns query distribution and connection statistics
- mysqlnd_ms_match_wild — Finds whether a table name matches a wildcard pattern or not
- mysqlnd_ms_query_is_select — Find whether to send the query to the master, the slave or the last used MySQL server
- mysqlnd_ms_set_qos — Sets the quality of service needed from the cluster
- mysqlnd_ms_set_user_pick_server — Sets a callback for user-defined read/write splitting
- Change History
Mysqlnd query result cache plugin
Wstęp
The mysqlnd query result cache plugin adds easy to use client-side query caching to all PHP MySQL extensions using mysqlnd.
As of version PHP 5.3.3 the MySQL native driver for PHP ( mysqlnd) features an internal plugin C API. C plugins, such as the query cache plugin, can extend the functionality of mysqlnd.
Mysqlnd plugins such as the query cache plugin operate transparent from a user perspective. The cache plugin supports all PHP applications and all PHP MySQL extensions ( mysqli, mysql, PDO_MYSQL). It does not change existing APIs.
No significant application changes are required to cache a query. The cache has two operation modes. It will either cache all queries (not recommended) or only those queries marked with a certain SQL hint (recommended).
Key Features
-
Transparent and therefore easy to use
-
supports all PHP MySQL extensions
-
no API changes
-
very little application changes required
-
-
Flexible invalidation strategy
-
Time-to-Live (TTL)
-
user-defined
-
-
Storage with different scope and life-span
-
Default (Hash, process memory)
-
MEMCACHE
-
sqlite
-
user-defined
-
-
Built-in slam defense to prevent cache stampeding.
Limitations
The current 1.0.1 release of PECL mysqlnd_qc does not support PHP 5.4. Version 1.1.0-alpha lifts this limitation.
Prepared statements and unbuffered queries are fully supported. Thus, the plugin is capable of caching all statements issued with mysqli or PDO_MySQL, which are the only two PHP MySQL APIs to offer prepared statement support.
On the name
The shortcut mysqlnd_qc stands for mysqlnd query cache plugin. The name was chosen for a quick-and-dirty proof-of-concept. In the beginning the developers did not expect to continue using the code base. Sometimes PECL/mysqlnd_qc has also been called client-side query result set cache.
Quickstart and Examples
Spis treści
- Architecture and Concepts
- Setup
- Caching queries
- Setting the TTL
- Pattern based caching
- Slam defense
- Finding cache candidates
- Measuring cache efficiency
- Beyond TTL: user-defined storage
The mysqlnd query cache plugin is easy to use. This quickstart will demo typical use-cases, and provide practical advice on getting started.
It is strongly recommended to read the reference sections in addition to the quickstart. It is safe to begin with the quickstart. However, before using the plugin in mission critical environments we urge you to read additionally the background information from the reference sections.
Most of the examples use the mysqli extension because it is the most feature complete PHP MySQL extension. However, the plugin can be used with any PHP MySQL extension that is using the mysqlnd library.
Architecture and Concepts
The query cache plugin is implemented as a PHP extension. It is written in C and operates under the hood of PHP. During the startup of the PHP interpreter, it gets registered as a mysqlnd plugin to replace selected mysqlnd C methods. Hereby, it can change the behaviour of any PHP MySQL extension (mysqli, PDO_MYSQL, mysql) compiled to use the mysqlnd library without changing the extensions API. This makes the plugin compatible with each and every PHP MySQL application. Because existing APIs are not changed, it is almost transparent to use. Please, see the mysqlnd plugin API description for a discussion of the advantages of the plugin architecture and a comparison with proxy based solutions.
Transparent to use
At PHP run time PECL/mysqlnd_qc can proxy queries send from PHP (mysqlnd) to the MySQL server. It then inspects the statement string to find whether it shall cache its results. If so, result set is cached using a storage handler and further executions of the statement are served from the cache for a user-defined period. The Time to Live (TTL) of the cache entry can either be set globally or on a per statement basis.
A statement is either cached if the plugin is instructed to cache all statements globally using a or, if the query string starts with the SQL hint (/*qc=on*/). The plugin is capable of caching any query issued by calling appropriate API calls of any of the existing PHP MySQL extensions.
Flexible storage: various storage handler
Various storage handler are supported to offer different scopes for cache entries. Different scopes allow for different degrees in sharing cache entries among clients.
-
default (built-in): process memory, scope: process, one or more web requests depending on PHP deployment model used
-
APC: shared memory, scope: single server, multiple web requests
-
SQLite: memory or file, scope: single server, multiple web requests
-
MEMCACHE: main memory, scope: single or multiple server, multiple web requests
-
user (built-in): user-defined - any, scope: user-defined - any
Support for the APC, SQLite and MEMCACHE storage handler has to be enabled at compile time. The default and user handler are built-in. It is possible to switch between compiled-in storage handlers on a per query basis at run time. However, it is recommended to pick one storage handler and use it for all cache entries.
Built-in slam defense to avoid overloading
To avoid overload situations the cache plugin has a built-in slam defense mechanism. If a popular cache entries expires many clients using the cache entries will try to refresh the cache entry. For the duration of the refresh many clients may access the database server concurrently. In the worst case, the database server becomes overloaded and it takes more and more time to refresh the cache entry, which in turn lets more and more clients try to refresh the cache entry. To prevent this from happening the plugin has a slam defense mechanism. If slam defense is enabled and the plugin detects an expired cache entry it extends the life time of the cache entry before it refreshes the cache entry. This way other concurrent accesses to the expired cache entry are still served from the cache for a certain time. The other concurrent accesses to not trigger a concurrent refresh. Ideally, the cache entry gets refreshed by the client which extended the cache entries lifespan before other clients try to refresh the cache and potentially cause an overload situation.
Unique approach to caching
PECL/mysqlnd_qc has a unique approach to caching result sets that is superior to application based cache solutions. Application based solutions first fetch a result set into PHP variables. Then, the PHP variables are serialized for storage in a persistent cache, and then unserialized when fetching. The mysqlnd query cache stores the raw wire protocol data sent from MySQL to PHP in its cache and replays it, if still valid, on a cache hit. This way, it saves an extra serialization step for a cache put that all application based solutions have to do. It can store the raw wire protocol data in the cache without having to serialize into a PHP variable first and deserializing the PHP variable for storing in the cache again.
Setup
The plugin is implemented as a PHP extension. See also the installation instructions to install the » PECL/mysqlnd_qc extension.
Compile or configure the PHP MySQL extension (mysqli, PDO_MYSQL, mysql) that you plan to use with support for the mysqlnd library. PECL/mysqlnd_qc is a plugin for the mysqlnd library. To use the plugin with any of the existing PHP MySQL extensions (APIs), the extension has to use the mysqlnd library.
Then, load the extension into PHP and activate the plugin in the PHP configuration file using the PHP configuration directive named mysqlnd_qc.enable_qc.
Przykład #1 Enabling the plugin (php.ini)
mysqlnd_qc.enable_qc=1
Caching queries
There are four ways to trigger caching of a query.
- Use of SQL hints on a per query basis
- User supplied callbacks to decide on a per query basis, for example, using mysqlnd_qc_is_select()
- mysqlnd_set_cache_condition() for rule based automatic per query decisions
- mysqlnd_qc.cache_by_default = 1 to cache all queries blindly
Use of SQL hints and mysqlnd_qc.cache_by_default = 1 are explained below. Please, refer to the function reference on mysqlnd_qc_is_select() for a description of using a callback and, mysqlnd_qc_set_cache_condition() on how to set rules for automatic caching.
A SQL hint is a SQL standards compliant comment. As a SQL comment it is ignored by the database. A statement is considered eligible for caching if it either begins with the SQL hint enabling caching or it is a SELECT statement.
An individual query which shall be cached must begin with the SQL hint /*qc=on*/. It is recommended to use the PHP constant MYSQLND_QC_ENABLE_SWITCH instead of using the string value.
-
not eligible for caching and not cached: INSERT INTO test(id) VALUES (1)
-
not eligible for caching and not cached: SHOW ENGINES
-
eligible for caching but uncached: SELECT id FROM test
-
eligible for caching and cached: /*qc=on*/SELECT id FROM test
The examples SELECT statement string is prefixed with the MYSQLND_QC_ENABLE_SWITCH SQL hint to enable caching of the statement. The SQL hint must be given at the very beginning of the statement string to enable caching.
mysqlnd_qc.enable_qc=1
<?php
/* Connect, create and populate test table */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2)");
/* Will be cached because of the SQL hint */
$start = microtime(true);
$res = $mysqli->query("/*" . MYSQLND_QC_ENABLE_SWITCH . "*/" . "SELECT id FROM test WHERE id = 1");
var_dump($res->fetch_assoc());
$res->free();
printf("Total time uncached query: %.6fs\n", microtime(true) - $start);
/* Cache hit */
$start = microtime(true);
$res = $mysqli->query("/*" . MYSQLND_QC_ENABLE_SWITCH . "*/" . "SELECT id FROM test WHERE id = 1");
var_dump($res->fetch_assoc());
$res->free();
printf("Total time cached query: %.6fs\n", microtime(true) - $start);
?>
Powyższe przykłady wyświetlą coś podobnego do:
array(1) {
["id"]=>
string(1) "1"
}
Total time uncached query: 0.000740s
array(1) {
["id"]=>
string(1) "1"
}
Total time cached query: 0.000098s
If nothing else is configured, as it is the case in the quickstart example, the plugin will use the built-in default storage handler. The default storage handler uses process memory to hold a cache entry. Depending on the PHP deployment model, a PHP process may serve one or more web requests. Please, consult the web server manual for details. Details make no difference for the examples given in the quickstart.
The query cache plugin will cache all queries regardless if the query string begins with the SQL hint which enables caching or not, if the PHP configuration directive mysqlnd_qc.cache_by_default is set to 1. The setting mysqlnd_qc.cache_by_default is evaluated by the core of the query cache plugins. Neither the built-in nor user-defined storage handler can overrule the setting.
The SQL hint /*qc=off*/ can be used to disable caching of individual queries if mysqlnd_qc.cache_by_default = 1 It is recommended to use the PHP constant MYSQLND_QC_DISABLE_SWITCH instead of using the string value.
mysqlnd_qc.enable_qc=1 mysqlnd_qc.cache_by_default=1
<?php
/* Connect, create and populate test table */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2)");
/* Will be cached although no SQL hint is present because of mysqlnd_qc.cache_by_default = 1*/
$res = $mysqli->query("SELECT id FROM test WHERE id = 1");
var_dump($res->fetch_assoc());
$res->free();
$mysqli->query("DELETE FROM test WHERE id = 1");
/* Cache hit - no automatic invalidation and still valid! */
$res = $mysqli->query("SELECT id FROM test WHERE id = 1");
var_dump($res->fetch_assoc());
$res->free();
/* Cache miss - query must not be cached because of the SQL hint */
$res = $mysqli->query("/*" . MYSQLND_QC_DISABLE_SWITCH . "*/SELECT id FROM test WHERE id = 1");
var_dump($res->fetch_assoc());
$res->free();
?>
Powyższe przykłady wyświetlą:
array(1) {
["id"]=>
string(1) "1"
}
array(1) {
["id"]=>
string(1) "1"
}
NULL
PECL/mysqlnd_qc forbids caching of statements for which at least one column from the statements result set shows no table name in its meta data by default. This is usually the case for columns originating from SQL functions such as NOW() or LAST_INSERT_ID(). The policy aims to prevent pitfalls if caching by default is used.
mysqlnd_qc.enable_qc=1 mysqlnd_qc.cache_by_default=1
<?php
/* Connect, create and populate test table */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1)");
for ($i = 0; $i < 3; $i++) {
$start = microtime(true);
/* Note: statement will not be cached because of NOW() use */
$res = $mysqli->query("SELECT id, NOW() AS _time FROM test");
$row = $res->fetch_assoc();
/* dump results */
var_dump($row);
printf("Total time: %.6fs\n", microtime(true) - $start);
/* pause one second */
sleep(1);
}
?>
Powyższe przykłady wyświetlą coś podobnego do:
array(2) {
["id"]=>
string(1) "1"
["_time"]=>
string(19) "2012-01-11 15:43:10"
}
Total time: 0.000540s
array(2) {
["id"]=>
string(1) "1"
["_time"]=>
string(19) "2012-01-11 15:43:11"
}
Total time: 0.000555s
array(2) {
["id"]=>
string(1) "1"
["_time"]=>
string(19) "2012-01-11 15:43:12"
}
Total time: 0.000549s
It is possible to enable caching for all statements including those which has columns in their result set for which MySQL reports no table, such as the statement from the example. Set mysqlnd_qc.cache_no_table = 1 to enable caching of such statements. Please, note the difference in the measured times for the above and below examples.
mysqlnd_qc.enable_qc=1 mysqlnd_qc.cache_by_default=1 mysqlnd_qc.cache_no_table=1
<?php
/* Connect, create and populate test table */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1)");
for ($i = 0; $i < 3; $i++) {
$start = microtime(true);
/* Note: statement will not be cached because of NOW() use */
$res = $mysqli->query("SELECT id, NOW() AS _time FROM test");
$row = $res->fetch_assoc();
/* dump results */
var_dump($row);
printf("Total time: %.6fs\n", microtime(true) - $start);
/* pause one second */
sleep(1);
}
?>
Powyższe przykłady wyświetlą coś podobnego do:
array(2) {
["id"]=>
string(1) "1"
["_time"]=>
string(19) "2012-01-11 15:47:45"
}
Total time: 0.000546s
array(2) {
["id"]=>
string(1) "1"
["_time"]=>
string(19) "2012-01-11 15:47:45"
}
Total time: 0.000187s
array(2) {
["id"]=>
string(1) "1"
["_time"]=>
string(19) "2012-01-11 15:47:45"
}
Total time: 0.000167s
Informacja:
Although mysqlnd_qc.cache_no_table = 1 has been created for use with mysqlnd_qc.cache_by_default = 1 it is bound it. The plugin will evaluate the mysqlnd_qc.cache_no_table whenever a query is to be cached, no matter whether caching has been enabled using a SQL hint or any other measure.
Setting the TTL
The default invalidation strategy of the query cache plugin is Time to Live (TTL). The built-in storage handlers will use the default TTL defined by the PHP configuration value mysqlnd_qc.ttl unless the query string contains a hint for setting a different TTL. The TTL is specified in seconds. By default cache entries expire after 30 seconds
The example sets mysqlnd_qc.ttl=3 to cache statements for three seconds by default. Every second it updates a database table record to hold the current time and executes a SELECT statement to fetch the record from the database. The SELECT statement is cached for three seconds because it is prefixed with the SQL hint enabling caching. The output verifies that the query results are taken from the cache for the duration of three seconds before they are refreshed.
mysqlnd_qc.enable_qc=1 mysqlnd_qc.ttl=3
<?php
/* Connect, create and populate test table */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id VARCHAR(255))");
for ($i = 0; $i < 7; $i++) {
/* update DB row */
if (!$mysqli->query("DELETE FROM test") ||
!$mysqli->query("INSERT INTO test(id) VALUES (NOW())"))
/* Of course, a real-life script should do better error handling */
die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
/* select latest row but cache results */
$query = "/*" . MYSQLND_QC_ENABLE_SWITCH . "*/";
$query .= "SELECT id AS _time FROM test";
if (!($res = $mysqli->query($query)) ||
!($row = $res->fetch_assoc()))
{
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}
$res->free();
printf("Wall time %s - DB row time %s\n", date("H:i:s"), $row['_time']);
/* pause one second */
sleep(1);
}
?>
Powyższe przykłady wyświetlą coś podobnego do:
Wall time 14:55:59 - DB row time 2012-01-11 14:55:59 Wall time 14:56:00 - DB row time 2012-01-11 14:55:59 Wall time 14:56:01 - DB row time 2012-01-11 14:55:59 Wall time 14:56:02 - DB row time 2012-01-11 14:56:02 Wall time 14:56:03 - DB row time 2012-01-11 14:56:02 Wall time 14:56:04 - DB row time 2012-01-11 14:56:02 Wall time 14:56:05 - DB row time 2012-01-11 14:56:05
As can be seen from the example, any TTL based cache can serve stale data. Cache entries are not automatically invalidated, if underlying data changes. Applications using the default TTL invalidation strategy must be able to work correctly with stale data.
A user-defined cache storage handler can implement any invalidation strategy to work around this limitation.
The default TTL can be overruled using the SQL hint /*qc_tt=seconds*/. The SQL hint must be appear immediately after the SQL hint which enables caching. It is recommended to use the PHP constant MYSQLND_QC_TTL_SWITCH instead of using the string value.
<?php
$start = microtime(true);
/* Connect, create and populate test table */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2)");
printf("Default TTL\t: %d seconds\n", ini_get("mysqlnd_qc.ttl"));
/* Will be cached for 2 seconds */
$sql = sprintf("/*%s*//*%s%d*/SELECT id FROM test WHERE id = 1", MYSQLND_QC_ENABLE_SWITCH, MYSQLND_QC_TTL_SWITCH, 2);
$res = $mysqli->query($sql);
var_dump($res->fetch_assoc());
$res->free();
$mysqli->query("DELETE FROM test WHERE id = 1");
sleep(1);
/* Cache hit - no automatic invalidation and still valid! */
$res = $mysqli->query($sql);
var_dump($res->fetch_assoc());
$res->free();
sleep(2);
/* Cache miss - cache entry has expired */
$res = $mysqli->query($sql);
var_dump($res->fetch_assoc());
$res->free();
printf("Script runtime\t: %d seconds\n", microtime(true) - $start);
?>
Powyższe przykłady wyświetlą coś podobnego do:
Default TTL : 30 seconds
array(1) {
["id"]=>
string(1) "1"
}
array(1) {
["id"]=>
string(1) "1"
}
NULL
Script runtime : 3 seconds
Pattern based caching
An application has three options for telling PECL/mysqlnd_qc whether a particular statement shall be used. The most basic approach is to cache all statements by setting mysqlnd_qc.cache_by_default = 1. This approach is often of little practical value. But it enables users to make a quick estimation about the maximum performance gains from caching. An application designed to use a cache may be able to prefix selected statements with the appropriate SQL hints. However, altering an applications source code may not always be possible or desired, for example, to avoid problems with software updates. Therefore, PECL/mysqlnd_qc allows setting a callback which decides if a query is to be cached.
The callback is installed with the mysqlnd_qc_set_is_select()
function. The callback is given the statement string of every statement
inspected by the plugin. Then, the callback can decide whether to cache
the function. The callback is supposed to return FALSE
if the statement shall not be cached. A return value of TRUE
makes the plugin try to add the statement into the cache. The cache entry
will be given the default TTL (
mysqlnd_qc.ttl). If the callback returns
a numerical value it is used as the TTL instead of the global default.
mysqlnd_qc.enable_qc=1 mysqlnd_qc.collect_statistics=1
<?php
/* callback which decides if query is cached */
function is_select($query) {
static $patterns = array(
/* true - use default from mysqlnd_qc.ttl */
"@SELECT\s+.*\s+FROM\s+test@ismU" => true,
/* 3 - use TTL = 3 seconds */
"@SELECT\s+.*\s+FROM\s+news@ismU" => 3
);
/* check if query does match pattern */
foreach ($patterns as $pattern => $ttl) {
if (preg_match($pattern, $query)) {
printf("is_select(%45s): cache\n", $query);
return $ttl;
}
}
printf("is_select(%45s): do not cache\n", $query);
return false;
}
/* install callback */
mysqlnd_qc_set_is_select("is_select");
/* Connect, create and populate test table */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");
/* cache put */
$mysqli->query("SELECT id FROM test WHERE id = 1");
/* cache hit */
$mysqli->query("SELECT id FROM test WHERE id = 1");
/* cache put */
$mysqli->query("SELECT * FROM test");
$stats = mysqlnd_qc_get_core_stats();
printf("Cache put: %d\n", $stats['cache_put']);
printf("Cache hit: %d\n", $stats['cache_hit']);
?>
Powyższe przykłady wyświetlą coś podobnego do:
is_select( DROP TABLE IF EXISTS test): do not cache is_select( CREATE TABLE test(id INT)): do not cache is_select( INSERT INTO test(id) VALUES (1), (2), (3)): do not cache is_select( SELECT id FROM test WHERE id = 1): cache is_select( SELECT id FROM test WHERE id = 1): cache is_select( SELECT * FROM test): cache Cache put: 2 Cache hit: 1
The examples callback tests if a statement string matches a pattern.
If this is the case, it either returns TRUE to cache
the statement using the global default TTL or an alternative TTL.
To minimize application changes the callback can put into and registered in an auto prepend file.
Slam defense
A badly designed cache can do more harm than good. In the worst case a cache can increase database server load instead of minimizing it. An overload situation can occur if a highly shared cache entry expires (cache stampeding).
Cache entries are shared and reused to a different degree depending on the storage used. The default storage handler stores cache entries in process memory. Thus, a cache entry can be reused for the life-span of a process. Other PHP processes cannot access it. If Memcache is used, a cache entry can be shared among multiple PHP processes and even among multiple machines, depending on the set up being used.
If a highly shared cache entry stored, for example, in Memcache expires, many clients gets a cache miss. Many client requests can no longer be served from the cache but try to run the underlying query on the database server. Until the cache entry is refreshed, more and more clients contact the database server. In the worst case, a total lost of service is the result.
The overload can be avoided using a storage handler which limits the reuse of cache entries to few clients. Then, at the average, its likely that only a limited number of clients will try to refresh a cache entry concurrently.
Additionally, the built-in slam defense mechanism can and should be used. If slam defense is activated an expired cache entry is given an extended life time. The first client getting a cache miss for the expired cache entry tries to refresh the cache entry within the extended life time. All other clients requesting the cache entry are temporarily served from the cache although the original TTL of the cache entry has expired. The other clients will not experience a cache miss before the extended life time is over.
mysqlnd_qc.slam_defense=1 mysqlnd_qc.slam_defense_ttl=1
The slam defense mechanism is enabled with the PHP configuration directive mysqlnd_qc.slam_defense. The extended life time of a cache entry is set with mysqlnd_qc.slam_defense_ttl.
The function mysqlnd_qc_get_core_stats() returns an array of statistics. The statistics slam_stale_refresh and slam_stale_hit are incremented if slam defense takes place.
It is not possible to give a one-fits-all recommendation on the slam defense configuration. Users are advised to monitor and test their setup and derive settings accordingly.
Finding cache candidates
A statement should be considered for caching if it is executed often and has a long run time. Cache candidates are found by creating a list of statements sorted by the product of the number of executions multiplied by the statements run time. The function mysqlnd_qc_get_query_trace_log() returns a query log which help with the task.
Collecting a query trace is a slow operation. Thus, it is disabled by default. The PHP configuration directive mysqlnd_qc.collect_query_trace is used to enable it. The functions trace contains one entry for every query issued before the function is called.
mysqlnd_qc.enable_qc=1 mysqlnd_qc.collect_query_trace=1
<?php
/* connect to MySQL */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
/* dummy queries to fill the query trace */
for ($i = 0; $i < 2; $i++) {
$res = $mysqli->query("SELECT 1 AS _one FROM DUAL");
$res->free();
}
/* dump trace */
var_dump(mysqlnd_qc_get_query_trace_log());
?>
Powyższe przykłady wyświetlą:
array(2) {
[0]=>
array(8) {
["query"]=>
string(26) "SELECT 1 AS _one FROM DUAL"
["origin"]=>
string(102) "#0 qc.php(7): mysqli->query('SELECT 1 AS _on...')
#1 {main}"
["run_time"]=>
int(0)
["store_time"]=>
int(25)
["eligible_for_caching"]=>
bool(false)
["no_table"]=>
bool(false)
["was_added"]=>
bool(false)
["was_already_in_cache"]=>
bool(false)
}
[1]=>
array(8) {
["query"]=>
string(26) "SELECT 1 AS _one FROM DUAL"
["origin"]=>
string(102) "#0 qc.php(7): mysqli->query('SELECT 1 AS _on...')
#1 {main}"
["run_time"]=>
int(0)
["store_time"]=>
int(8)
["eligible_for_caching"]=>
bool(false)
["no_table"]=>
bool(false)
["was_added"]=>
bool(false)
["was_already_in_cache"]=>
bool(false)
}
}
Assorted information is given in the trace. Among them timings and the origin of the query call. The origin property holds a code backtrace to identify the source of the query. The depth of the backtrace can be limited with the PHP configuration directive mysqlnd_qc.query_trace_bt_depth. The default depth is 3.
mysqlnd_qc.enable_qc=1 mysqlnd_qc.collect_query_trace=1
<?php
/* connect to MySQL */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");
/* dummy queries to fill the query trace */
for ($i = 0; $i < 3; $i++) {
$res = $mysqli->query("SELECT id FROM test WHERE id = " . $mysqli->real_escape_string($i));
$res->free();
}
$trace = mysqlnd_qc_get_query_trace_log();
$summary = array();
foreach ($trace as $entry) {
if (!isset($summary[$entry['query']])) {
$summary[$entry['query']] = array(
"executions" => 1,
"time" => $entry['run_time'] + $entry['store_time'],
);
} else {
$summary[$entry['query']]['executions']++;
$summary[$entry['query']]['time'] += $entry['run_time'] + $entry['store_time'];
}
}
foreach ($summary as $query => $details) {
printf("%45s: %5dms (%dx)\n",
$query, $details['time'], $details['executions']);
}
?>
Powyższe przykłady wyświetlą coś podobnego do:
DROP TABLE IF EXISTS test: 0ms (1x)
CREATE TABLE test(id INT): 0ms (1x)
INSERT INTO test(id) VALUES (1), (2), (3): 0ms (1x)
SELECT id FROM test WHERE id = 0: 25ms (1x)
SELECT id FROM test WHERE id = 1: 10ms (1x)
SELECT id FROM test WHERE id = 2: 9ms (1x)
Measuring cache efficiency
PECL/mysqlnd_qc offers three ways to measure the cache efficiency. The function mysqlnd_qc_get_normalized_query_trace_log() returns statistics aggregated by the normalized query string, mysqlnd_qc_get_cache_info() gives storage handler specific information which includes a list of all cached items, depending on the storage handler. Additionally, the core of PECL/mysqlnd_qc collects high-level summary statistics aggregated per PHP process. The high-level statistics are returned by mysqlnd_qc_get_core_stats().
The functions mysqlnd_qc_get_normalized_query_trace_log() and mysqlnd_qc_get_core_stats() will not collect data unless data collection has been enabled through their corresponding PHP configuration directives. Data collection is disabled by default for performance considerations. It is configurable with the >mysqlnd_qc.time_statistics option, which determines if timing information should be collected. Collection of time statistics is enabled by default but only performed if data collection as such has been enabled. Recording time statistics causes extra system calls. In most cases, the benefit of the monitoring outweighs any potential performance penalty of the additional system calls.
mysqlnd_qc.enable_qc=1 mysqlnd_qc.collect_statistics=1
<?php
/* connect to MySQL */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");
/* dummy queries */
for ($i = 1; $i <= 4; $i++) {
$query = sprintf("/*%s*/SELECT id FROM test WHERE id = %d", MYSQLND_QC_ENABLE_SWITCH, $i % 2);
$res = $mysqli->query($query);
$res->free();
}
var_dump(mysqlnd_qc_get_core_stats());
?>
Powyższe przykłady wyświetlą coś podobnego do:
array(26) {
["cache_hit"]=>
string(1) "2"
["cache_miss"]=>
string(1) "2"
["cache_put"]=>
string(1) "2"
["query_should_cache"]=>
string(1) "4"
["query_should_not_cache"]=>
string(1) "3"
["query_not_cached"]=>
string(1) "3"
["query_could_cache"]=>
string(1) "4"
["query_found_in_cache"]=>
string(1) "2"
["query_uncached_other"]=>
string(1) "0"
["query_uncached_no_table"]=>
string(1) "0"
["query_uncached_no_result"]=>
string(1) "0"
["query_uncached_use_result"]=>
string(1) "0"
["query_aggr_run_time_cache_hit"]=>
string(2) "28"
["query_aggr_run_time_cache_put"]=>
string(3) "900"
["query_aggr_run_time_total"]=>
string(3) "928"
["query_aggr_store_time_cache_hit"]=>
string(2) "14"
["query_aggr_store_time_cache_put"]=>
string(2) "40"
["query_aggr_store_time_total"]=>
string(2) "54"
["receive_bytes_recorded"]=>
string(3) "136"
["receive_bytes_replayed"]=>
string(3) "136"
["send_bytes_recorded"]=>
string(2) "84"
["send_bytes_replayed"]=>
string(2) "84"
["slam_stale_refresh"]=>
string(1) "0"
["slam_stale_hit"]=>
string(1) "0"
["request_counter"]=>
int(1)
["process_hash"]=>
int(1929695233)
}
For a quick overview, call mysqlnd_qc_get_core_stats(). It delivers cache usage, cache timing and traffic related statistics. Values are aggregated on a per process basis for all queries issued by any PHP MySQL API call.
Some storage handler, such as the default handler, can report cache entries, statistics related to the entries and meta data for the underlying query through the mysqlnd_qc_get_cache_info() function. Please note, that the information returned depends on the storage handler. Values are aggregated on a per process basis.
mysqlnd_qc.enable_qc=1
<?php
/* connect to MySQL */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");
/* dummy queries to fill the query trace */
for ($i = 1; $i <= 4; $i++) {
$query = sprintf("/*%s*/SELECT id FROM test WHERE id = %d", MYSQLND_QC_ENABLE_SWITCH, $i % 2);
$res = $mysqli->query($query);
$res->free();
}
var_dump(mysqlnd_qc_get_cache_info());
?>
Powyższe przykłady wyświetlą coś podobnego do:
array(4) {
["num_entries"]=>
int(2)
["handler"]=>
string(7) "default"
["handler_version"]=>
string(5) "1.0.0"
["data"]=>
array(2) {
["Localhost via UNIX socket
3306
root
test|/*qc=on*/SELECT id FROM test WHERE id = 1"]=>
array(2) {
["statistics"]=>
array(11) {
["rows"]=>
int(1)
["stored_size"]=>
int(71)
["cache_hits"]=>
int(1)
["run_time"]=>
int(391)
["store_time"]=>
int(27)
["min_run_time"]=>
int(16)
["max_run_time"]=>
int(16)
["min_store_time"]=>
int(8)
["max_store_time"]=>
int(8)
["avg_run_time"]=>
int(8)
["avg_store_time"]=>
int(4)
}
["metadata"]=>
array(1) {
[0]=>
array(8) {
["name"]=>
string(2) "id"
["orig_name"]=>
string(2) "id"
["table"]=>
string(4) "test"
["orig_table"]=>
string(4) "test"
["db"]=>
string(4) "test"
["max_length"]=>
int(1)
["length"]=>
int(11)
["type"]=>
int(3)
}
}
}
["Localhost via UNIX socket
3306
root
test|/*qc=on*/SELECT id FROM test WHERE id = 0"]=>
array(2) {
["statistics"]=>
array(11) {
["rows"]=>
int(0)
["stored_size"]=>
int(65)
["cache_hits"]=>
int(1)
["run_time"]=>
int(299)
["store_time"]=>
int(13)
["min_run_time"]=>
int(11)
["max_run_time"]=>
int(11)
["min_store_time"]=>
int(6)
["max_store_time"]=>
int(6)
["avg_run_time"]=>
int(5)
["avg_store_time"]=>
int(3)
}
["metadata"]=>
array(1) {
[0]=>
array(8) {
["name"]=>
string(2) "id"
["orig_name"]=>
string(2) "id"
["table"]=>
string(4) "test"
["orig_table"]=>
string(4) "test"
["db"]=>
string(4) "test"
["max_length"]=>
int(0)
["length"]=>
int(11)
["type"]=>
int(3)
}
}
}
}
}
It is possible to further break down the granularity of statistics to the level of the normalized statement string. The normalized statement string is the statements string with all parameters replaced with question marks. For example, the two statements SELECT id FROM test WHERE id = 0 and SELECT id FROM test WHERE id = 1 are normalized into SELECT id FROM test WHERE id = ?. Their both statistics are aggregated into one entry for SELECT id FROM test WHERE id = ?.
mysqlnd_qc.enable_qc=1 mysqlnd_qc.collect_normalized_query_trace=1
<?php
/* connect to MySQL */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");
/* dummy queries to fill the query trace */
for ($i = 1; $i <= 4; $i++) {
$query = sprintf("/*%s*/SELECT id FROM test WHERE id = %d", MYSQLND_QC_ENABLE_SWITCH, $i % 2);
$res = $mysqli->query($query);
$res->free();
}
var_dump(mysqlnd_qc_get_normalized_query_trace_log());
?>
Powyższe przykłady wyświetlą coś podobnego do:
array(4) {
[0]=>
array(9) {
["query"]=>
string(25) "DROP TABLE IF EXISTS test"
["occurences"]=>
int(0)
["eligible_for_caching"]=>
bool(false)
["avg_run_time"]=>
int(0)
["min_run_time"]=>
int(0)
["max_run_time"]=>
int(0)
["avg_store_time"]=>
int(0)
["min_store_time"]=>
int(0)
["max_store_time"]=>
int(0)
}
[1]=>
array(9) {
["query"]=>
string(27) "CREATE TABLE test (id INT )"
["occurences"]=>
int(0)
["eligible_for_caching"]=>
bool(false)
["avg_run_time"]=>
int(0)
["min_run_time"]=>
int(0)
["max_run_time"]=>
int(0)
["avg_store_time"]=>
int(0)
["min_store_time"]=>
int(0)
["max_store_time"]=>
int(0)
}
[2]=>
array(9) {
["query"]=>
string(46) "INSERT INTO test (id ) VALUES (? ), (? ), (? )"
["occurences"]=>
int(0)
["eligible_for_caching"]=>
bool(false)
["avg_run_time"]=>
int(0)
["min_run_time"]=>
int(0)
["max_run_time"]=>
int(0)
["avg_store_time"]=>
int(0)
["min_store_time"]=>
int(0)
["max_store_time"]=>
int(0)
}
[3]=>
array(9) {
["query"]=>
string(31) "SELECT id FROM test WHERE id =?"
["occurences"]=>
int(4)
["eligible_for_caching"]=>
bool(true)
["avg_run_time"]=>
int(179)
["min_run_time"]=>
int(11)
["max_run_time"]=>
int(393)
["avg_store_time"]=>
int(12)
["min_store_time"]=>
int(7)
["max_store_time"]=>
int(25)
}
}
The source distribution of PECL/mysqlnd_qc contains a directory web/ in which web based monitoring scripts can be found which give an example how to write a cache monitor. Please, follow the instructions given in the source.
Since PECL/mysqlnd_qc 1.1.0 it is possible to write statistics into a log file. Please, see mysqlnd_qc.collect_statistics_log_file.
Beyond TTL: user-defined storage
The query cache plugin supports the use of user-defined storage handler. User-defined storage handler can use arbitrarily complex invalidation algorithms and support arbitrary storage media.
All user-defined storage handlers have to provide a certain interface. The functions of the user-defined storage handler will be called by the core of the cache plugin. The necessary interface consists of seven public functions. Both procedural and object oriented user-defined storage handler must implement the same set of functions.
Please check the example for details.
<?php
/* Enable default caching of all statements */
ini_set("mysqlnd_qc.cache_by_default", 1);
/* Procedural user defined storage handler functions */
$__cache = array();
function get_hash($host_info, $port, $user, $db, $query) {
global $__cache;
printf("\t%s(%d)\n", __FUNCTION__, func_num_args());
return md5(sprintf("%s%s%s%s%s", $host_info, $port, $user, $db, $query));
}
function find_query_in_cache($key) {
global $__cache;
printf("\t%s(%d)\n", __FUNCTION__, func_num_args());
if (isset($__cache[$key])) {
$tmp = $__cache[$key];
if ($tmp["valid_until"] < time()) {
unset($__cache[$key]);
$ret = NULL;
} else {
$ret = $__cache[$key]["data"];
}
} else {
$ret = NULL;
}
return $ret;
}
function return_to_cache($key) {
/*
Called on cache hit after cached data has been processed,
may be used for reference counting
*/
printf("\t%s(%d)\n", __FUNCTION__, func_num_args());
}
function add_query_to_cache_if_not_exists($key, $data, $ttl, $run_time, $store_time, $row_count) {
global $__cache;
printf("\t%s(%d)\n", __FUNCTION__, func_num_args());
$__cache[$key] = array(
"data" => $data,
"row_count" => $row_count,
"valid_until" => time() + $ttl,
"hits" => 0,
"run_time" => $run_time,
"store_time" => $store_time,
"cached_run_times" => array(),
"cached_store_times" => array(),
);
return TRUE;
}
function query_is_select($query) {
printf("\t%s('%s'): ", __FUNCTION__, $query);
$ret = FALSE;
if (stristr($query, "SELECT") !== FALSE) {
/* cache for 5 seconds */
$ret = 5;
}
printf("%s\n", (FALSE === $ret) ? "FALSE" : $ret);
return $ret;
}
function update_query_run_time_stats($key, $run_time, $store_time) {
global $__cache;
printf("\t%s(%d)\n", __FUNCTION__, func_num_args());
if (isset($__cache[$key])) {
$__cache[$key]['hits']++;
$__cache[$key]["cached_run_times"][] = $run_time;
$__cache[$key]["cached_store_times"][] = $store_time;
}
}
function get_stats($key = NULL) {
global $__cache;
printf("\t%s(%d)\n", __FUNCTION__, func_num_args());
if ($key && isset($__cache[$key])) {
$stats = $__cache[$key];
} else {
$stats = array();
foreach ($__cache as $key => $details) {
$stats[$key] = array(
'hits' => $details['hits'],
'bytes' => strlen($details['data']),
'uncached_run_time' => $details['run_time'],
'cached_run_time' => (count($details['cached_run_times']))
? array_sum($details['cached_run_times']) / count($details['cached_run_times'])
: 0,
);
}
}
return $stats;
}
function clear_cache() {
global $__cache;
printf("\t%s(%d)\n", __FUNCTION__, func_num_args());
$__cache = array();
return TRUE;
}
/* Install procedural user-defined storage handler */
if (!mysqlnd_qc_set_user_handlers("get_hash", "find_query_in_cache",
"return_to_cache", "add_query_to_cache_if_not_exists",
"query_is_select", "update_query_run_time_stats", "get_stats", "clear_cache")) {
printf("Failed to install user-defined storage handler\n");
}
/* Connect, create and populate test table */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2)");
printf("\nCache put/cache miss\n");
$res = $mysqli->query("SELECT id FROM test WHERE id = 1");
var_dump($res->fetch_assoc());
$res->free();
/* Delete record to verify we get our data from the cache */
$mysqli->query("DELETE FROM test WHERE id = 1");
printf("\nCache hit\n");
$res = $mysqli->query("SELECT id FROM test WHERE id = 1");
var_dump($res->fetch_assoc());
$res->free();
printf("\nDisplay cache statistics\n");
var_dump(mysqlnd_qc_get_cache_info());
printf("\nFlushing cache, cache put/cache miss");
var_dump(mysqlnd_qc_clear_cache());
$res = $mysqli->query("SELECT id FROM test WHERE id = 1");
var_dump($res->fetch_assoc());
$res->free();
?>
Powyższe przykłady wyświetlą coś podobnego do:
query_is_select('DROP TABLE IF EXISTS test'): FALSE
query_is_select('CREATE TABLE test(id INT)'): FALSE
query_is_select('INSERT INTO test(id) VALUES (1), (2)'): FALSE
Cache put/cache miss
query_is_select('SELECT id FROM test WHERE id = 1'): 5
get_hash(5)
find_query_in_cache(1)
add_query_to_cache_if_not_exists(6)
array(1) {
["id"]=>
string(1) "1"
}
query_is_select('DELETE FROM test WHERE id = 1'): FALSE
Cache hit
query_is_select('SELECT id FROM test WHERE id = 1'): 5
get_hash(5)
find_query_in_cache(1)
return_to_cache(1)
update_query_run_time_stats(3)
array(1) {
["id"]=>
string(1) "1"
}
Display cache statistics
get_stats(0)
array(4) {
["num_entries"]=>
int(1)
["handler"]=>
string(4) "user"
["handler_version"]=>
string(5) "1.0.0"
["data"]=>
array(1) {
["18683c177dc89bb352b29965d112fdaa"]=>
array(4) {
["hits"]=>
int(1)
["bytes"]=>
int(71)
["uncached_run_time"]=>
int(398)
["cached_run_time"]=>
int(4)
}
}
}
Flushing cache, cache put/cache miss clear_cache(0)
bool(true)
query_is_select('SELECT id FROM test WHERE id = 1'): 5
get_hash(5)
find_query_in_cache(1)
add_query_to_cache_if_not_exists(6)
NULL
Instalacja/Konfiguracja
Spis treści
Wymagania
PHP 5.3.3 or a newer version of PHP 5.3. PHP 5.4.0 is not yet supported.
PECL/mysqlnd_qc is a mysqlnd plugin. It plugs into the mysqlnd library. To use you plugin with a PHP MySQL extension (mysqli, mysql, PDO_MYSQL) it is necessary to enable use of the mysqlnd library by the PHP MySQL extension in question. Please refer to the extensions manual sections for details.
For using APC storage handler: APC 3.1.3p1-beta or newer.
For using MEMCACHE storage handler: libmemcache 0.38 or newer.
For using sqlite storage handler: sqlite3 bundled with PHP.
Instalacja
To rozszerzenie » PECL nie jest dołączane do PHP.
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/mysqlnd_qc
DLL z tym rozszerzeniem PECL można pobrać zarówno ze strony » PHP Downloads lub z » http://pecl4win.php.net/
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| mysqlnd_qc.enable_qc | 1 | PHP_INI_SYSTEM | |
| mysqlnd_qc.ttl | 30 | PHP_INI_ALL | |
| mysqlnd_qc.cache_by_default | 0 | PHP_INI_ALL | |
| mysqlnd_qc.cache_no_table | 0 | PHP_INI_ALL | |
| mysqlnd_qc.use_request_time | 0 | PHP_INI_ALL | |
| mysqlnd_qc.time_statistics | 1 | PHP_INI_ALL | |
| mysqlnd_qc.collect_statistics | 0 | PHP_INI_ALL | |
| mysqlnd_qc.collect_statistics_log_file | /tmp/mysqlnd_qc.stats | PHP_INI_SYSTEM | |
| mysqlnd_qc.collect_query_trace | 0 | PHP_INI_SYSTEM | |
| mysqlnd_qc.query_trace_bt_depth | 3 | PHP_INI_SYSTEM | |
| mysqlnd_qc.collect_normalized_query_trace | 0 | PHP_INI_SYSTEM | |
| mysqlnd_qc.ignore_sql_comments | 1 | PHP_INI_ALL | |
| mysqlnd_qc.slam_defense | 0 | PHP_INI_SYSTEM | |
| mysqlnd_qc.slam_defense_ttl | 30 | PHP_INI_SYSTEM | |
| mysqlnd_qc.std_data_copy | 0 | PHP_INI_SYSTEM | |
| mysqlnd_qc.apc_prefix | qc_ | PHP_INI_ALL | |
| mysqlnd_qc.memc_server | 127.0.0.1 | PHP_INI_ALL | |
| mysqlnd_qc.memc_port | 11211 | PHP_INI_ALL | |
| mysqlnd_qc.sqlite_data_file | :memory: | PHP_INI_ALL |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
mysqlnd_qc.enable_qcinteger -
Enables or disables the plugin. If disabled the extension will not plug into mysqlnd to proxy internal mysqlnd C API calls.
-
mysqlnd_qc.ttlinteger -
Default Time-to-Live (TTL) for cache entries in seconds.
-
mysqlnd_qc.cache_by_defaultinteger -
Cache all queries regardless if they begin with the SQL hint that enables caching of a query or not. Storage handler cannot overrule the setting. It is evaluated by the core of the plugin.
-
mysqlnd_qc.cache_no_tableinteger -
Whether to cache queries with no table name in any of columns meta data of their result set, for example, SELECT SLEEP(1), SELECT NOW(), SELECT SUBSTRING().
-
mysqlnd_qc.use_request_timeinteger -
Use PHP global request time to avoid gettimeofday() system calls? If using APC storage handler it should be set to the value of apc.use_request_time , if not warnings will be generated.
-
mysqlnd_qc.time_statisticsinteger -
Collect run time and store time statistics using gettimeofday() system call? Data will be collected only if you also set mysqlnd_qc.collect_statistics = 1,
-
mysqlnd_qc.collect_statisticsinteger -
Collect statistics for mysqlnd_qc_get_core_stats()? Does not influence storage handler statistics! Handler statistics can be an integral part of the handler internal storage format. Thereofore, collection of some handler statistics cannot be disabled.
-
mysqlnd_qc.collect_statistics-log-fileinteger -
If mysqlnd_qc.collect_statistics and mysqlnd_qc.collect_statistics_log_file are set, the plugin will dump statistics into the specified log file at every 10th web request during PHP request shutdown. The log file needs to be writeable by the web server user.
Since 1.1.0.
-
mysqlnd_qc.collect_query_traceinteger -
Collect query back traces?
-
mysqlnd_qc.query_trace_bt_depthinteger -
Maximum depth/level of a query code backtrace.
-
mysqlnd_qc.ignore_sql_commentsinteger -
Whether to remove SQL comments from a query string before hashing it to generate a cache key. Disable if you do not want two statemts such as SELECT /*my_source_ip=123*/ id FROM test and SELECT /*my_source_ip=456*/ id FROM test to refer to the same cache entry.
Since 1.1.0.
-
mysqlnd_qc.slam_defenseinteger -
Activates handler based slam defense (cache stampeding protection) if available. Supported by Default and APC storage handler
-
mysqlnd_qc.slam_defense_ttlinteger -
TTL for stale cache entries which are served while another client updates the entries. Supported by APC storage handler.
-
mysqlnd_qc.collect_normalized_query_traceinteger -
Collect aggregated normalized query traces? The setting has no effect by default. You compile the extension using the define NORM_QUERY_TRACE_LOG to make use of the setting.
-
mysqlnd_qc.std_data_copyinteger -
Default storage handler: copy cached wire data? EXPERIMENTAL – use default setting!
-
mysqlnd_qc.apc_prefixstring -
The APC storage handler stores data in the APC user cache. The setting sets a prefix to be used for cache entries.
-
mysqlnd_qc.memc_serverstring -
MEMCACHE storage handler: memcache server host.
-
mysqlnd_qc.memc_portinteger -
MEMCACHE storage handler: memcached server port.
-
mysqlnd_qc.sqlite_data_filestring -
sqlite storage handler: data file. Any setting but :memory: may be of little practical value.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
SQL hint related
The query cache is controlled by SQL hints. SQL hints are used to enable and disable caching. SQL hints can be used to set the TTL of a query.
The SQL hints recognized by the query cache can be manually changed at compile time. This makes it possible to use mysqlnd_qc in environments in which the default SQL hints are already taken and interpreted by other systems. Therefore it is recommended to use the SQL hint string constants instead of manually adding the default SQL hints to the query string.
<?php
/* Use constants for maximum portability */
$query = "/*" . MYSQLND_QC_ENABLE_SWITCH . "*/SELECT id FROM test";
/* Valid but less portable: default TTL */
$query = "/*qc=on*/SELECT id FROM test";
/* Valid but less portable: per statement TTL */
$query = "/*qc=on*//*qc_ttl=5*/SELECT id FROM test";
printf("MYSQLND_QC_ENABLE_SWITCH: %s\n", MYSQLND_QC_ENABLE_SWITCH);
printf("MYSQLND_QC_DISABLE_SWITCH: %s\n", MYSQLND_QC_DISABLE_SWITCH);
printf("MYSQLND_QC_TTL_SWITCH: %s\n", MYSQLND_QC_TTL_SWITCH);
?>
Powyższe przykłady wyświetlą:
MYSQLND_QC_ENABLE_SWITCH: qc=on MYSQLND_QC_DISABLE_SWITCH: qc=off MYSQLND_QC_TTL_SWITCH: qc_ttl=
-
MYSQLND_QC_ENABLE_SWITCH(string) - SQL hint used to enable caching of a query.
-
MYSQLND_QC_DISABLE_SWITCH(string) - SQL hint used to disable caching of a query if mysqlnd_qc.cache_by_default = 1.
-
MYSQLND_QC_TTL_SWITCH(string) - SQL hint used to set the TTL of a result set.
-
MYSQLND_QC_SERVER_ID_SWITCH(string) - This SQL hint should not be used in general. It is needed by PECL/mysqlnd_ms to group cache entries for one statement but originating from different physical connections. If the hint is used connection settings such as user, hostname and charset are not considered for generating a cache key of a query. Instead the given value and the query string are used as input to the hashing function that generates the key. PECL/mysqlnd_ms may, if instructed, cache results from MySQL Replication slaves. Because it can hold many connections to the slave the cache key shall not be formed from the user, hostname or other settings that may vary for the various slave connections. Instead, PECL/mysqlnd_ms provides an identifier which refers to the group of slave connections that shall be enabled to share cache entries no matter which physical slave connection was to generate the cache entry. Use of this feature outside of PECL/mysqlnd_ms is not recommended.
mysqlnd_qc_set_cache_condition() related
The function mysqlnd_qc_set_cache_condition() allows setting conditions for automatic caching of statements which don't begin with the SQL hints necessary to manually enable caching.
<?php
/* Cache all accesses to tables with the name "new%" in schema/database "db_example" for 1 second */
if (!mysqlnd_qc_set_cache_condition(MYSQLND_QC_CONDITION_META_SCHEMA_PATTERN, "db_example.new%", 1)) {
die("Failed to set cache condition!");
}
$mysqli = new mysqli("host", "user", "password", "db_example", "port");
/* cached although no SQL hint given */
$mysqli->query("SELECT id, title FROM news");
$pdo_mysql = new PDO("mysql:host=host;dbname=db_example;port=port", "user", "password");
/* not cached: no SQL hint, no pattern match */
$pdo_mysql->query("SELECT id, title FROM latest_news");
/* cached: TTL 1 second, pattern match */
$pdo_mysql->query("SELECT id, title FROM news");
?>
-
MYSQLND_QC_CONDITION_META_SCHEMA_PATTERN(int) - Used as a parameter of mysqlnd_qc_set_cache_condition() to set conditions for schema based automatic caching.
mysqlnd_qc Funkcje
mysqlnd_qc_clear_cache
(PECL mysqlnd_qc >= 1.0.0)
mysqlnd_qc_clear_cache — Flush all cache contents
Opis
Flush all cache contents.
Flushing the cache is a storage handler responsibility. All built-in storage handler but the memcache storage handler support flushing the cache. The memcache storage handler cannot flush its cache contents.
User-defined storage handler may or may not support the operation.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
A return value of
FALSE
indicates that flushing all cache contents has
failed or the operation is not supported by
the active storage handler. Applications must
not expect that calling the function will always
flush the cache.
mysqlnd_qc_get_available_handlers
(PECL mysqlnd_qc >= 1.0.0)
mysqlnd_qc_get_available_handlers — Returns a list of available storage handler
Opis
Which storage are available depends on the compile time configuration of the query cache plugin. The default storage handler is always available. All other storage handler must be enabled explicitly when building the extension.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns an array of available built-in storage handler. For each storage handler the version number and version string is given.
Przykłady
<?php
var_dump(mysqlnd_qc_get_available_handlers());
?>
Powyższe przykłady wyświetlą:
array(5) {
["default"]=>
array(2) {
["version"]=>
string(5) "1.0.0"
["version_number"]=>
int(100000)
}
["user"]=>
array(2) {
["version"]=>
string(5) "1.0.0"
["version_number"]=>
int(100000)
}
["APC"]=>
array(2) {
["version"]=>
string(5) "1.0.0"
["version_number"]=>
int(100000)
}
["MEMCACHE"]=>
array(2) {
["version"]=>
string(5) "1.0.0"
["version_number"]=>
int(100000)
}
["sqlite"]=>
array(2) {
["version"]=>
string(5) "1.0.0"
["version_number"]=>
int(100000)
}
}
mysqlnd_qc_get_cache_info
(PECL mysqlnd_qc >= 1.0.0)
mysqlnd_qc_get_cache_info — Returns information on the current handler, the number of cache entries and cache entries, if available
Opis
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns information on the current handler, the number of cache entries and cache entries, if available. If and what data will be returned for the cache entries is subject to the active storage handler. Storage handler are free to return any data. Storage handler are recommended to return at least the data provided by the default handler, if technically possible.
The scope of the information is the PHP process. Dependng on the PHP deployment model a process may serve one or more web requests.
Values are aggregated for all cache activities on a per storage handler basis. It is not possible to tell how much queries originating from mysqli, PDO_MySQL or mysql.API calls have contributed to the aggregated data values. Use mysqlnd_qc_get_core_stats() to get timing data aggregated for all storage handlers.
Array of cache information
-
handlerstring -
The active storage handler.
All storage handler. Since 1.0.0.
-
handler_versionstring -
The version of the active storage handler.
All storage handler. Since 1.0.0.
-
num_entriesint -
The number of cache entries. The value depends on the storage handler in use.
The default, APC and SQLite storage handler provide the actual number of cache entries.
The MEMCACHE storage handler always returns 0. MEMCACHE does not support counting the number of cache entries.
If a user defined handler is used, the number of entries of the data property is reported.
Since 1.0.0.
-
dataarray -
The version of the active storage handler.
Additional storage handler dependent data on the cache entries. Storage handler are requested to provide similar and comparable information. A user defined storage handler is free to return any data.
Since 1.0.0.
The following information is provided by the default storage handler for the data property.
The data property holds a hash. The hash is indexed by the internal cache entry itentifier of the storage handler. The cache entry identifier is human-readable and contains the query string leading to the cache entry. Please, see also the example below. The following data is given for every cache entry.
-
statisticsarray -
Statistics of the cache entry.
Since 1.0.0.
Property Description Version rows Number of rows of the cached result set. Since 1.0.0. stored_size The size of the cached result set in bytes. This is the size of the payload. The value is not suited for caclculating the total memory consumption of all cache entries including the administrative overhead of the cache entries. Since 1.0.0. cache_hits How often the cached entry has been returned. Since 1.0.0. run_time Run time of the statement to which the cache entry belongs. This is the run time of the uncached statement. It is the time between sending the statement to MySQL receiving a reply from MySQL. Run time saved by using the query cache plugin can be calculated like this: cache_hits * ((run_time - avg_run_time) + (store_time - avg_store_time)). Since 1.0.0. store_time Store time of the statements result set to which the cache entry belongs. This is the time it took to fetch and store the results of the uncached statement. Since 1.0.0. min_run_time Minimun run time of the cached statement. How long it took to find the statement in the cache. Since 1.0.0. min_store_time Minimun store time of the cached statement. The time taken for fetching the cached result set from the storage medium and decoding Since 1.0.0. avg_run_time Average run time of the cached statement. Since 1.0.0. avg_store_time Average store time of the cached statement. Since 1.0.0. max_run_time Average run time of the cached statement. Since 1.0.0. max_store_time Average store time of the cached statement. Since 1.0.0. valid_until Timestamp when the cache entry expires. Since 1.1.0. -
metadataarray -
Metadata of the cache entry. This is the metadata provided by MySQL together with the result set of the statement in question. Different versions of the MySQL server may return different metadata. Unlike with some of the PHP MySQL extensions no attempt is made to hide MySQL server version dependencies and version details from the caller. Please, refer to the MySQL C API documentation that belongs to the MySQL server in use for further details.
The metadata list contains one entry for every column.
Since 1.0.0.
Property Description Version name The field name. Depending on the MySQL version this may be the fields alias name. Since 1.0.0. org_name The field name. Since 1.0.0. table The table name. If an alias name was used for the table, this usually holds the alias name. Since 1.0.0. org_table The table name. Since 1.0.0. db The database/schema name. Since 1.0.0. max_length The maximum width of the field. Details may vary by MySQL server version. Since 1.0.0. length The width of the field. Details may vary by MySQL server version. Since 1.0.0. type The data type of the field. Details may vary by the MySQL server in use. This is the MySQL C API type constants value. It is recommended to use type constants provided by the mysqli extension to test for its meaning. You should not test for certain type values by comparing with certain numbers. Since 1.0.0.
The APC storage handler returns the same information for the data property but no metadata. The metadata of a cache entry is set to NULL.
The MEMCACHE storage handler does not fill the data property. Statistics are not available on a per cache entry basis with the MEMCACHE storage handler.
A user defined storage handler is free to provide any data.
-
Przykłady
The example shows the output from the built-in default storage handler. Other storage handler may report different data.
<?php
/* Populate the cache, e.g. using mysqli */
$mysqli = new mysqli("host", "user", "password", "schema");
$mysqli->query("/*" . MYSQLND_QC_ENABLE_SWITCH . "*/SELECT id FROM test");
/* Display cache information */
var_dump(mysqlnd_qc_get_cache_info());
?>
Powyższe przykłady wyświetlą:
array(4) {
["num_entries"]=>
int(1)
["handler"]=>
string(7) "default"
["handler_version"]=>
string(5) "1.0.0"
["data"]=>
array(1) {
["Localhost via UNIX socket 3306 user schema|/*qc=on*/SELECT id FROM test"]=>
array(2) {
["statistics"]=>
array(11) {
["rows"]=>
int(6)
["stored_size"]=>
int(101)
["cache_hits"]=>
int(0)
["run_time"]=>
int(471)
["store_time"]=>
int(27)
["min_run_time"]=>
int(0)
["max_run_time"]=>
int(0)
["min_store_time"]=>
int(0)
["max_store_time"]=>
int(0)
["avg_run_time"]=>
int(0)
["avg_store_time"]=>
int(0)
}
["metadata"]=>
array(1) {
[0]=>
array(8) {
["name"]=>
string(2) "id"
["orig_name"]=>
string(2) "id"
["table"]=>
string(4) "test"
["orig_table"]=>
string(4) "test"
["db"]=>
string(4) "schema"
["max_length"]=>
int(1)
["length"]=>
int(11)
["type"]=>
int(3)
}
}
}
}
}
mysqlnd_qc_get_core_stats
(PECL mysqlnd_qc >= 1.0.0)
mysqlnd_qc_get_core_stats — Statistics collected by the core of the query cache
Opis
Returns an array of statistics collected by the core of the cache plugin. The same data fields will be reported for any storage handler because the data is collected by the core.
The PHP configuration setting mysqlnd_qc.collect_statistics controls the collection of statistics. The collection of statistics is disabled by default for performance reasons. Disabling the collection of statistics will also disable the collection of time related statistics.
The PHP configuration setting mysqlnd_qc.collect_time_statistics controls the collection of time related statistics.
The scope of the core statistics is the PHP process. Depending on your deployment model a PHP process may handle one or multiple requests.
Statistics are aggregated for all cache entries and all storage handler. It is not possible to tell how much queries originating from mysqli, PDO_MySQL or mysql API calls have contributed to the aggregated data values.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Array of core statistics
| Statistic | Description | Version |
|---|---|---|
| cache_hit | Statement is considered cacheable and cached data has been reused. Statement is considered cacheable and a cache miss happened but the statement got cached by someone else while we process it and thus we can fetch the result from the refreshed cache. | Since 1.0.0. |
| cache_miss |
Statement is considered cacheable...
|
Since 1.0.0. |
| cache_put | Statement is considered cacheable and has been added to the cache. Take care when calculating derived statistics. Storage handler with a storage life time beyond process scope may report cache_put = 0 together with cache_hit > 0, if another process has filled the cache. You may want to use num_entries from mysqlnd_qc_get_cache_info() if the handler supports it ( default, APC). | Since 1.0.0. |
| query_should_cache | Statement is considered cacheable based on query string analysis. The statement may or may not be added to the cache. See also cache_put. | Since 1.0.0. |
| query_should_not_cache | Statement is considered not cacheable based on query string analysis. | Since 1.0.0. |
| query_not_cached | Statement is considered not cacheable or it is considered cachable but the storage handler has not returned a hash key for it. | Since 1.0.0. |
| query_could_cache |
Statement is considered cacheable...
|
Since 1.0.0. |
| query_found_in_cache | Statement is considered cacheable and we have found it in the cache but we have not replayed the cached data yet and we have not send the result set to the client yet. This is not considered a cache hit because the client might not fetch the result or the cached data may be faulty. | Since 1.0.0. |
| query_uncached_other | Statement is considered cacheable and it may or may not be in the cache already but either replaying cached data has failed, no result set is available or some other error has happened. | |
| query_uncached_no_table | Statement has not been cached because the result set has at least one column which has no table name in its meta data. An example of such a query is SELECT SLEEP(1). To cache those statements you have to change default value of the PHP configuration directive mysqlnd_qc.cache_no_table and set mysqlnd_qc.cache_no_table = 1. Often, it is not desired to cache such statements. | Since 1.0.0. |
| query_uncached_use_result | Statement would have been cached if a buffered result set had been used. The situation is also consiered as a cache miss and cache_miss will be incremented as well. | Since 1.0.0. |
| query_aggr_run_time_cache_hit | Aggregated run time (ms) of all cached queries. Cached queries are those which have incremented cache_hit. | Since 1.0.0. |
| query_aggr_run_time_cache_put | Aggregated run time (ms) of all uncached queries that have been put into the cache. See also cache_put. | Since 1.0.0. |
| query_aggr_run_time_total | Aggregated run time (ms) of all uncached and cached queries that have been inspected and executed by the query cache. | Since 1.0.0. |
| query_aggr_store_time_cache_hit | Aggregated store time (ms) of all cached queries. Cached queries are those which have incremented cache_hit. | Since 1.0.0. |
| query_aggr_store_time_cache_put | Aggregated store time ( ms) of all uncached queries that have been put into the cache. See also cache_put. | Since 1.0.0. |
| query_aggr_store_time_total | Aggregated store time (ms) of all uncached and cached queries that have been inspected and executed by the query cache. | Since 1.0.0. |
| receive_bytes_recorded | Recorded incoming network traffic ( bytes) send from MySQL to PHP. The traffic may or may not have been added to the cache. The traffic is the total for all queries regardless if cached or not. | Since 1.0.0. |
| receive_bytes_replayed | Network traffic replayed during cache. This is the total amount of incoming traffic saved because of the usage of the query cache plugin. | Since 1.0.0. |
| send_bytes_recorded | Recorded outgoing network traffic ( bytes) send from MySQL to PHP. The traffic may or may not have been added to the cache. The traffic is the total for all queries regardless if cached or not. | Since 1.0.0. |
| send_bytes_replayed | Network traffic replayed during cache. This is the total amount of outgoing traffic saved because of the usage of the query cache plugin. | Since 1.0.0. |
| slam_stale_refresh | Number of cache misses which triggered serving stale data until the client causing the cache miss has refreshed the cache entry. | Since 1.0.0. |
| slam_stale_hit | Number of cache hits while a stale cache entry gets refreshed. | Since 1.0.0. |
Przykłady
<?php
/* Enable collection of statistics - default: disabled */
ini_set("mysqlnd_qc.collect_statistics", 1);
/* Enable collection of all timing related statistics -
default: enabled but overruled by mysqlnd_qc.collect_statistics = 0 */
ini_set("mysqlnd_qc.collect_time_statistics", 1);
/* Populate the cache, e.g. using mysqli */
$mysqli = new mysqli('host', 'user', 'password', 'schema');
/* Cache miss and cache put */
$mysqli->query("/*qc=on*/SELECT id FROM test");
/* Cache hit */
$mysqli->query("/*qc=on*/SELECT id FROM test");
/* Display core statstics */
var_dump(mysqlnd_qc_get_core_stats());
?>
Powyższe przykłady wyświetlą:
array(26) {
["cache_hit"]=>
string(1) "1"
["cache_miss"]=>
string(1) "1"
["cache_put"]=>
string(1) "1"
["query_should_cache"]=>
string(1) "2"
["query_should_not_cache"]=>
string(1) "0"
["query_not_cached"]=>
string(1) "0"
["query_could_cache"]=>
string(1) "2"
["query_found_in_cache"]=>
string(1) "1"
["query_uncached_other"]=>
string(1) "0"
["query_uncached_no_table"]=>
string(1) "0"
["query_uncached_no_result"]=>
string(1) "0"
["query_uncached_use_result"]=>
string(1) "0"
["query_aggr_run_time_cache_hit"]=>
string(1) "4"
["query_aggr_run_time_cache_put"]=>
string(3) "395"
["query_aggr_run_time_total"]=>
string(3) "399"
["query_aggr_store_time_cache_hit"]=>
string(1) "2"
["query_aggr_store_time_cache_put"]=>
string(1) "8"
["query_aggr_store_time_total"]=>
string(2) "10"
["receive_bytes_recorded"]=>
string(2) "65"
["receive_bytes_replayed"]=>
string(2) "65"
["send_bytes_recorded"]=>
string(2) "29"
["send_bytes_replayed"]=>
string(2) "29"
["slam_stale_refresh"]=>
string(1) "0"
["slam_stale_hit"]=>
string(1) "0"
["request_counter"]=>
int(1)
["process_hash"]=>
int(3547549858)
}
Zobacz też:
- Runtime configuration
- mysqlnd_qc.collect_statistics
- mysqlnd_qc.time_statistics
- mysqlnd_qc_get_cache_info() - Returns information on the current handler, the number of cache entries and cache entries, if available
mysqlnd_qc_get_normalized_query_trace_log
(PECL mysqlnd_qc >= 1.0.0)
mysqlnd_qc_get_normalized_query_trace_log — Returns a normalized query trace log for each query inspected by the query cache
Opis
Returns a normalized query trace log for each query inspected by the query cache. The collection of the trace log is disabled by default. To collect the trace log you have to set the PHP configuration directive mysqlnd_qc.collect_normalized_query_trace to 1
Entries in the trace log are grouped by the normalized query statement. The normalized query statement is the query statement with all statement parameter values being replaced with a question mark. For example, the two statements SELECT id FROM test WHERE id = 1 and SELECT id FROM test WHERE id = 2 are normalized as SELECT id FROM test WHERE id = ?. Whenever a statement is inspected by the query cache which matches the normalized statement pattern, its statistics are grouped by the normalized statement string.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
An array of query log. Every list entry contains the normalized query stringand further detail information.
| Key | Description |
|---|---|
| query | Normalized statement string. |
| occurences | How many statements have matched the normalized statement string in addition to the one which has created the log entry. The value is zero if a statement has been normalized, its normalized representation has been added to the log but no further queries inspected by PECL/mysqlnd_qc have the same normalized statement string. |
| eligible_for_caching | Whether the statement could be cached. An statement eligible for caching has not necessarily been cached. It not possible to tell for sure if or how many cached statement have contributed to the aggregated normalized statement log entry. However, comparing the minimum and average run time one can make an educated guess. |
| avg_run_time | The average run time of all queries contributing to the query log entry. The run time is the time between sending the query statement to MySQL and receiving an answer from MySQL. |
| avg_store_time | The average store time of all queries contributing to the query log entry. The store time is the time needed to fetch a statements result set from the server to the client and, storing it on the client. |
| min_run_time | The minimum run time of all queries contributing to the query log entry. |
| min_store_time | The minimum store time of all queries contributing to the query log entry. |
| max_run_time | The maximum run time of all queries contributing to the query log entry. |
| max_store_time | The maximum store time of all queries contributing to the query log entry. |
Przykłady
mysqlnd_qc.collect_normalized_query_trace=1
<?php
/* Connect, create and populate test table */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2)");
/* not cached */
$res = $mysqli->query("SELECT id FROM test WHERE id = 1");
var_dump($res->fetch_assoc());
$res->free();
/* cache put */
$res = $mysqli->query("/*" . MYSQLND_QC_ENABLE_SWITCH . "*/" . "SELECT id FROM test WHERE id = 2");
var_dump($res->fetch_assoc());
$res->free();
/* cache hit */
$res = $mysqli->query("/*" . MYSQLND_QC_ENABLE_SWITCH . "*/" . "SELECT id FROM test WHERE id = 2");
var_dump($res->fetch_assoc());
$res->free();
var_dump(mysqlnd_qc_get_normalized_query_trace_log());
?>
Powyższe przykłady wyświetlą:
array(1) {
["id"]=>
string(1) "1"
}
array(1) {
["id"]=>
string(1) "2"
}
array(1) {
["id"]=>
string(1) "2"
}
array(4) {
[0]=>
array(9) {
["query"]=>
string(25) "DROP TABLE IF EXISTS test"
["occurences"]=>
int(0)
["eligible_for_caching"]=>
bool(false)
["avg_run_time"]=>
int(0)
["min_run_time"]=>
int(0)
["max_run_time"]=>
int(0)
["avg_store_time"]=>
int(0)
["min_store_time"]=>
int(0)
["max_store_time"]=>
int(0)
}
[1]=>
array(9) {
["query"]=>
string(27) "CREATE TABLE test (id INT )"
["occurences"]=>
int(0)
["eligible_for_caching"]=>
bool(false)
["avg_run_time"]=>
int(0)
["min_run_time"]=>
int(0)
["max_run_time"]=>
int(0)
["avg_store_time"]=>
int(0)
["min_store_time"]=>
int(0)
["max_store_time"]=>
int(0)
}
[2]=>
array(9) {
["query"]=>
string(40) "INSERT INTO test (id ) VALUES (? ), (? )"
["occurences"]=>
int(0)
["eligible_for_caching"]=>
bool(false)
["avg_run_time"]=>
int(0)
["min_run_time"]=>
int(0)
["max_run_time"]=>
int(0)
["avg_store_time"]=>
int(0)
["min_store_time"]=>
int(0)
["max_store_time"]=>
int(0)
}
[3]=>
array(9) {
["query"]=>
string(31) "SELECT id FROM test WHERE id =?"
["occurences"]=>
int(2)
["eligible_for_caching"]=>
bool(true)
["avg_run_time"]=>
int(159)
["min_run_time"]=>
int(12)
["max_run_time"]=>
int(307)
["avg_store_time"]=>
int(10)
["min_store_time"]=>
int(8)
["max_store_time"]=>
int(13)
}
}
Zobacz też:
- Runtime configuration
- mysqlnd_qc.collect_normalized_query_trace
- mysqlnd_qc.time_statistics
- mysqlnd_qc_get_query_trace_log() - Returns a backtrace for each query inspected by the query cache
mysqlnd_qc_get_query_trace_log
(PECL mysqlnd_qc >= 1.0.0)
mysqlnd_qc_get_query_trace_log — Returns a backtrace for each query inspected by the query cache
Opis
Returns a backtrace for each query inspected by the query cache. The collection of the backtrace is disabled by default. To collect the backtrace you have to set the PHP configuration directive mysqlnd_qc.collect_query_trace to 1
The maximum depth of the backtrace is limited to the depth set with the PHP configuration directive mysqlnd_qc.query_trace_bt_depth.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
An array of query backtrace. Every list entry contains the query string, a backtrace and further detail information.
| Key | Description |
|---|---|
| query | Query string. |
| origin | Code backtrace. |
| run_time | Query run time in milliseconds. The collection of all times and the necessary gettimeofday system calls can be disabled by setting the PHP configuration directive mysqlnd_qc.time_statistics to 0 |
| store_time | Query result set store time in milliseconds. The collection of all times and the necessary gettimeofday system calls can be disabled by setting the PHP configuration directive mysqlnd_qc.time_statistics to 0 |
| eligible_for_caching |
TRUE if query is cacheble otherwise
FALSE.
|
| no_table |
TRUE if the query has generated a result
set and at least one column from the result set has no table
name set in its metadata. This is usually the case with
queries which one probably do not want to cache such as
SELECT SLEEP(1). By default any such query
will not be added to the cache. See also PHP configuration directive
mysqlnd_qc.cache_no_table.
|
| was_added |
TRUE if the query result has been put into
the cache, otherwise
FALSE.
|
| was_already_in_cache |
TRUE if the query result would have been
added to the cache if it was not already in the cache (cache hit).
Otherwise
FALSE.
|
Przykłady
mysqlnd_qc.collect_query_trace=1
<?php
/* Connect, create and populate test table */
$mysqli = new mysqli("host", "user", "password", "schema", "port", "socket");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2)");
/* not cached */
$res = $mysqli->query("SELECT id FROM test WHERE id = 1");
var_dump($res->fetch_assoc());
$res->free();
/* cache put */
$res = $mysqli->query("/*" . MYSQLND_QC_ENABLE_SWITCH . "*/" . "SELECT id FROM test WHERE id = 2");
var_dump($res->fetch_assoc());
$res->free();
/* cache hit */
$res = $mysqli->query("/*" . MYSQLND_QC_ENABLE_SWITCH . "*/" . "SELECT id FROM test WHERE id = 2");
var_dump($res->fetch_assoc());
$res->free();
var_dump(mysqlnd_qc_get_query_trace_log());
?>
Powyższe przykłady wyświetlą:
array(1) {
["id"]=>
string(1) "1"
}
array(1) {
["id"]=>
string(1) "2"
}
array(1) {
["id"]=>
string(1) "2"
}
array(6) {
[0]=>
array(8) {
["query"]=>
string(25) "DROP TABLE IF EXISTS test"
["origin"]=>
string(102) "#0 qc.php(4): mysqli->query('DROP TABLE IF E...')
#1 {main}"
["run_time"]=>
int(0)
["store_time"]=>
int(0)
["eligible_for_caching"]=>
bool(false)
["no_table"]=>
bool(false)
["was_added"]=>
bool(false)
["was_already_in_cache"]=>
bool(false)
}
[1]=>
array(8) {
["query"]=>
string(25) "CREATE TABLE test(id INT)"
["origin"]=>
string(102) "#0 qc.php(5): mysqli->query('CREATE TABLE te...')
#1 {main}"
["run_time"]=>
int(0)
["store_time"]=>
int(0)
["eligible_for_caching"]=>
bool(false)
["no_table"]=>
bool(false)
["was_added"]=>
bool(false)
["was_already_in_cache"]=>
bool(false)
}
[2]=>
array(8) {
["query"]=>
string(36) "INSERT INTO test(id) VALUES (1), (2)"
["origin"]=>
string(102) "#0 qc.php(6): mysqli->query('INSERT INTO tes...')
#1 {main}"
["run_time"]=>
int(0)
["store_time"]=>
int(0)
["eligible_for_caching"]=>
bool(false)
["no_table"]=>
bool(false)
["was_added"]=>
bool(false)
["was_already_in_cache"]=>
bool(false)
}
[3]=>
array(8) {
["query"]=>
string(32) "SELECT id FROM test WHERE id = 1"
["origin"]=>
string(102) "#0 qc.php(9): mysqli->query('SELECT id FROM ...')
#1 {main}"
["run_time"]=>
int(0)
["store_time"]=>
int(25)
["eligible_for_caching"]=>
bool(false)
["no_table"]=>
bool(false)
["was_added"]=>
bool(false)
["was_already_in_cache"]=>
bool(false)
}
[4]=>
array(8) {
["query"]=>
string(41) "/*qc=on*/SELECT id FROM test WHERE id = 2"
["origin"]=>
string(103) "#0 qc.php(14): mysqli->query('/*qc=on*/SELECT...')
#1 {main}"
["run_time"]=>
int(311)
["store_time"]=>
int(13)
["eligible_for_caching"]=>
bool(true)
["no_table"]=>
bool(false)
["was_added"]=>
bool(true)
["was_already_in_cache"]=>
bool(false)
}
[5]=>
array(8) {
["query"]=>
string(41) "/*qc=on*/SELECT id FROM test WHERE id = 2"
["origin"]=>
string(103) "#0 qc.php(19): mysqli->query('/*qc=on*/SELECT...')
#1 {main}"
["run_time"]=>
int(13)
["store_time"]=>
int(8)
["eligible_for_caching"]=>
bool(true)
["no_table"]=>
bool(false)
["was_added"]=>
bool(false)
["was_already_in_cache"]=>
bool(true)
}
}
Zobacz też:
- Runtime configuration
- mysqlnd_qc.collect_query_trace
- mysqlnd_qc.query_trace_bt_depth
- mysqlnd_qc.time_statistics
- mysqlnd_qc.cache_no_table
- mysqlnd_qc_get_normalized_query_trace_log() - Returns a normalized query trace log for each query inspected by the query cache
mysqlnd_qc_set_cache_condition
(PECL mysqlnd_qc >= 1.1.0)
mysqlnd_qc_set_cache_condition — Set conditions for automatic caching
Opis
$condition_type
,
mixed
$condition
,
mixed
$condition_option
)Sets a condition for automatic caching of statements which do not contain the necessary SQL hints to enable caching of them.
Parametry
-
condition_type -
Type of the condition. The only allowed value is
MYSQLND_QC_CONDITION_META_SCHEMA_PATTERN. -
condition -
Parameter for the condition set with condition_type. Parameter type and structure depend on condition_type
If condition_type equals MYSQLND_QC_CONDITION_META_SCHEMA_PATTERN condition must be a string. The string sets a pattern. Statements are cached if table and database meta data entry of their result sets match the pattern. The pattern is checked for a match with the db and org_table meta data entries provided by the underlying MySQL client server library. Please, check the MySQL Reference manual for details about the two entries. The db and org_table values are concatenated with a dot (.) before matched against condition. Pattern matching supports the wildcards % and _. The wildcard % will match one or many arbitrary characters. _ will match one arbitrary character. The escape symbol is backslash.
-
condition_option -
Option for condition. Type and structure depend on condition_type.
If condition_type equals MYSQLND_QC_CONDITION_META_SCHEMA_PATTERN condition_options is the TTL to be used.
Przykłady
<?php
/* Cache all accesses to tables with the name "new%" in schema/database "db_example" for 1 second */
if (!mysqlnd_qc_set_cache_condition(MYSQLND_QC_CONDITION_META_SCHEMA_PATTERN, "db_example.new%", 1)) {
die("Failed to set cache condition!");
}
$mysqli = new mysqli("host", "user", "password", "db_example", "port");
/* cached although no SQL hint given */
$mysqli->query("SELECT id, title FROM news");
$pdo_mysql = new PDO("mysql:host=host;dbname=db_example;port=port", "user", "password");
/* not cached: no SQL hint, no pattern match */
$pdo_mysql->query("SELECT id, title FROM latest_news");
/* cached: TTL 1 second, pattern match */
$pdo_mysql->query("SELECT id, title FROM news");
?>
Zwracane wartości
Returns TRUE on success or FALSE on FAILURE.
mysqlnd_qc_set_is_select
(PECL mysqlnd_qc >= 1.0.0)
mysqlnd_qc_set_is_select — Installs a callback which decides whether a statement is cached
Opis
Installs a callback which decides whether a statement is cached.
There are several ways of hinting PELC/mysqlnd_qc to cache a query. By default, PECL/mysqlnd_qc attempts to cache a if caching of all statements is enabled or the query string begins with a certain SQL hint. The plugin internally calls a function named is_select() to find out. This internal function can be replaced with a user-defined callback. Then, the user-defined callback is responsible to decide whether the plugin attempts to cache a statement. Because the internal function is replaced with the callback, the callback gains full control. The callback is free to ignore the configuration setting mysqlnd_qc.cache_by_default and SQL hints.
The callback is invoked for every statement inspected by the plugin.
It is given the statements string as a parameter. The callback returns
FALSE if the statement shall not be cached. It returns TRUE to
make the plugin attempt to cache the statements result set, if any.
A so-created cache entry is given the default TTL set with the
PHP configuration directive mysqlnd_qc.ttl.
If a different TTL shall be used, the callback returns a numeric
value to be used as the TTL.
The internal is_select function is part of the internal cache storage handler interface. Thus, a user-defined storage handler offers the same capabilities.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
<?php
/* callback which decides if query is cached */
function is_select($query) {
static $patterns = array(
/* true - use default from mysqlnd_qc.ttl */
"@SELECT\s+.*\s+FROM\s+test@ismU" => true,
/* 3 - use TTL = 3 seconds */
"@SELECT\s+.*\s+FROM\s+news@ismU" => 3
);
/* check if query does match pattern */
foreach ($patterns as $pattern => $ttl) {
if (preg_match($pattern, $query)) {
printf("is_select(%45s): cache\n", $query);
return $ttl;
}
}
printf("is_select(%45s): do not cache\n", $query);
return false;
}
mysqlnd_qc_set_is_select("is_select");
/* Connect, create and populate test table */
$mysqli = new mysqli("host", "user", "password", "schema");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");
/* cache put */
$mysqli->query("SELECT id FROM test WHERE id = 1");
/* cache hit */
$mysqli->query("SELECT id FROM test WHERE id = 1");
/* cache put */
$mysqli->query("SELECT * FROM test");
?>
Powyższe przykłady wyświetlą:
is_select( DROP TABLE IF EXISTS test): do not cache is_select( CREATE TABLE test(id INT)): do not cache is_select( INSERT INTO test(id) VALUES (1), (2), (3)): do not cache is_select( SELECT id FROM test WHERE id = 1): cache is_select( SELECT id FROM test WHERE id = 1): cache is_select( SELECT * FROM test): cache
Zobacz też:
- Runtime configuration
- mysqlnd_qc.ttl
- mysqlnd_qc.cache_by_default
- mysqlnd_qc_set_user_handlers() - Sets the callback functions for a user-defined procedural storage handler
mysqlnd_qc_set_storage_handler
(PECL mysqlnd_qc >= 1.0.0)
mysqlnd_qc_set_storage_handler — Change current storage handler
Opis
$handler
)Sets the storage handler used by the query cache. A list of available storage handler can be obtained from mysqlnd_qc_get_available_handlers(). Which storage are available depends on the compile time configuration of the query cache plugin. The default storage handler is always available. All other storage handler must be enabled explicitly when building the extension.
Parametry
-
handler -
Handler can be of type string representing the name of a built-in storage handler or an object of type mysqlnd_qc_handler_default. The names of the built-in storage handler are default, APC, MEMCACHE, sqlite.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
If changing the storage handler fails a catchable fatal error will be thrown. The query cache cannot operate if the previous storage handler has been shutdown but no new storage handler has been installed.
Przykłady
The example shows the output from the built-in default storage handler. Other storage handler may report different data.
<?php
var_dump(mysqlnd_qc_set_storage_handler("memcache"));
if (true === mysqlnd_qc_set_storage_handler("default"))
printf("Default storage handler activated");
/* Catchable fatal error */
var_dump(mysqlnd_qc_set_storage_handler("unknown"));
?>
Powyższe przykłady wyświetlą:
bool(true) Default storage handler activated Catchable fatal error: mysqlnd_qc_set_storage_handler(): Unknown handler 'unknown' in (file) on line (line)
Zobacz też:
- Installation
- mysqlnd_qc_get_available_handlers() - Returns a list of available storage handler
mysqlnd_qc_set_user_handlers
(PECL mysqlnd_qc >= 1.0.0)
mysqlnd_qc_set_user_handlers — Sets the callback functions for a user-defined procedural storage handler
Opis
$get_hash
,
string
$find_query_in_cache
,
string
$return_to_cache
,
string
$add_query_to_cache_if_not_exists
,
string
$query_is_select
,
string
$update_query_run_time_stats
,
string
$get_stats
,
string
$clear_cache
)Sets the callback functions for a user-defined procedural storage handler.
Parametry
-
get_hash -
Name of the user function implementing the storage handler get_hash functionality.
-
find_query_in_cache -
Name of the user function implementing the storage handler find_in_cache functionality.
-
return_to_cache -
Name of the user function implementing the storage handler return_to_cache functionality.
-
add_query_to_cache_if_not_exists -
Name of the user function implementing the storage handler add_query_to_cache_if_not_exists functionality.
-
query_is_select -
Name of the user function implementing the storage handler query_is_select functionality.
-
update_query_run_time_stats -
Name of the user function implementing the storage handler update_query_run_time_stats functionality.
-
get_stats -
Name of the user function implementing the storage handler get_stats functionality.
-
clear_cache -
Name of the user function implementing the storage handler clear_cache functionality.
Zwracane wartości
Returns TRUE on success or FALSE on FAILURE.
Spis treści
- mysqlnd_qc_clear_cache — Flush all cache contents
- mysqlnd_qc_get_available_handlers — Returns a list of available storage handler
- mysqlnd_qc_get_cache_info — Returns information on the current handler, the number of cache entries and cache entries, if available
- mysqlnd_qc_get_core_stats — Statistics collected by the core of the query cache
- mysqlnd_qc_get_normalized_query_trace_log — Returns a normalized query trace log for each query inspected by the query cache
- mysqlnd_qc_get_query_trace_log — Returns a backtrace for each query inspected by the query cache
- mysqlnd_qc_set_cache_condition — Set conditions for automatic caching
- mysqlnd_qc_set_is_select — Installs a callback which decides whether a statement is cached
- mysqlnd_qc_set_storage_handler — Change current storage handler
- mysqlnd_qc_set_user_handlers — Sets the callback functions for a user-defined procedural storage handler
Change History
Spis treści
This change history is a high level summary of selected changes that may impact applications and/or break backwards compatibility.
See also the CHANGES file in the source distribution for a complete list of changes.
PECL/mysqlnd_qc 1.1 series
1.1.0
- Release date: under development
- Motto/theme: PHP 5.4 compatibility, schema pattern based caching and mysqlnd_ms support
Feature changes
-
APC storage handler update
- Fix build for APC 3.1.9+
- Note: Use of the APC storage handler is currently not recommended due to stability issues of APC itself.
-
New PHP configuration directives
- mysqlnd_qc.collect_statistics_log_file. Aggregated cache statistics log file written after every 10th request served by the PHP process.
- mysqlnd_qc.ignore_sql_comments. Control whether SQL comments are ignored for cache key hash generation.
-
New constants and SQL hints
-
MYSQLND_QC_SERVER_ID_SWITCHallows grouping of cache entries from different physical connections. This is needed by PECL/mysqlnd_ms. -
MYSQLND_QC_CONDITION_META_SCHEMA_PATTERNto be used with mysqlnd_qc_set_cache_condition().
-
-
New function mysqlnd_qc_set_cache_condition() for built-in schema pattern based caching. Likely to support a wider range of conditions in the future.
-
Report valid_until timestamp for cache entries of the default handler through mysqlnd_qc_get_cache_info().
-
Include charset number for cache entry hashing. This should prevent serving result sets which have the wrong charset.
API change: get_hash_key expects new "charsetnr" (int) parameter after "port".
-
API change: changing is_select() signature from bool is_select() to mixed is_select(). Mixed can be either boolean or array(long ttl, string server_id). This is needed by PECL/mysqlnd_ms.
Other
-
Support acting as a cache backend for PECL/mysqlnd_ms 1.3.0-beta or later to transparently replace MySQL Replication slave reads with cache accesses, if the user explicitly allows.
Bug fixes
- Fixed Bug #59959 (config.m4, wrong library - 64bit memcached handler builds) (Credits: Remi Collet)
PECL/mysqlnd_qc 1.0 series
1.0.1-stable
- Release date: 12/2010
- Motto/theme: Prepared statement support
Added support for Prepared statements and unbuffered queries.
1.0.0-beta
- Release date: 07/2010
- Motto/theme: TTL-based cache with various storage options (Memcache, APC, SQLite, user-defined)
Initial public release of the transparent TTL-based query result cache. Flexible storage of cached results. Various storage media supported.
- Wstęp
- Quickstart and Examples
- Instalacja/Konfiguracja
- Stałe predefiniowane
- mysqlnd_qc Funkcje
- mysqlnd_qc_clear_cache — Flush all cache contents
- mysqlnd_qc_get_available_handlers — Returns a list of available storage handler
- mysqlnd_qc_get_cache_info — Returns information on the current handler, the number of cache entries and cache entries, if available
- mysqlnd_qc_get_core_stats — Statistics collected by the core of the query cache
- mysqlnd_qc_get_normalized_query_trace_log — Returns a normalized query trace log for each query inspected by the query cache
- mysqlnd_qc_get_query_trace_log — Returns a backtrace for each query inspected by the query cache
- mysqlnd_qc_set_cache_condition — Set conditions for automatic caching
- mysqlnd_qc_set_is_select — Installs a callback which decides whether a statement is cached
- mysqlnd_qc_set_storage_handler — Change current storage handler
- mysqlnd_qc_set_user_handlers — Sets the callback functions for a user-defined procedural storage handler
- Change History
Mysqlnd user handler plugin
Wstęp
The mysqlnd user handler plugin (mysqlnd_uh) allows users to set hooks for most internal calls of the MySQL native driver for PHP (mysqlnd). Mysqlnd and its plugins, including PECL/mysqlnd_uh, operate on a layer beneath the PHP MySQL extensions. A mysqlnd plugin can be considered as a proxy between the PHP MySQL extensions and the MySQL server as part of the PHP executable on the client-side. Because the plugins operates on their own layer below the PHP MySQL extensions, they can monitor and change application actions without requiring application changes. If the PHP MySQL extensions (mysqli, mysql, PDO_MYSQL) are compiled to use mysqlnd this can be used for:
-
Monitoring
-
Queries run by any of the PHP MySQL extensions
-
Prepared statements run by any of the PHP MySQL extensions
-
-
Auditing
-
Detection of databases uses
-
SQL Injection protection using black-/whitelists
-
-
Assorted
-
Load Balancing connections
-
As of version PHP 5.3.3 the MySQL native driver for PHP (mysqlnd) features an internal plugin C API. C plugins, such as the mysqlnd user handler plugin, can extend the functionality of mysqlnd. PECL/mysqlnd_uh makes parts of the internal plugin C API available to the PHP user for plugin development with PHP.
The MySQL native driver for PHP is a C library which ships together with PHP as of PHP 5.3.0. It serves as a drop-in replacement for the MySQL Client Library (AKA libmysql/libmysqlclient). As of PHP 5.4.0, mysqlnd is the compile time default library used by all PHP MySQL extensions.
Security considerations
PECL/mysqlnd_uh gives users access to MySQL user names, MySQL password used by any of the PHP MySQL extensions to connect to MySQL. It allows monitoring of all queries and prepared statements exposing the statement string to the user. Therefore, the extension should be installed with care. The PHP_INI_SYSTEM configuration setting mysqlnd_uh.enable can be used to prevent users from hooking mysqlnd calls.
Code obfuscators and similar technologies are not suitable to prevent monitoring of mysqlnd library activities if PECL/mysqlnd_uh is made available and the user can install a proxy, for example, using auto_prepend_file.
Documentation note
Many of the extensions functions are described very briefly. This is done intentionally to avoid content duplication. The mysqli extension is often only a thin abstraction layer on top of the MySQL C API, which the mysqlnd library provides. Therefore, the corresponding mysqli documentation respectively the MySQL reference manual can be consulted to get more information on a particular function.
On the name
The shortcut mysqlnd_uh stands for mysqlnd user handler. There may be better names. However, this was the initial choice when development started. Meanwhile, non speaking names have almost become a tradition.
Informacja:
The mysqlnd user handler plugin is in alpha status. Take appropriate care before using it in production environments.
Quickstart and Examples
Spis treści
The mysqlnd user handler plugin can be understood as a client-side proxy for all PHP MySQL extensions (mysqli, mysql, PDO_MYSQL), if they are compiled to use the mysqlnd library. The extensions use the mysqlnd library internally, at the C level, to communicate with the MySQL server. PECL/mysqlnd_uh allows it to hook many mysqlnd calls. Therefore, most activities of the PHP MySQL extensions can be monitored.
Because monitoring happens at the level of the library, at a layer below the application, it is possible to monitor applications without changing them.
On the C level, the mysqlnd library is structured in modules or classes. The extension hooks almost all methods of the mysqlnd internal connection class and exposes them through the user space class MysqlndUhConnection. Some few methods of the mysqlnd internal statement class are made available to the PHP user with the class MysqlndUhPreparedStatement. By subclassing the classes MysqlndUhConnection and MysqlndUhPreparedStatement users get access to mysqlnd internal function calls.
Informacja:
None of the mysqlnd internal function calls has been designed to ever by exposed to the PHP user. Manipulating their activities may cause PHP to crash or leak memory. Often, this is not considered a bug. Please, keep in mind that you are accessing C library functions through PHP which are expected to take certain actions, which you may not be able to emulate in user space. Therefore, it is strongly recommended to always call the parent method implementation when subclassing MysqlndUhConnection or MysqlndUhPreparedStatement. To prevent the worst case, the extension performs some sanity checks. Please, see also Mysqlnd_uh Opcje konfiguracyjne.
Setup
The plugin is implemented as a PHP extension. Please, follow the installation instructions to install the » PECL/mysqlnd_uh extension. Then, load the extension into PHP and activate the plugin in the PHP configuration file using the PHP configuration directive named mysqlnd_uh.enable. The below example shows the default settings of the extension.
Przykład #1 Enabling the plugin (php.ini)
mysqlnd_uh.enable=1 mysqlnd_uh.report_wrong_types=1
How it works
Informacja:
You can skip the following and move on to the examples for now, if you are not interested in the inner workings. Please, get back to the background information and read it carefully, if you plan to use PECL/mysqlnd_uh intensively in the future.
Two classes are provided by the extension: MysqlndUhConnection and MysqlndUhPreparedStatement. The first one lets you access almost all methods of the mysqlnd internal connection class. The latter exposes some, selected methods of the mysqlnd internal statement class. For example, MysqlndUhConnection::connect() maps to the mysqlnd library C function mysqlnd_conn__connect.
As a mysqlnd plugin, the PECL/mysqlnd_uh extensions replaces mysqlnd library C functions with its own functions. Whenever a PHP MySQL extension compiled to use mysqlnd, calls a mysqlnd function, the functions installed by the plugin are executed instead of the original mysqlnd ones. If, for example, mysqli_connect() invokes mysqlnd_conn__connect, the connect function installed by PECL/mysqlnd_uh will be called. The functions installed by PECL/mysqlnd_uh are the methods of the built-in classes.
The built-in PHP classes and their methods do nothing but call their mysqlnd C library counterparts, to behave exaclty like the original mysqlnd function they replace. The code below illustrates in pseudo-code what the extension does.
Przykład #1 Pseudo-code: what a built-in class does
class MysqlndUhConnection {
public function connect(($conn, $host, $user, $passwd, $db, $port, $socket, $mysql_flags) {
MYSQLND* c_mysqlnd_connection = convert_from_php_to_c($conn);
...
return call_c_function(mysqlnd_conn__connect(c_mysqlnd_connection, ...));
}
}
The build-in classes behave like a transparent proxy. It is possible for you to replace the proxy with your own. This is done by subclassing MysqlndUhConnection or MysqlndUhPreparedStatement to extend the functionality of the proxy, followed by registering a new proxy object. Proxy objects are installed by mysqlnd_uh_set_connection_proxy() and mysqlnd_uh_set_statement_proxy().
Przykład #2 Installing a proxy
<?php
class proxy extends MysqlndUhConnection {
public function connect($res, $host, $user, $passwd, $db, $port, $socket, $mysql_flags) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::connect($res, $host, $user, $passwd, $db, $port, $socket, $mysql_flags);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
?>
Powyższy przykład wyświetli:
proxy::connect(array ( 0 => NULL, 1 => 'localhost', 2 => 'root', 3 => '', 4 => 'test', 5 => 3306, 6 => NULL, 7 => 131072, )) proxy::connect returns true
Installing a proxy
The extension provides two built-in classes: MysqlndUhConnection and MysqlndUhPreparedStatement. The classes are used for hooking mysqlnd library calls. Their methods correspond to mysqlnd internal functions. By default they act like a transparent proxy and do nothing but call their mysqlnd counterparts. By subclassing the classes you can install your own proxy to monitor mysqlnd.
Please, see How it works for details. However, to get started you do not need to look at the details. Copy the patterns shown in the quickstart instead.
Connections proxies are objects of the type MysqlndUhConnection. Connection proxy objects are installed by mysqlnd_uh_set_connection_proxy(). If you install the built-in class MysqlndUhConnection as a proxy, nothing happens. It behaves like a transparent proxy.
Przykład #1 Proxy registration, mysqlnd_uh.enable=1
<?php
mysqlnd_uh_set_connection_proxy(new MysqlndUhConnection());
$mysqli = new mysqli("localhost", "root", "", "test");
?>
The PHP_INI_SYSTEM configuration setting mysqlnd_uh.enable setting controls whether a proxy may be set. If disabled, the extension will throw errors of type E_WARNING
Przykład #2 Proxy installation disabled
mysqlnd_uh.enable=0
<?php
mysqlnd_uh_set_connection_proxy(new MysqlndUhConnection());
$mysqli = new mysqli("localhost", "root", "", "test");
?>
Powyższy przykład wyświetli:
PHP Warning: MysqlndUhConnection::__construct(): (Mysqlnd User Handler) The plugin has been disabled by setting the configuration parameter mysqlnd_uh.enabled = false. You must not use any of the base classes in %s on line %d PHP Warning: mysqlnd_uh_set_connection_proxy(): (Mysqlnd User Handler) The plugin has been disabled by setting the configuration parameter mysqlnd_uh.enable = false. The proxy has not been installed in %s on line %d
To monitor mysqlnd you have to write your own proxy object subclassing MysqlndUhConnection. Please, see the function reference for a the list of methods that can be subclassed. Alternatively, you can use reflection to inspect the built-in MysqlndUhConnection.
Create a new class proxy. Derive it from the built-in class MysqlndUhConnection. Replace the MysqlndUhConnection::connect(). method. Print out the host parameter value passed to the method. Make sure that you call the parent implementation of the connect method. Failing to do so may give unexpected and undesired results, including memory leaks and crashes.
Register your proxy and open three connections using the PHP MySQL extensions mysqli, mysql, PDO_MYSQL. If the extensions have been compiled to use the mysqlnd library, the proxy::connect method will be called three times, once for each connection opened.
Przykład #3 Connection proxy
<?php
class proxy extends MysqlndUhConnection {
public function connect($res, $host, $user, $passwd, $db, $port, $socket, $mysql_flags) {
printf("Connection opened to '%s'\n", $host);
/* Always call the parent implementation! */
return parent::connect($res, $host, $user, $passwd, $db, $port, $socket, $mysql_flags);
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysql = mysql_connect("localhost", "root", "");
$pdo = new PDO("mysql:host=localhost;dbname=test", "root", "");
?>
Powyższy przykład wyświetli:
Connection opened to 'localhost' Connection opened to 'localhost' Connection opened to 'localhost'
The use of prepared statement proxies follows the same pattern: create a proxy object of the type MysqlndUhPreparedStatement and install the proxy using mysqlnd_uh_set_statement_proxy().
Przykład #4 Prepared statement proxy
<?php
class stmt_proxy extends MysqlndUhPreparedStatement {
public function prepare($res, $query) {
printf("%s(%s)\n", __METHOD__, $query);
return parent::prepare($res, $query);
}
}
mysqlnd_uh_set_statement_proxy(new stmt_proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$stmt = $mysqli->prepare("SELECT 'mysqlnd hacking made easy' AS _msg FROM DUAL");
?>
Powyższy przykład wyświetli:
stmt_proxy::prepare(SELECT 'mysqlnd hacking made easy' AS _msg FROM DUAL)
Basic query monitoring
Basic monitoring of a query statement is easy with PECL/mysqlnd_uh. Combined with debug_print_backtrace() it can become a powerful tool, for example, to find the origin of certain statement. This may be desired when searching for slow queries but also after database refactorings to find code still accessing deprecated databases or tables. The latter may be a complicated matter to do otherwise, if the application uses auto-generated queries.
Przykład #1 Basic Monitoring
<?php
class conn_proxy extends MysqlndUhConnection {
public function query($res, $query) {
debug_print_backtrace();
return parent::query($res, $query);
}
}
class stmt_proxy extends MysqlndUhPreparedStatement {
public function prepare($res, $query) {
debug_print_backtrace();
return parent::prepare($res, $query);
}
}
mysqlnd_uh_set_connection_proxy(new conn_proxy());
mysqlnd_uh_set_statement_proxy(new stmt_proxy());
printf("Proxies installed...\n");
$pdo = new PDO("mysql:host=localhost;dbname=test", "root", "");
var_dump($pdo->query("SELECT 1 AS _one FROM DUAL")->fetchAll(PDO::FETCH_ASSOC));
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->prepare("SELECT 1 AS _two FROM DUAL");
?>
Powyższy przykład wyświetli:
#0 conn_proxy->query(Resource id #19, SELECT 1 AS _one FROM DUAL)
#1 PDO->query(SELECT 1 AS _one FROM DUAL) called at [example.php:19]
array(1) {
[0]=>
array(1) {
["_one"]=>
string(1) "1"
}
}
#0 stmt_proxy->prepare(Resource id #753, SELECT 1 AS _two FROM DUAL)
#1 mysqli->prepare(SELECT 1 AS _two FROM DUAL) called at [example.php:22]
For basic query monitoring you should install a connection and a prepared statement proxy. The connection proxy should subclass MysqlndUhConnection::query(). All database queries not using native prepared statements will call this method. In the example the query function is invoked by a PDO call. By default, PDO_MySQL is using prepared statement emulation.
All native prepared statements are prepared with the prepare method of mysqlnd exported through MysqlndUhPreparedStatement::prepare(). Subclass MysqlndUhPreparedStatement and overwrite prepare for native prepared statement monitoring.
Instalacja/Konfiguracja
Spis treści
Wymagania
PHP 5.3.3 or later. It is recommended to use PHP 5.4.0 or later to get access to the latest mysqlnd features.
The mysqlnd_uh user handler plugin supports all PHP applications and all available PHP MySQL extensions (mysqli, mysql, PDO_MYSQL). The PHP MySQL extension must be configured to use mysqlnd in order to be able to use the mysqlnd_uh plugin for mysqlnd.
The alpha versions makes use of some mysqli features. You must enable mysqli to compile the plugin. This requirement may be removed in the future. Note, that this requirement does not restrict you to use the plugin only with mysqli. You can use the plugin to monitor mysql, mysqli and PDO_MYSQL.
Instalacja
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/mysqlnd-uh
PECL/mysqlnd_uh is currently not available on Windows. The source code of the extension makes use of C99 constructs not allowed with PHP Windows builds.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| mysqlnd_uh.enable | 1 | PHP_INI_SYSTEM | |
| mysqlnd_uh.report_wrong_types | 1 | PHP_INI_ALL |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
mysqlnd_uh.enableinteger -
Enables or disables the plugin. If set to disabled, the extension will not allow users to plug into mysqlnd to hook mysqlnd calls.
-
mysqlnd_uh.report_wrong_typesinteger -
Wheter to report wrong return value types of user hooks as error of the type E_WARNING. It is strongly recommended to use this setting for detecting possible issues.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
Most of the constants refer to details of the MySQL Client Server Protocol. Please, refer to the MySQL reference manual to learn about their meaning. To avoid content duplication, only short descriptions are given.
MysqlndUhConnection::simpleCommand() related
The following constants can be used to detect what command is to be send through MysqlndUhConnection::simpleCommand().
-
MYSQLND_UH_MYSQLND_COM_SLEEP(integer) - MySQL Client Server protocol command: COM_SLEEP.
-
MYSQLND_UH_MYSQLND_COM_QUIT(integer) - MySQL Client Server protocol command: COM_QUIT.
-
MYSQLND_UH_MYSQLND_COM_INIT_DB(integer) - MySQL Client Server protocol command: COM_INIT_DB.
-
MYSQLND_UH_MYSQLND_COM_QUERY(integer) - MySQL Client Server protocol command: COM_QUERY.
-
MYSQLND_UH_MYSQLND_COM_FIELD_LIST(integer) - MySQL Client Server protocol command: COM_FIELD_LIST.
-
MYSQLND_UH_MYSQLND_COM_CREATE_DB(integer) - MySQL Client Server protocol command: COM_CREATE_DB.
-
MYSQLND_UH_MYSQLND_COM_DROP_DB(integer) - MySQL Client Server protocol command: COM_DROP_DB.
-
MYSQLND_UH_MYSQLND_COM_REFRESH(integer) - MySQL Client Server protocol command: COM_REFRESH.
-
MYSQLND_UH_MYSQLND_COM_SHUTDOWN(integer) - MySQL Client Server protocol command: COM_SHUTDOWN.
-
MYSQLND_UH_MYSQLND_COM_STATISTICS(integer) - MySQL Client Server protocol command: COM_STATISTICS.
-
MYSQLND_UH_MYSQLND_COM_PROCESS_INFO(integer) - MySQL Client Server protocol command: COM_PROCESS_INFO.
-
MYSQLND_UH_MYSQLND_COM_CONNECT(integer) - MySQL Client Server protocol command: COM_CONNECT.
-
MYSQLND_UH_MYSQLND_COM_PROCESS_KILL(integer) - MySQL Client Server protocol command: COM_PROCESS_KILL.
-
MYSQLND_UH_MYSQLND_COM_DEBUG(integer) - MySQL Client Server protocol command: COM_DEBUG.
-
MYSQLND_UH_MYSQLND_COM_PING(integer) - MySQL Client Server protocol command: COM_PING.
-
MYSQLND_UH_MYSQLND_COM_TIME(integer) - MySQL Client Server protocol command: COM_TIME.
-
MYSQLND_UH_MYSQLND_COM_DELAYED_INSERT(integer) - MySQL Client Server protocol command: COM_DELAYED_INSERT.
-
MYSQLND_UH_MYSQLND_COM_CHANGE_USER(integer) - MySQL Client Server protocol command: COM_CHANGE_USER.
-
MYSQLND_UH_MYSQLND_COM_BINLOG_DUMP(integer) - MySQL Client Server protocol command: COM_BINLOG_DUMP.
-
MYSQLND_UH_MYSQLND_COM_TABLE_DUMP(integer) - MySQL Client Server protocol command: COM_TABLE_DUMP.
-
MYSQLND_UH_MYSQLND_COM_CONNECT_OUT(integer) - MySQL Client Server protocol command: COM_CONNECT_OUT.
-
MYSQLND_UH_MYSQLND_COM_REGISTER_SLAVED(integer) - MySQL Client Server protocol command: COM_REGISTER_SLAVED.
-
MYSQLND_UH_MYSQLND_COM_STMT_PREPARE(integer) - MySQL Client Server protocol command: COM_STMT_PREPARE.
-
MYSQLND_UH_MYSQLND_COM_STMT_EXECUTE(integer) - MySQL Client Server protocol command: COM_STMT_EXECUTE.
-
MYSQLND_UH_MYSQLND_COM_STMT_SEND_LONG_DATA(integer) - MySQL Client Server protocol command: COM_STMT_SEND_LONG_DATA.
-
MYSQLND_UH_MYSQLND_COM_STMT_CLOSE(integer) - MySQL Client Server protocol command: COM_STMT_CLOSE.
-
MYSQLND_UH_MYSQLND_COM_STMT_RESET(integer) - MySQL Client Server protocol command: COM_STMT_RESET.
-
MYSQLND_UH_MYSQLND_COM_SET_OPTION(integer) - MySQL Client Server protocol command: COM_SET_OPTION.
-
MYSQLND_UH_MYSQLND_COM_STMT_FETCH(integer) - MySQL Client Server protocol command: COM_STMT_FETCH.
-
MYSQLND_UH_MYSQLND_COM_DAEMON(integer) - MySQL Client Server protocol command: COM_DAEMON.
-
MYSQLND_UH_MYSQLND_COM_END(integer) - MySQL Client Server protocol command: COM_END.
The following constants can be used to analyze the ok_packet argument of MysqlndUhConnection::simpleCommand().
-
MYSQLND_UH_MYSQLND_PROT_GREET_PACKET(integer) - MySQL Client Server protocol packet: greeting.
-
MYSQLND_UH_MYSQLND_PROT_AUTH_PACKET(integer) - MySQL Client Server protocol packet: authentification.
-
MYSQLND_UH_MYSQLND_PROT_OK_PACKET(integer) - MySQL Client Server protocol packet: OK.
-
MYSQLND_UH_MYSQLND_PROT_EOF_PACKET(integer) - MySQL Client Server protocol packet: EOF.
-
MYSQLND_UH_MYSQLND_PROT_CMD_PACKET(integer) - MySQL Client Server protocol packet: command.
-
MYSQLND_UH_MYSQLND_PROT_RSET_HEADER_PACKET(integer) - MySQL Client Server protocol packet: result set header.
-
MYSQLND_UH_MYSQLND_PROT_RSET_FLD_PACKET(integer) - MySQL Client Server protocol packet: resultset field.
-
MYSQLND_UH_MYSQLND_PROT_ROW_PACKET(integer) - MySQL Client Server protocol packet: row.
-
MYSQLND_UH_MYSQLND_PROT_STATS_PACKET(integer) - MySQL Client Server protocol packet: stats.
-
MYSQLND_UH_MYSQLND_PREPARE_RESP_PACKET(integer) - MySQL Client Server protocol packet: prepare response.
-
MYSQLND_UH_MYSQLND_CHG_USER_RESP_PACKET(integer) - MySQL Client Server protocol packet: change user response.
-
MYSQLND_UH_MYSQLND_PROT_LAST(integer) - No practical meaning. Last entry marker of internal C data structure list.
MysqlndUhConnection::close() related
The following constants can be used to detect why a connection has been closed through MysqlndUhConnection::close().
-
MYSQLND_UH_MYSQLND_CLOSE_EXPLICIT(integer) - User has called mysqlnd to close the connection.
-
MYSQLND_UH_MYSQLND_CLOSE_IMPLICIT(integer) - Implicity close, for example, during garbage connection.
-
MYSQLND_UH_MYSQLND_CLOSE_DISCONNECTED(integer) - Connection error.
-
MYSQLND_UH_MYSQLND_CLOSE_LAST(integer) - No practical meaning. Last entry marker of internal C data structure list.
MysqlndUhConnection::setServerOption() related
The following constants can be used to detect which option is set through MysqlndUhConnection::setServerOption().
-
MYSQLND_UH_SERVER_OPTION_MULTI_STATEMENTS_ON(integer) - Option: enables multi statement support.
-
MYSQLND_UH_SERVER_OPTION_MULTI_STATEMENTS_OFF(integer) - Option: disables multi statement support.
MysqlndUhConnection::setClientOption() related
The following constants can be used to detect which option is set through MysqlndUhConnection::setClientOption().
-
MYSQLND_UH_MYSQLND_OPTION_OPT_CONNECT_TIMEOUT(integer) - Option: connection timeout.
-
MYSQLND_UH_MYSQLND_OPTION_OPT_COMPRESS(integer) - Option: wheter the MySQL compressed protocol is to be used.
-
MYSQLND_UH_MYSQLND_OPTION_OPT_NAMED_PIPE(integer) - Option: named pipe to use for connection (Windows).
-
MYSQLND_UH_MYSQLND_OPTION_INIT_COMMAND(integer) - Option: init command to execute upon connect.
-
MYSQLND_UH_MYSQLND_READ_DEFAULT_FILE(integer) - Option: MySQL server default file to read upon connect.
-
MYSQLND_UH_MYSQLND_READ_DEFAULT_GROUP(integer) - Option: MySQL server default file group to read upon connect.
-
MYSQLND_UH_MYSQLND_SET_CHARSET_DIR(integer) - Option: charset description files directory.
-
MYSQLND_UH_MYSQLND_SET_CHARSET_NAME(integer) - Option: charset name.
-
MYSQLND_UH_MYSQLND_OPT_LOCAL_INFILE(integer) - Option: Wheter to allow LOAD DATA LOCAL INFILE use.
-
MYSQLND_UH_MYSQLND_OPT_PROTOCOL(integer) - Option: supported protocol version.
- Option: shared memory base name for shared memory connections.
-
MYSQLND_UH_MYSQLND_OPT_READ_TIMEOUT(integer) - Option: connection read timeout.
-
MYSQLND_UH_MYSQLND_OPT_WRITE_TIMEOUT(integer) - Option: connection write timeout.
-
MYSQLND_UH_MYSQLND_OPT_USE_RESULT(integer) - Option: unbuffered result sets.
-
MYSQLND_UH_MYSQLND_OPT_USE_REMOTE_CONNECTION(integer) - Embedded server related.
-
MYSQLND_UH_MYSQLND_OPT_USE_EMBEDDED_CONNECTION(integer) - Embedded server related.
-
MYSQLND_UH_MYSQLND_OPT_GUESS_CONNECTION(integer) - TODO
-
MYSQLND_UH_MYSQLND_SET_CLIENT_IP(integer) - TODO
-
MYSQLND_UH_MYSQLND_SECURE_AUTH(integer) - TODO
-
MYSQLND_UH_MYSQLND_REPORT_DATA_TRUNCATION(integer) - Option: Wheter to report data truncation.
-
MYSQLND_UH_MYSQLND_OPT_RECONNECT(integer) - Option: Wheter to reconnect automatically.
-
MYSQLND_UH_MYSQLND_OPT_SSL_VERIFY_SERVER_CERT(integer) - Option: TODO
-
MYSQLND_UH_MYSQLND_OPT_NET_CMD_BUFFER_SIZE(integer) - Option: mysqlnd network buffer size for commands.
-
MYSQLND_UH_MYSQLND_OPT_NET_READ_BUFFER_SIZE(integer) - Option: mysqlnd network buffer size for reading from the server.
-
MYSQLND_UH_MYSQLND_OPT_SSL_KEY(integer) - Option: SSL key.
-
MYSQLND_UH_MYSQLND_OPT_SSL_CERT(integer) - Option: SSL certificate.
-
MYSQLND_UH_MYSQLND_OPT_SSL_CA(integer) - Option: SSL CA.
-
MYSQLND_UH_MYSQLND_OPT_SSL_CAPATH(integer) - Option: Path to SSL CA.
-
MYSQLND_UH_MYSQLND_OPT_SSL_CIPHER(integer) - Option: SSL cipher.
-
MYSQLND_UH_MYSQLND_OPT_SSL_PASSPHRASE(integer) - Option: SSL passphrase.
-
MYSQLND_UH_SERVER_OPTION_PLUGIN_DIR(integer) - Option: server plugin directory.
-
MYSQLND_UH_SERVER_OPTION_DEFAULT_AUTH(integer) - Option: default authentification method.
-
MYSQLND_UH_SERVER_OPTION_SET_CLIENT_IP(integer) - TODO
-
MYSQLND_UH_MYSQLND_OPT_MAX_ALLOWED_PACKET(integer) - Option: maximum allowd packet size. Available as of PHP 5.4.0.
-
MYSQLND_UH_MYSQLND_OPT_AUTH_PROTOCOL(integer) - Option: TODO. Available as of PHP 5.4.0.
-
MYSQLND_UH_MYSQLND_OPT_INT_AND_FLOAT_NATIVE(integer) - Option: make mysqlnd return integer and float columns as long even when using the MySQL Client Server text protocol. Only available with a custom build of mysqlnd.
Other
The plugins version number can be obtained using
MYSQLND_UH_VERSION or
MYSQLND_UH_VERSION_ID.
MYSQLND_UH_VERSION
is the string representation of the numerical version number
MYSQLND_UH_VERSION_ID, which is an integer such as 10000.
Developers can calculate the version number as follows.
| Version (part) | Example |
|---|---|
| Major*10000 | 1*10000 = 10000 |
| Minor*100 | 0*100 = 0 |
| Patch | 0 = 0 |
| MYSQLND_UH_VERSION_ID | 10000 |
The MysqlndUhConnection class
(PECL mysqlnd-uh >= 1.0.0-alpha)
Wstęp
Krótki opis klasy
$connection
, string $user
, string $password
, string $database
, bool $silent
, int $passwd_len
)$connection
, string $host
, string $use"
, string $password
, string $database
, int $port
, string $socket
, int $mysql_flags
)$connection
, string $query
, string $achtung_wild
, string $par1
)$connection
, mysqlnd_statement $mysqlnd_stmt
)$connection
, int $command
, string $arg
, int $ok_packet
, bool $silent
, bool $ignore_upsert_status
)$connection
, int $ok_packet
, bool $silent
, int $command
, bool $ignore_upsert_status
)$connection
, string $key
, string $cert
, string $ca
, string $capath
, string $cipher
)MysqlndUhConnection::changeUser
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::changeUser — Changes the user of the specified mysqlnd database connection
Opis
$connection
, string $user
, string $password
, string $database
, bool $silent
, int $passwd_len
)Changes the user of the specified mysqlnd database connection
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
-
user -
The MySQL user name.
-
password -
The MySQL password.
-
database -
The MySQL database to change to.
-
silent -
Controls if mysqlnd is allowed to emit errors or not.
-
passwd_len -
Length of the MySQL password.
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhConnection::changeUser() example
<?php
class proxy extends MysqlndUhConnection {
/* Hook mysqlnd's connection::change_user call */
public function changeUser($res, $user, $passwd, $db, $silent, $passwd_len) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::changeUser($res, $user, $passwd, $db, $silent, $passwd_len);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
/* Install proxy/hooks to be used with all future mysqlnd connection */
mysqlnd_uh_set_connection_proxy(new proxy());
/* Create mysqli connection which is using the mysqlnd library */
$mysqli = new mysqli("localhost", "root", "", "test");
/* Example of a user API call which triggers the hooked mysqlnd call */
var_dump($mysqli->change_user("root", "bar", "test"));
?>
Powyższy przykład wyświetli:
proxy::changeUser(array ( 0 => NULL, 1 => 'root', 2 => 'bar', 3 => 'test', 4 => false, 5 => 3, )) proxy::changeUser returns false bool(false)
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_change_user() - Changes the user of the specified database connection
MysqlndUhConnection::charsetName
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::charsetName — Returns the default character set for the database connection
Opis
$connection
)Returns the default character set for the database connection.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
The default cahracter set.
Przykłady
Przykład #1 MysqlndUhConnection::charsetName() example
<?php
class proxy extends MysqlndUhConnection {
public function charsetName($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::charsetName($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
var_dump(mysqli_character_set_name($mysqli));
?>
Powyższy przykład wyświetli:
proxy::charsetName(array ( 0 => NULL, )) proxy::charsetName returns 'latin1' string(6) "latin1"
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_character_set_name() - Returns the default character set for the database connection
MysqlndUhConnection::close
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::close — Closes a previously opened database connection
Opis
$connection
, int $close_type
)Closes a previously opened database connection.
Informacja:
Failing to call the parent implementation may cause memory leaks or crash PHP. This is not considered a bug. Please, keep in mind that the mysqlnd library functions have never been designed to be exposed to the user space.
Parametry
-
connection -
The connection to be closed. Do not modify!
-
close_type -
Why the connection is to be closed. The value of
close_typeis one ofMYSQLND_UH_MYSQLND_CLOSE_EXPLICIT,MYSQLND_UH_MYSQLND_CLOSE_IMPLICIT,MYSQLND_UH_MYSQLND_CLOSE_DISCONNECTEDorMYSQLND_UH_MYSQLND_CLOSE_LAST. The latter should never be seen, unless the default behaviour of the mysqlnd library has been changed by a plugin.
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhConnection::close() example
<?php
function close_type_to_string($close_type) {
$mapping = array(
MYSQLND_UH_MYSQLND_CLOSE_DISCONNECTED => "MYSQLND_UH_MYSQLND_CLOSE_DISCONNECTED",
MYSQLND_UH_MYSQLND_CLOSE_EXPLICIT => "MYSQLND_UH_MYSQLND_CLOSE_EXPLICIT",
MYSQLND_UH_MYSQLND_CLOSE_IMPLICIT => "MYSQLND_UH_MYSQLND_CLOSE_IMPLICIT",
MYSQLND_UH_MYSQLND_CLOSE_LAST => "MYSQLND_UH_MYSQLND_CLOSE_IMPLICIT"
);
return (isset($mapping[$close_type])) ? $mapping[$close_type] : 'unknown';
}
class proxy extends MysqlndUhConnection {
public function close($res, $close_type) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
printf("close_type = %s\n", close_type_to_string($close_type));
/* WARNING: you must call the parent */
$ret = parent::close($res, $close_type);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->close();
?>
Powyższy przykład wyświetli:
proxy::close(array ( 0 => NULL, 1 => 0, )) close_type = MYSQLND_UH_MYSQLND_CLOSE_EXPLICIT proxy::close returns true
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_close() - Closes a previously opened database connection
- mysql_close() - Zamyka połączenie MySQL
MysqlndUhConnection::connect
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::connect — Open a new connection to the MySQL server
Opis
$connection
, string $host
, string $use"
, string $password
, string $database
, int $port
, string $socket
, int $mysql_flags
)Open a new connection to the MySQL server.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
-
host -
Can be either a host name or an IP address. Passing the NULL value or the string "localhost" to this parameter, the local host is assumed. When possible, pipes will be used instead of the TCP/IP protocol.
-
user -
The MySQL user name.
-
password -
If not provided or
NULL, the MySQL server will attempt to authenticate the user against those user records which have no password only. This allows one username to be used with different permissions (depending on if a password as provided or not). -
database -
If provided will specify the default database to be used when performing queries.
-
port -
Specifies the port number to attempt to connect to the MySQL server.
-
socket -
Specifies the socket or named pipe that should be used. If
NULL, mysqlnd will default to /tmp/mysql.sock. -
mysql_flags -
Connection options.
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhConnection::connect() example
<?php
class proxy extends MysqlndUhConnection {
public function connect($res, $host, $user, $passwd, $db, $port, $socket, $mysql_flags) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::connect($res, $host, $user, $passwd, $db, $port, $socket, $mysql_flags);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
?>
Powyższy przykład wyświetli:
proxy::connect(array ( 0 => NULL, 1 => 'localhost', 2 => 'root', 3 => '', 4 => 'test', 5 => 3306, 6 => NULL, 7 => 131072, )) proxy::connect returns true
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_connect() - Alias dla mysqli::__construct
- mysql_connect() - Otwiera połączenie do serwera MySQL
MysqlndUhConnection::__construct
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::__construct — The __construct purpose
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
MysqlndUhConnection::endPSession
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::endPSession — End a persistent connection
Opis
$connection
)End a persistent connection
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhConnection::endPSession() example
<?php
class proxy extends MysqlndUhConnection {
public function endPSession($conn) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::endPSession($conn);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("p:localhost", "root", "", "test");
$mysqli->close();
?>
Powyższy przykład wyświetli:
proxy::endPSession(array ( 0 => NULL, )) proxy::endPSession returns true
MysqlndUhConnection::escapeString
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::escapeString — Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection
Opis
$connection
, string $escape_string
)Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection.
Parametry
-
MYSQLND_UH_RES_MYSQLND_NAME -
Mysqlnd connection handle. Do not modify!
-
escape_string -
The string to be escaped.
Zwracane wartości
The escaped string.
Przykłady
Przykład #1 MysqlndUhConnection::escapeString() example
<?php
class proxy extends MysqlndUhConnection {
public function escapeString($res, $string) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::escapeString($res, $string);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->set_charset("latin1");
$mysqli->real_escape_string("test0'test");
?>
Powyższy przykład wyświetli:
proxy::escapeString(array ( 0 => NULL, 1 => 'test0\'test', )) proxy::escapeString returns 'test0\\\'test'
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_real_escape_string() - Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection
- mysql_real_escape_string() - Dodaje znaki unikowe w łańcuchu znaków do użycia w instrukcji SQL
MysqlndUhConnection::getAffectedRows
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::getAffectedRows — Gets the number of affected rows in a previous MySQL operation
Opis
$connection
)Gets the number of affected rows in a previous MySQL operation.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
Number of affected rows.
Przykłady
Przykład #1 MysqlndUhConnection::getAffectedRows() example
<?php
class proxy extends MysqlndUhConnection {
public function getAffectedRows($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::getAffectedRows($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1)");
var_dump($mysqli->affected_rows);
?>
Powyższy przykład wyświetli:
proxy::getAffectedRows(array ( 0 => NULL, )) proxy::getAffectedRows returns 1 int(1)
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_affected_rows() - Gets the number of affected rows in a previous MySQL operation
- mysql_affected_rows() - Zwraca liczbę wierszy przetworzonych w poprzedniej operacji MySQL
MysqlndUhConnection::getErrorNumber
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::getErrorNumber — Returns the error code for the most recent function call
Opis
$connection
)Returns the error code for the most recent function call.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
Error code for the most recent function call.
Przykłady
MysqlndUhConnection::getErrorNumber() is not only executed after the invocation of a user space API call which maps directly to it but also called internally.
Przykład #1 MysqlndUhConnection::getErrorNumber() example
<?php
class proxy extends MysqlndUhConnection {
public function getErrorNumber($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::getErrorNumber($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
printf("connect...\n");
$mysqli = new mysqli("localhost", "root", "", "test");
printf("query...\n");
$mysqli->query("PLEASE_LET_THIS_BE_INVALID_SQL");
printf("errno...\n");
var_dump($mysqli->errno);
printf("close...\n");
$mysqli->close();
?>
Powyższy przykład wyświetli:
connect... proxy::getErrorNumber(array ( 0 => NULL, )) proxy::getErrorNumber returns 0 query... errno... proxy::getErrorNumber(array ( 0 => NULL, )) proxy::getErrorNumber returns 1064 int(1064) close...
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- MysqlndUhConnection::getErrorString() - Returns a string description of the last error
- mysqli_errno() - Returns the error code for the most recent function call
- mysql_errno() - Zwraca liczbową wartość kodu błędu z poprzedniej operacji MySQL
MysqlndUhConnection::getErrorString
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::getErrorString — Returns a string description of the last error
Opis
$connection
)Returns a string description of the last error.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
Error string for the most recent function call.
Przykłady
MysqlndUhConnection::getErrorString() is not only executed after the invocation of a user space API call which maps directly to it but also called internally.
Przykład #1 MysqlndUhConnection::getErrorString() example
<?php
class proxy extends MysqlndUhConnection {
public function getErrorString($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::getErrorString($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
printf("connect...\n");
$mysqli = new mysqli("localhost", "root", "", "test");
printf("query...\n");
$mysqli->query("WILL_I_EVER_LEARN_SQL?");
printf("errno...\n");
var_dump($mysqli->error);
printf("close...\n");
$mysqli->close();
?>
Powyższy przykład wyświetli:
connect... proxy::getErrorString(array ( 0 => NULL, )) proxy::getErrorString returns '' query... errno... proxy::getErrorString(array ( 0 => NULL, )) proxy::getErrorString returns 'You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near \'WILL_I_EVER_LEARN_SQL?\' at line 1' string(168) "You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 'WILL_I_EVER_LEARN_SQL?' at line 1" close...
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- MysqlndUhConnection::getErrorNumber() - Returns the error code for the most recent function call
- mysqli_error() - Returns a string description of the last error
- mysql_error() - Zwraca tekst komunikatu błędu z ostatniej operacji MySQL
MysqlndUhConnection::getFieldCount
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::getFieldCount — Returns the number of columns for the most recent query
Opis
$connection
)Returns the number of columns for the most recent query.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
Number of columns.
Przykłady
MysqlndUhConnection::getFieldCount() is not only executed after the invocation of a user space API call which maps directly to it but also called internally.
Przykład #1 MysqlndUhConnection::getFieldCount() example
<?php
class proxy extends MysqlndUhConnection {
public function getFieldCount($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::getFieldCount($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->query("WILL_I_EVER_LEARN_SQL?");
var_dump($mysqli->field_count);
$mysqli->query("SELECT 1, 2, 3 FROM DUAL");
var_dump($mysqli->field_count);
?>
Powyższy przykład wyświetli:
proxy::getFieldCount(array ( 0 => NULL, )) proxy::getFieldCount returns 0 int(0) proxy::getFieldCount(array ( 0 => NULL, )) proxy::getFieldCount returns 3 proxy::getFieldCount(array ( 0 => NULL, )) proxy::getFieldCount returns 3 int(3)
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_field_count() - Returns the number of columns for the most recent query
MysqlndUhConnection::getHostInformation
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::getHostInformation — Returns a string representing the type of connection used
Opis
$connection
)Returns a string representing the type of connection used.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
Connection description.
Przykłady
Przykład #1 MysqlndUhConnection::getHostInformation() example
<?php
class proxy extends MysqlndUhConnection {
public function getHostInformation($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::getHostInformation($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
var_dump($mysqli->host_info);
?>
Powyższy przykład wyświetli:
proxy::getHostInformation(array ( 0 => NULL, )) proxy::getHostInformation returns 'Localhost via UNIX socket' string(25) "Localhost via UNIX socket"
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_get_host_info() - Returns a string representing the type of connection used
- mysql_get_host_info() - Pobiera informacje o hoście MySQL
MysqlndUhConnection::getLastInsertId
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::getLastInsertId — Returns the auto generated id used in the last query.
Opis
$connection
)Returns the auto generated id used in the last query.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
Last insert id.
Przykłady
Przykład #1 MysqlndUhConnection::getLastInsertId() example
<?php
class proxy extends MysqlndUhConnection {
public function getLastInsertId($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::getLastInsertId($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT AUTO_INCREMENT PRIMARY KEY, col VARCHAR(255))");
$mysqli->query("INSERT INTO test(col) VALUES ('a')");
var_dump($mysqli->insert_id);
?>
Powyższy przykład wyświetli:
proxy::getLastInsertId(array ( 0 => NULL, )) proxy::getLastInsertId returns 1 int(1)
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_insert_id() - Returns the auto generated id used in the last query
- mysql_insert_id() - Podaje numer ID wygenerowany podczas ostatniej operacji INSERT
MysqlndUhConnection::getLastMessage
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::getLastMessage — Retrieves information about the most recently executed query
Opis
$connection
)Retrieves information about the most recently executed query.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
Last message. Trying to return a string longer than 511 bytes will cause an error of the type E_WARNING and result in the string being truncated.
Przykłady
Przykład #1 MysqlndUhConnection::getLastMessage() example
<?php
class proxy extends MysqlndUhConnection {
public function getLastMessage($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::getLastMessage($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
var_dump($mysqli->info);
$mysqli->query("DROP TABLE IF EXISTS test");
var_dump($mysqli->info);
?>
Powyższy przykład wyświetli:
proxy::getLastMessage(array ( 0 => NULL, )) proxy::getLastMessage returns '' string(0) "" proxy::getLastMessage(array ( 0 => NULL, )) proxy::getLastMessage returns '' string(0) ""
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_info() - Retrieves information about the most recently executed query
- mysql_info() - Pobiera informacje o ostatnim zapytaniu
MysqlndUhConnection::getProtocolInformation
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::getProtocolInformation — Returns the version of the MySQL protocol used
Opis
$connection
)Returns the version of the MySQL protocol used.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
The protocol version.
Przykłady
Przykład #1 MysqlndUhConnection::getProtocolInformation() example
<?php
class proxy extends MysqlndUhConnection {
public function getProtocolInformation($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::getProtocolInformation($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
var_dump($mysqli->protocol_version);
?>
Powyższy przykład wyświetli:
proxy::getProtocolInformation(array ( 0 => NULL, )) proxy::getProtocolInformation returns 10 int(10)
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_get_proto_info() - Returns the version of the MySQL protocol used
- mysql_get_proto_info() - Pobiera informacje o protokole MySQL
MysqlndUhConnection::getServerInformation
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::getServerInformation — Returns the version of the MySQL server
Opis
$connection
)Returns the version of the MySQL server.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
The server version.
Przykłady
Przykład #1 MysqlndUhConnection::getServerInformation() example
<?php
class proxy extends MysqlndUhConnection {
public function getServerInformation($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::getServerInformation($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
var_dump($mysqli->server_info);
?>
Powyższy przykład wyświetli:
proxy::getServerInformation(array ( 0 => NULL, )) proxy::getServerInformation returns '5.1.45-debug-log' string(16) "5.1.45-debug-log"
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_get_server_info() - Returns the version of the MySQL server
- mysql_get_server_info() - Pobiera informacje o serwerze MySQL
MysqlndUhConnection::getServerStatistics
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::getServerStatistics — Gets the current system status
Opis
$connection
)Gets the current system status.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
The system status message.
Przykłady
Przykład #1 MysqlndUhConnection::getServerStatistics() example
<?php
class proxy extends MysqlndUhConnection {
public function getServerStatistics($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::getServerStatistics($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
var_dump(mysqli_stat($mysqli));
?>
Powyższy przykład wyświetli:
proxy::getServerStatistics(array ( 0 => NULL, )) proxy::getServerStatistics returns 'Uptime: 2059995 Threads: 1 Questions: 126157 Slow queries: 0 Opens: 6377 Flush tables: 1 Open tables: 18 Queries per second avg: 0.61' string(140) "Uptime: 2059995 Threads: 1 Questions: 126157 Slow queries: 0 Opens: 6377 Flush tables: 1 Open tables: 18 Queries per second avg: 0.61"
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_stat() - Gets the current system status
- mysql_stat() - Pobiera aktualny stan systemu
MysqlndUhConnection::getServerVersion
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::getServerVersion — Returns the version of the MySQL server as an integer
Opis
$connection
)Returns the version of the MySQL server as an integer.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
The MySQL version.
Przykłady
Przykład #1 MysqlndUhConnection::getServerVersion() example
<?php
class proxy extends MysqlndUhConnection {
public function getServerVersion($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::getServerVersion($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
var_dump($mysqli->server_version);
?>
Powyższy przykład wyświetli:
proxy::getServerVersion(array ( 0 => NULL, )) proxy::getServerVersion returns 50145 int(50145)
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_get_server_version() - Returns the version of the MySQL server as an integer
- mysql_get_server_version()
MysqlndUhConnection::getSqlstate
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::getSqlstate — Returns the SQLSTATE error from previous MySQL operation
Opis
$connection
)Returns the SQLSTATE error from previous MySQL operation.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
The SQLSTATE code.
Przykłady
Przykład #1 MysqlndUhConnection::getSqlstate() example
<?php
class proxy extends MysqlndUhConnection {
public function getSqlstate($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::getSqlstate($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
var_dump($mysqli->sqlstate);
$mysqli->query("AN_INVALID_REQUEST_TO_PROVOKE_AN_ERROR");
var_dump($mysqli->sqlstate);
?>
Powyższy przykład wyświetli:
proxy::getSqlstate(array ( 0 => NULL, )) proxy::getSqlstate returns '00000' string(5) "00000" proxy::getSqlstate(array ( 0 => NULL, )) proxy::getSqlstate returns '42000' string(5) "42000"
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_sql_state()
MysqlndUhConnection::getStatistics
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::getStatistics — Returns statistics about the client connection.
Opis
$connection
)Returns statistics about the client connection.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
Connection statistics collected by mysqlnd.
Przykłady
Przykład #1 MysqlndUhConnection::getStatistics() example
<?php
class proxy extends MysqlndUhConnection {
public function getStatistics($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::getStatistics($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
var_dump($mysqli->get_connection_stats());
?>
Powyższy przykład wyświetli:
proxy::getStatistics(array (
0 => NULL,
))
proxy::getStatistics returns array (
'bytes_sent' => '73',
'bytes_received' => '77',
'packets_sent' => '2',
'packets_received' => '2',
'protocol_overhead_in' => '8',
'protocol_overhead_out' => '8',
'bytes_received_ok_packet' => '0',
'bytes_received_eof_packet' => '0',
'bytes_received_rset_header_packet' => '0',
'bytes_received_rset_field_meta_packet' => '0',
'bytes_received_rset_row_packet' => '0',
'bytes_received_prepare_response_packet' => '0',
'bytes_received_change_user_packet' => '0',
'packets_sent_command' => '0',
'packets_received_ok' => '0',
'packets_received_eof' => '0',
'packets_received_rset_header' => '0',
'packets_received_rset_field_meta' => '0',
'packets_received_rset_row' => '0',
'packets_received_prepare_response' => '0',
'packets_received_change_user' => '0',
'result_set_queries' => '0',
'non_result_set_queries' => '0',
'no_index_used' => '0',
'bad_index_used' => '0',
'slow_queries' => '0',
'buffered_sets' => '0',
'unbuffered_sets' => '0',
'ps_buffered_sets' => '0',
'ps_unbuffered_sets' => '0',
'flushed_normal_sets' => '0',
'flushed_ps_sets' => '0',
'ps_prepared_never_executed' => '0',
'ps_prepared_once_executed' => '0',
'rows_fetched_from_server_normal' => '0',
'rows_fetched_from_server_ps' => '0',
'rows_buffered_from_client_normal' => '0',
'rows_buffered_from_client_ps' => '0',
'rows_fetched_from_client_normal_buffered' => '0',
'rows_fetched_from_client_normal_unbuffered' => '0',
'rows_fetched_from_client_ps_buffered' => '0',
'rows_fetched_from_client_ps_unbuffered' => '0',
'rows_fetched_from_client_ps_cursor' => '0',
'rows_affected_normal' => '0',
'rows_affected_ps' => '0',
'rows_skipped_normal' => '0',
'rows_skipped_ps' => '0',
'copy_on_write_saved' => '0',
'copy_on_write_performed' => '0',
'command_buffer_too_small' => '0',
'connect_success' => '1',
'connect_failure' => '0',
'connection_reused' => '0',
'reconnect' => '0',
'pconnect_success' => '0',
'active_connections' => '1',
'active_persistent_connections' => '0',
'explicit_close' => '0',
'implicit_close' => '0',
'disconnect_close' => '0',
'in_middle_of_command_close' => '0',
'explicit_free_result' => '0',
'implicit_free_result' => '0',
'explicit_stmt_close' => '0',
'implicit_stmt_close' => '0',
'mem_emalloc_count' => '0',
'mem_emalloc_amount' => '0',
'mem_ecalloc_count' => '0',
'mem_ecalloc_amount' => '0',
'mem_erealloc_count' => '0',
'mem_erealloc_amount' => '0',
'mem_efree_count' => '0',
'mem_efree_amount' => '0',
'mem_malloc_count' => '0',
'mem_malloc_amount' => '0',
'mem_calloc_count' => '0',
'mem_calloc_amount' => '0',
'mem_realloc_count' => '0',
'mem_realloc_amount' => '0',
'mem_free_count' => '0',
'mem_free_amount' => '0',
'mem_estrndup_count' => '0',
'mem_strndup_count' => '0',
'mem_estndup_count' => '0',
'mem_strdup_count' => '0',
'proto_text_fetched_null' => '0',
'proto_text_fetched_bit' => '0',
'proto_text_fetched_tinyint' => '0',
'proto_text_fetched_short' => '0',
'proto_text_fetched_int24' => '0',
'proto_text_fetched_int' => '0',
'proto_text_fetched_bigint' => '0',
'proto_text_fetched_decimal' => '0',
'proto_text_fetched_float' => '0',
'proto_text_fetched_double' => '0',
'proto_text_fetched_date' => '0',
'proto_text_fetched_year' => '0',
'proto_text_fetched_time' => '0',
'proto_text_fetched_datetime' => '0',
'proto_text_fetched_timestamp' => '0',
'proto_text_fetched_string' => '0',
'proto_text_fetched_blob' => '0',
'proto_text_fetched_enum' => '0',
'proto_text_fetched_set' => '0',
'proto_text_fetched_geometry' => '0',
'proto_text_fetched_other' => '0',
'proto_binary_fetched_null' => '0',
'proto_binary_fetched_bit' => '0',
'proto_binary_fetched_tinyint' => '0',
'proto_binary_fetched_short' => '0',
'proto_binary_fetched_int24' => '0',
'proto_binary_fetched_int' => '0',
'proto_binary_fetched_bigint' => '0',
'proto_binary_fetched_decimal' => '0',
'proto_binary_fetched_float' => '0',
'proto_binary_fetched_double' => '0',
'proto_binary_fetched_date' => '0',
'proto_binary_fetched_year' => '0',
'proto_binary_fetched_time' => '0',
'proto_binary_fetched_datetime' => '0',
'proto_binary_fetched_timestamp' => '0',
'proto_binary_fetched_string' => '0',
'proto_binary_fetched_blob' => '0',
'proto_binary_fetched_enum' => '0',
'proto_binary_fetched_set' => '0',
'proto_binary_fetched_geometry' => '0',
'proto_binary_fetched_other' => '0',
'init_command_executed_count' => '0',
'init_command_failed_count' => '0',
'com_quit' => '0',
'com_init_db' => '0',
'com_query' => '0',
'com_field_list' => '0',
'com_create_db' => '0',
'com_drop_db' => '0',
'com_refresh' => '0',
'com_shutdown' => '0',
'com_statistics' => '0',
'com_process_info' => '0',
'com_connect' => '0',
'com_process_kill' => '0',
'com_debug' => '0',
'com_ping' => '0',
'com_time' => '0',
'com_delayed_insert' => '0',
'com_change_user' => '0',
'com_binlog_dump' => '0',
'com_table_dump' => '0',
'com_connect_out' => '0',
'com_register_slave' => '0',
'com_stmt_prepare' => '0',
'com_stmt_execute' => '0',
'com_stmt_send_long_data' => '0',
'com_stmt_close' => '0',
'com_stmt_reset' => '0',
'com_stmt_set_option' => '0',
'com_stmt_fetch' => '0',
'com_deamon' => '0',
'bytes_received_real_data_normal' => '0',
'bytes_received_real_data_ps' => '0',
)
array(160) {
["bytes_sent"]=>
string(2) "73"
["bytes_received"]=>
string(2) "77"
["packets_sent"]=>
string(1) "2"
["packets_received"]=>
string(1) "2"
["protocol_overhead_in"]=>
string(1) "8"
["protocol_overhead_out"]=>
string(1) "8"
["bytes_received_ok_packet"]=>
string(1) "0"
["bytes_received_eof_packet"]=>
string(1) "0"
["bytes_received_rset_header_packet"]=>
string(1) "0"
["bytes_received_rset_field_meta_packet"]=>
string(1) "0"
["bytes_received_rset_row_packet"]=>
string(1) "0"
["bytes_received_prepare_response_packet"]=>
string(1) "0"
["bytes_received_change_user_packet"]=>
string(1) "0"
["packets_sent_command"]=>
string(1) "0"
["packets_received_ok"]=>
string(1) "0"
["packets_received_eof"]=>
string(1) "0"
["packets_received_rset_header"]=>
string(1) "0"
["packets_received_rset_field_meta"]=>
string(1) "0"
["packets_received_rset_row"]=>
string(1) "0"
["packets_received_prepare_response"]=>
string(1) "0"
["packets_received_change_user"]=>
string(1) "0"
["result_set_queries"]=>
string(1) "0"
["non_result_set_queries"]=>
string(1) "0"
["no_index_used"]=>
string(1) "0"
["bad_index_used"]=>
string(1) "0"
["slow_queries"]=>
string(1) "0"
["buffered_sets"]=>
string(1) "0"
["unbuffered_sets"]=>
string(1) "0"
["ps_buffered_sets"]=>
string(1) "0"
["ps_unbuffered_sets"]=>
string(1) "0"
["flushed_normal_sets"]=>
string(1) "0"
["flushed_ps_sets"]=>
string(1) "0"
["ps_prepared_never_executed"]=>
string(1) "0"
["ps_prepared_once_executed"]=>
string(1) "0"
["rows_fetched_from_server_normal"]=>
string(1) "0"
["rows_fetched_from_server_ps"]=>
string(1) "0"
["rows_buffered_from_client_normal"]=>
string(1) "0"
["rows_buffered_from_client_ps"]=>
string(1) "0"
["rows_fetched_from_client_normal_buffered"]=>
string(1) "0"
["rows_fetched_from_client_normal_unbuffered"]=>
string(1) "0"
["rows_fetched_from_client_ps_buffered"]=>
string(1) "0"
["rows_fetched_from_client_ps_unbuffered"]=>
string(1) "0"
["rows_fetched_from_client_ps_cursor"]=>
string(1) "0"
["rows_affected_normal"]=>
string(1) "0"
["rows_affected_ps"]=>
string(1) "0"
["rows_skipped_normal"]=>
string(1) "0"
["rows_skipped_ps"]=>
string(1) "0"
["copy_on_write_saved"]=>
string(1) "0"
["copy_on_write_performed"]=>
string(1) "0"
["command_buffer_too_small"]=>
string(1) "0"
["connect_success"]=>
string(1) "1"
["connect_failure"]=>
string(1) "0"
["connection_reused"]=>
string(1) "0"
["reconnect"]=>
string(1) "0"
["pconnect_success"]=>
string(1) "0"
["active_connections"]=>
string(1) "1"
["active_persistent_connections"]=>
string(1) "0"
["explicit_close"]=>
string(1) "0"
["implicit_close"]=>
string(1) "0"
["disconnect_close"]=>
string(1) "0"
["in_middle_of_command_close"]=>
string(1) "0"
["explicit_free_result"]=>
string(1) "0"
["implicit_free_result"]=>
string(1) "0"
["explicit_stmt_close"]=>
string(1) "0"
["implicit_stmt_close"]=>
string(1) "0"
["mem_emalloc_count"]=>
string(1) "0"
["mem_emalloc_amount"]=>
string(1) "0"
["mem_ecalloc_count"]=>
string(1) "0"
["mem_ecalloc_amount"]=>
string(1) "0"
["mem_erealloc_count"]=>
string(1) "0"
["mem_erealloc_amount"]=>
string(1) "0"
["mem_efree_count"]=>
string(1) "0"
["mem_efree_amount"]=>
string(1) "0"
["mem_malloc_count"]=>
string(1) "0"
["mem_malloc_amount"]=>
string(1) "0"
["mem_calloc_count"]=>
string(1) "0"
["mem_calloc_amount"]=>
string(1) "0"
["mem_realloc_count"]=>
string(1) "0"
["mem_realloc_amount"]=>
string(1) "0"
["mem_free_count"]=>
string(1) "0"
["mem_free_amount"]=>
string(1) "0"
["mem_estrndup_count"]=>
string(1) "0"
["mem_strndup_count"]=>
string(1) "0"
["mem_estndup_count"]=>
string(1) "0"
["mem_strdup_count"]=>
string(1) "0"
["proto_text_fetched_null"]=>
string(1) "0"
["proto_text_fetched_bit"]=>
string(1) "0"
["proto_text_fetched_tinyint"]=>
string(1) "0"
["proto_text_fetched_short"]=>
string(1) "0"
["proto_text_fetched_int24"]=>
string(1) "0"
["proto_text_fetched_int"]=>
string(1) "0"
["proto_text_fetched_bigint"]=>
string(1) "0"
["proto_text_fetched_decimal"]=>
string(1) "0"
["proto_text_fetched_float"]=>
string(1) "0"
["proto_text_fetched_double"]=>
string(1) "0"
["proto_text_fetched_date"]=>
string(1) "0"
["proto_text_fetched_year"]=>
string(1) "0"
["proto_text_fetched_time"]=>
string(1) "0"
["proto_text_fetched_datetime"]=>
string(1) "0"
["proto_text_fetched_timestamp"]=>
string(1) "0"
["proto_text_fetched_string"]=>
string(1) "0"
["proto_text_fetched_blob"]=>
string(1) "0"
["proto_text_fetched_enum"]=>
string(1) "0"
["proto_text_fetched_set"]=>
string(1) "0"
["proto_text_fetched_geometry"]=>
string(1) "0"
["proto_text_fetched_other"]=>
string(1) "0"
["proto_binary_fetched_null"]=>
string(1) "0"
["proto_binary_fetched_bit"]=>
string(1) "0"
["proto_binary_fetched_tinyint"]=>
string(1) "0"
["proto_binary_fetched_short"]=>
string(1) "0"
["proto_binary_fetched_int24"]=>
string(1) "0"
["proto_binary_fetched_int"]=>
string(1) "0"
["proto_binary_fetched_bigint"]=>
string(1) "0"
["proto_binary_fetched_decimal"]=>
string(1) "0"
["proto_binary_fetched_float"]=>
string(1) "0"
["proto_binary_fetched_double"]=>
string(1) "0"
["proto_binary_fetched_date"]=>
string(1) "0"
["proto_binary_fetched_year"]=>
string(1) "0"
["proto_binary_fetched_time"]=>
string(1) "0"
["proto_binary_fetched_datetime"]=>
string(1) "0"
["proto_binary_fetched_timestamp"]=>
string(1) "0"
["proto_binary_fetched_string"]=>
string(1) "0"
["proto_binary_fetched_blob"]=>
string(1) "0"
["proto_binary_fetched_enum"]=>
string(1) "0"
["proto_binary_fetched_set"]=>
string(1) "0"
["proto_binary_fetched_geometry"]=>
string(1) "0"
["proto_binary_fetched_other"]=>
string(1) "0"
["init_command_executed_count"]=>
string(1) "0"
["init_command_failed_count"]=>
string(1) "0"
["com_quit"]=>
string(1) "0"
["com_init_db"]=>
string(1) "0"
["com_query"]=>
string(1) "0"
["com_field_list"]=>
string(1) "0"
["com_create_db"]=>
string(1) "0"
["com_drop_db"]=>
string(1) "0"
["com_refresh"]=>
string(1) "0"
["com_shutdown"]=>
string(1) "0"
["com_statistics"]=>
string(1) "0"
["com_process_info"]=>
string(1) "0"
["com_connect"]=>
string(1) "0"
["com_process_kill"]=>
string(1) "0"
["com_debug"]=>
string(1) "0"
["com_ping"]=>
string(1) "0"
["com_time"]=>
string(1) "0"
["com_delayed_insert"]=>
string(1) "0"
["com_change_user"]=>
string(1) "0"
["com_binlog_dump"]=>
string(1) "0"
["com_table_dump"]=>
string(1) "0"
["com_connect_out"]=>
string(1) "0"
["com_register_slave"]=>
string(1) "0"
["com_stmt_prepare"]=>
string(1) "0"
["com_stmt_execute"]=>
string(1) "0"
["com_stmt_send_long_data"]=>
string(1) "0"
["com_stmt_close"]=>
string(1) "0"
["com_stmt_reset"]=>
string(1) "0"
["com_stmt_set_option"]=>
string(1) "0"
["com_stmt_fetch"]=>
string(1) "0"
["com_deamon"]=>
string(1) "0"
["bytes_received_real_data_normal"]=>
string(1) "0"
["bytes_received_real_data_ps"]=>
string(1) "0"
}
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_get_connection_stats() - Returns statistics about the client connection
MysqlndUhConnection::getThreadId
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::getThreadId — Returns the thread ID for the current connection
Opis
$connection
)Returns the thread ID for the current connection.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
Connection thread id.
Przykłady
Przykład #1 MysqlndUhConnection::getThreadId() example
<?php
class proxy extends MysqlndUhConnection {
public function getThreadId($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::getThreadId($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
var_dump($mysqli->thread_id);
?>
Powyższy przykład wyświetli:
proxy::getThreadId(array ( 0 => NULL, )) proxy::getThreadId returns 27646 int(27646)
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_thread_id() - Returns the thread ID for the current connection
- mysql_thread_id() - Zwraca id bieżącego wątku
MysqlndUhConnection::getWarningCount
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::getWarningCount — Returns the number of warnings from the last query for the given link
Opis
$connection
)Returns the number of warnings from the last query for the given link.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
Number of warnings.
Przykłady
Przykład #1 MysqlndUhConnection::getWarningCount() example
<?php
class proxy extends MysqlndUhConnection {
public function getWarningCount($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::getWarningCount($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
var_dump($mysqli->warning_count);
?>
Powyższy przykład wyświetli:
proxy::getWarningCount(array ( 0 => NULL, )) proxy::getWarningCount returns 0 int(0)
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_warning_count() - Returns the number of warnings from the last query for the given link
MysqlndUhConnection::init
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::init — Initialize mysqlnd connection
Opis
$connection
)Initialize mysqlnd connection. This is an mysqlnd internal call to initialize the connection object.
Informacja:
Failing to call the parent implementation may cause memory leaks or crash PHP. This is not considered a bug. Please, keep in mind that the mysqlnd library functions have never been designed to be exposed to the user space.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhConnection::init() example
<?php
class proxy extends MysqlndUhConnection {
public function init($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::init($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
?>
Powyższy przykład wyświetli:
proxy::init(array ( 0 => NULL, )) proxy::init returns true
MysqlndUhConnection::killConnection
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::killConnection — Asks the server to kill a MySQL thread
Opis
$connection
, int $pid
)Asks the server to kill a MySQL thread.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
-
pid -
Thread Id of the connection to be killed.
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhConnection::kill() example
<?php
class proxy extends MysqlndUhConnection {
public function killConnection($res, $pid) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::killConnection($res, $pid);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->kill($mysqli->thread_id);
?>
Powyższy przykład wyświetli:
proxy::killConnection(array ( 0 => NULL, 1 => 27650, )) proxy::killConnection returns true
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_kill() - Asks the server to kill a MySQL thread
MysqlndUhConnection::listFields
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::listFields — List MySQL table fields
Opis
$connection
, string $table
, string $achtung_wild
)List MySQL table fields.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
-
table -
The name of the table that's being queried.
-
pattern -
Name pattern.
Zwracane wartości
Przykłady
Przykład #1 MysqlndUhConnection::listFields() example
<?php
class proxy extends MysqlndUhConnection {
public function listFields($res, $table, $pattern) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::listFields($res, $table, $pattern);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysql = mysql_connect("localhost", "root", "");
mysql_select_db("test", $mysql);
mysql_query("DROP TABLE IF EXISTS test_a", $mysql);
mysql_query("CREATE TABLE test_a(id INT, col1 VARCHAR(255))", $mysql);
$res = mysql_list_fields("test", "test_a", $mysql);
printf("num_rows = %d\n", mysql_num_rows($res));
while ($row = mysql_fetch_assoc($res))
var_dump($row);
?>
Powyższy przykład wyświetli:
proxy::listFields(array ( 0 => NULL, 1 => 'test_a', 2 => '', )) proxy::listFields returns NULL num_rows = 0
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysql_list_fields() - Pobiera informacje o polach tabeli MySQL
MysqlndUhConnection::listMethod
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::listMethod — Wrapper for assorted list commands
Opis
$connection
, string $query
, string $achtung_wild
, string $par1
)Wrapper for assorted list commands.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
-
query -
SHOW command to be executed.
-
achtung_wild -
-
par1 -
Zwracane wartości
Zwracane wartości
TODO
Przykłady
Przykład #1 MysqlndUhConnection::listMethod() example
<?php
class proxy extends MysqlndUhConnection {
public function listMethod($res, $query, $pattern, $par1) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::listMethod($res, $query, $pattern, $par1);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysql = mysql_connect("localhost", "root", "");
$res = mysql_list_dbs($mysql);
printf("num_rows = %d\n", mysql_num_rows($res));
while ($row = mysql_fetch_assoc($res))
var_dump($row);
?>
Powyższy przykład wyświetli:
proxy::listMethod(array (
0 => NULL,
1 => 'SHOW DATABASES',
2 => '',
3 => '',
))
proxy::listMethod returns NULL
num_rows = 6
array(1) {
["Database"]=>
string(18) "information_schema"
}
array(1) {
["Database"]=>
string(5) "mysql"
}
array(1) {
["Database"]=>
string(8) "oxid_new"
}
array(1) {
["Database"]=>
string(7) "phptest"
}
array(1) {
["Database"]=>
string(7) "pushphp"
}
array(1) {
["Database"]=>
string(4) "test"
}
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysql_list_dbs() - Pobiera nazwy baz dostępnych na serwerze MySQL
MysqlndUhConnection::moreResults
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::moreResults — Check if there are any more query results from a multi query
Opis
$connection
)Check if there are any more query results from a multi query.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhConnection::moreResults() example
<?php
class proxy extends MysqlndUhConnection {
public function moreResults($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::moreResults($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->multi_query("SELECT 1 AS _one; SELECT 2 AS _two");
do {
$res = $mysqli->store_result();
var_dump($res->fetch_assoc());
printf("%s\n", str_repeat("-", 40));
} while ($mysqli->more_results() && $mysqli->next_result());
?>
Powyższy przykład wyświetli:
array(1) {
["_one"]=>
string(1) "1"
}
----------------------------------------
proxy::moreResults(array (
0 => NULL,
))
proxy::moreResults returns true
proxy::moreResults(array (
0 => NULL,
))
proxy::moreResults returns true
array(1) {
["_two"]=>
string(1) "2"
}
----------------------------------------
proxy::moreResults(array (
0 => NULL,
))
proxy::moreResults returns false
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_more_results() - Check if there are any more query results from a multi query
MysqlndUhConnection::nextResult
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::nextResult — Prepare next result from multi_query
Opis
$connection
)Prepare next result from multi_query.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhConnection::nextResult() example
<?php
class proxy extends MysqlndUhConnection {
public function nextResult($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::nextResult($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->multi_query("SELECT 1 AS _one; SELECT 2 AS _two");
do {
$res = $mysqli->store_result();
var_dump($res->fetch_assoc());
printf("%s\n", str_repeat("-", 40));
} while ($mysqli->more_results() && $mysqli->next_result());
?>
Powyższy przykład wyświetli:
array(1) {
["_one"]=>
string(1) "1"
}
----------------------------------------
proxy::nextResult(array (
0 => NULL,
))
proxy::nextResult returns true
array(1) {
["_two"]=>
string(1) "2"
}
----------------------------------------
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_next_result() - Prepare next result from multi_query
MysqlndUhConnection::ping
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::ping — Pings a server connection, or tries to reconnect if the connection has gone down
Opis
$connection
)Pings a server connection, or tries to reconnect if the connection has gone down.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhConnection::ping() example
<?php
class proxy extends MysqlndUhConnection {
public function ping($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::ping($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->ping();
?>
Powyższy przykład wyświetli:
proxy::ping(array ( 0 => NULL, )) proxy::ping returns true
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_ping() - Pings a server connection, or tries to reconnect if the connection has gone down
- mysql_ping() - Sprawdza połączenie z serwerem, lub nawiązuje połączenie, jeśli go nie było
MysqlndUhConnection::query
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::query — Performs a query on the database
Opis
$connection
, string $query
)Performs a query on the database (COM_QUERY).
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
-
query -
The query string.
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhConnection::query() example
<?php
class proxy extends MysqlndUhConnection {
public function query($res, $query) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$query = "SELECT 'How about query rewriting?'";
$ret = parent::query($res, $query);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$res = $mysqli->query("SELECT 'Welcome mysqlnd_uh!' FROM DUAL");
var_dump($res->fetch_assoc());
?>
Powyższy przykład wyświetli:
proxy::query(array (
0 => NULL,
1 => 'SELECT \'Welcome mysqlnd_uh!\' FROM DUAL',
))
proxy::query returns true
array(1) {
["How about query rewriting?"]=>
string(26) "How about query rewriting?"
}
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_query() - Performs a query on the database
- mysql_query() - Wysyła zapytanie do serwera MySQL
MysqlndUhConnection::queryReadResultsetHeader
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::queryReadResultsetHeader — Read a result set header
Opis
$connection
, mysqlnd_statement $mysqlnd_stmt
)Read a result set header.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
-
mysqlnd_stmt -
Mysqlnd statement handle. Do not modify! Set to
NULL, if function is not used in the context of a prepared statement.
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhConnection::queryReadResultsetHeader() example
<?php
class proxy extends MysqlndUhConnection {
public function queryReadResultsetHeader($res, $stmt) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::queryReadResultsetHeader($res, $stmt);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$res = $mysqli->query("SELECT 'Welcome mysqlnd_uh!' FROM DUAL");
var_dump($res->fetch_assoc());
?>
Powyższy przykład wyświetli:
proxy::queryReadResultsetHeader(array (
0 => NULL,
1 => NULL,
))
proxy::queryReadResultsetHeader returns true
array(1) {
["Welcome mysqlnd_uh!"]=>
string(19) "Welcome mysqlnd_uh!"
}
MysqlndUhConnection::reapQuery
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::reapQuery — Get result from async query
Opis
$connection
)Get result from async query.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhConnection::reapQuery() example
<?php
class proxy extends MysqlndUhConnection {
public function reapQuery($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::reapQuery($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$conn1 = new mysqli("localhost", "root", "", "test");
$conn2 = new mysqli("localhost", "root", "", "test");
$conn1->query("SELECT 1 as 'one', SLEEP(1) AS _sleep FROM DUAL", MYSQLI_ASYNC | MYSQLI_USE_RESULT);
$conn2->query("SELECT 1.1 as 'one dot one' FROM DUAL", MYSQLI_ASYNC | MYSQLI_USE_RESULT);
$links = array(
$conn1->thread_id => array('link' => $conn1, 'processed' => false),
$conn2->thread_id => array('link' => $conn2, 'processed' => false)
);
$saved_errors = array();
do {
$poll_links = $poll_errors = $poll_reject = array();
foreach ($links as $thread_id => $link) {
if (!$link['processed']) {
$poll_links[] = $link['link'];
$poll_errors[] = $link['link'];
$poll_reject[] = $link['link'];
}
}
if (0 == count($poll_links))
break;
if (0 == ($num_ready = mysqli_poll($poll_links, $poll_errors, $poll_reject, 0, 200000)))
continue;
if (!empty($poll_errors)) {
die(var_dump($poll_errors));
}
foreach ($poll_links as $link) {
$thread_id = mysqli_thread_id($link);
$links[$thread_id]['processed'] = true;
if (is_object($res = mysqli_reap_async_query($link))) {
// result set object
while ($row = mysqli_fetch_assoc($res)) {
// eat up all results
var_dump($row);
}
mysqli_free_result($res);
} else {
// either there is no result (no SELECT) or there is an error
if (mysqli_errno($link) > 0) {
$saved_errors[$thread_id] = mysqli_errno($link);
printf("'%s' caused %d\n", $links[$thread_id]['query'], mysqli_errno($link));
}
}
}
} while (true);
?>
Powyższy przykład wyświetli:
proxy::reapQuery(array (
0 => NULL,
))
proxy::reapQuery returns true
array(1) {
["one dot one"]=>
string(3) "1.1"
}
proxy::reapQuery(array (
0 => NULL,
))
proxy::reapQuery returns true
array(2) {
["one"]=>
string(1) "1"
["_sleep"]=>
string(1) "0"
}
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_real_async_query()
MysqlndUhConnection::refreshServer
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::refreshServer — Flush or reset tables and caches
Opis
$connection
, int $options
)Flush or reset tables and caches.
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
-
options -
What to refresh.
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhConnection::refreshServer() example
<?php
class proxy extends MysqlndUhConnection {
public function refreshServer($res, $option) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::refreshServer($res, $option);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
mysqli_refresh($mysqli, 1);
?>
Powyższy przykład wyświetli:
proxy::refreshServer(array ( 0 => NULL, 1 => 1, )) proxy::refreshServer returns false
MysqlndUhConnection::restartPSession
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::restartPSession — Restart a persistent mysqlnd connection
Opis
$connection
)Restart a persistent mysqlnd connection.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhConnection::restartPSession() example
<?php
class proxy extends MysqlndUhConnection {
public function ping($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::ping($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->ping();
?>
Powyższy przykład wyświetli:
proxy::restartPSession(array ( 0 => NULL, )) proxy::restartPSession returns true
MysqlndUhConnection::selectDb
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::selectDb — Selects the default database for database queries
Opis
$connection
, string $database
)Selects the default database for database queries.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
-
database -
The database name.
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhConnection::selectDb() example
<?php
class proxy extends MysqlndUhConnection {
public function selectDb($res, $database) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::selectDb($res, $database);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->select_db("mysql");
?>
Powyższy przykład wyświetli:
proxy::selectDb(array ( 0 => NULL, 1 => 'mysql', )) proxy::selectDb returns true
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_select_db() - Selects the default database for database queries
- mysql_select_db() - Wybiera bazę MySQL
MysqlndUhConnection::sendClose
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::sendClose — Sends a close command to MySQL
Opis
$connection
)Sends a close command to MySQL.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhConnection::sendClose() example
<?php
class proxy extends MysqlndUhConnection {
public function sendClose($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::sendClose($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->close();
?>
Powyższy przykład wyświetli:
proxy::sendClose(array ( 0 => NULL, )) proxy::sendClose returns true proxy::sendClose(array ( 0 => NULL, )) proxy::sendClose returns true
MysqlndUhConnection::sendQuery
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::sendQuery — Sends a query to MySQL
Opis
$connection
, string $query
)Sends a query to MySQL.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
-
query -
The query string.
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhConnection::sendQuery() example
<?php
class proxy extends MysqlndUhConnection {
public function sendQuery($res, $query) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::sendQuery($res, $query);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->query("SELECT 1");
?>
Powyższy przykład wyświetli:
proxy::sendQuery(array ( 0 => NULL, 1 => 'SELECT 1', )) proxy::sendQuery returns true
MysqlndUhConnection::serverDumpDebugInformation
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::serverDumpDebugInformation — Dump debugging information into the log for the MySQL server
Opis
$connection
)Dump debugging information into the log for the MySQL server.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhConnection::serverDumpDebugInformation() example
<?php
class proxy extends MysqlndUhConnection {
public function serverDumpDebugInformation($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::serverDumpDebugInformation($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->dump_debug_info();
?>
Powyższy przykład wyświetli:
proxy::serverDumpDebugInformation(array ( 0 => NULL, )) proxy::serverDumpDebugInformation returns true
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_dump_debug_info() - Dump debugging information into the log
MysqlndUhConnection::setAutocommit
(PECL mysqlnd-uh >= 1.0.1-alpha, PHP >= 5.4.0)
MysqlndUhConnection::setAutocommit — Turns on or off auto-commiting database modifications
Opis
$connection
, int $mode
)Turns on or off auto-commiting database modifications
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
-
mode -
Whether to turn on auto-commit or not.
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhConnection::setAutocommit() example
<?php
class proxy extends MysqlndUhConnection {
public function setAutocommit($res, $mode) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::setAutocommit($res, $mode);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->autocommit(false);
$mysqli->autocommit(true);
?>
Powyższy przykład wyświetli:
proxy::setAutocommit(array ( 0 => NULL, 1 => 0, )) proxy::setAutocommit returns true proxy::setAutocommit(array ( 0 => NULL, 1 => 1, )) proxy::setAutocommit returns true
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_autocommit() - Turns on or off auto-commiting database modifications
MysqlndUhConnection::setCharset
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::setCharset — Sets the default client character set
Opis
$connection
, string $charset
)Sets the default client character set.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
-
charset -
The charset to be set as default.
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhConnection::setCharset() example
<?php
class proxy extends MysqlndUhConnection {
public function setCharset($res, $charset) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::setCharset($res, $charset);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->set_charset("latin1");
?>
Powyższy przykład wyświetli:
proxy::setCharset(array ( 0 => NULL, 1 => 'latin1', )) proxy::setCharset returns true
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_set_charset() - Sets the default client character set
MysqlndUhConnection::setClientOption
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::setClientOption — Sets a client option
Opis
$connection
, int $option
, int $value
)Sets a client option.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
-
option -
The option to be set.
-
value -
Optional option value, if required.
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhConnection::setClientOption() example
<?php
function client_option_to_string($option) {
static $mapping = array(
MYSQLND_UH_MYSQLND_OPTION_OPT_CONNECT_TIMEOUT => "MYSQLND_UH_MYSQLND_OPTION_OPT_CONNECT_TIMEOUT",
MYSQLND_UH_MYSQLND_OPTION_OPT_COMPRESS => "MYSQLND_UH_MYSQLND_OPTION_OPT_COMPRESS",
MYSQLND_UH_MYSQLND_OPTION_OPT_NAMED_PIPE => "MYSQLND_UH_MYSQLND_OPTION_OPT_NAMED_PIPE",
MYSQLND_UH_MYSQLND_OPTION_INIT_COMMAND => "MYSQLND_UH_MYSQLND_OPTION_INIT_COMMAND",
MYSQLND_UH_MYSQLND_READ_DEFAULT_FILE => "MYSQLND_UH_MYSQLND_READ_DEFAULT_FILE",
MYSQLND_UH_MYSQLND_READ_DEFAULT_GROUP => "MYSQLND_UH_MYSQLND_READ_DEFAULT_GROUP",
MYSQLND_UH_MYSQLND_SET_CHARSET_DIR => "MYSQLND_UH_MYSQLND_SET_CHARSET_DIR",
MYSQLND_UH_MYSQLND_SET_CHARSET_NAME => "MYSQLND_UH_MYSQLND_SET_CHARSET_NAME",
MYSQLND_UH_MYSQLND_OPT_LOCAL_INFILE => "MYSQLND_UH_MYSQLND_OPT_LOCAL_INFILE",
MYSQLND_UH_MYSQLND_OPT_PROTOCOL => "MYSQLND_UH_MYSQLND_OPT_PROTOCOL",
MYSQLND_UH_MYSQLND_SHARED_MEMORY_BASE_NAME => "MYSQLND_UH_MYSQLND_SHARED_MEMORY_BASE_NAME",
MYSQLND_UH_MYSQLND_OPT_READ_TIMEOUT => "MYSQLND_UH_MYSQLND_OPT_READ_TIMEOUT",
MYSQLND_UH_MYSQLND_OPT_WRITE_TIMEOUT => "MYSQLND_UH_MYSQLND_OPT_WRITE_TIMEOUT",
MYSQLND_UH_MYSQLND_OPT_USE_RESULT => "MYSQLND_UH_MYSQLND_OPT_USE_RESULT",
MYSQLND_UH_MYSQLND_OPT_USE_REMOTE_CONNECTION => "MYSQLND_UH_MYSQLND_OPT_USE_REMOTE_CONNECTION",
MYSQLND_UH_MYSQLND_OPT_USE_EMBEDDED_CONNECTION => "MYSQLND_UH_MYSQLND_OPT_USE_EMBEDDED_CONNECTION",
MYSQLND_UH_MYSQLND_OPT_GUESS_CONNECTION => "MYSQLND_UH_MYSQLND_OPT_GUESS_CONNECTION",
MYSQLND_UH_MYSQLND_SET_CLIENT_IP => "MYSQLND_UH_MYSQLND_SET_CLIENT_IP",
MYSQLND_UH_MYSQLND_SECURE_AUTH => "MYSQLND_UH_MYSQLND_SECURE_AUTH",
MYSQLND_UH_MYSQLND_REPORT_DATA_TRUNCATION => "MYSQLND_UH_MYSQLND_REPORT_DATA_TRUNCATION",
MYSQLND_UH_MYSQLND_OPT_RECONNECT => "MYSQLND_UH_MYSQLND_OPT_RECONNECT",
MYSQLND_UH_MYSQLND_OPT_SSL_VERIFY_SERVER_CERT => "MYSQLND_UH_MYSQLND_OPT_SSL_VERIFY_SERVER_CERT",
MYSQLND_UH_MYSQLND_OPT_NET_CMD_BUFFER_SIZE => "MYSQLND_UH_MYSQLND_OPT_NET_CMD_BUFFER_SIZE",
MYSQLND_UH_MYSQLND_OPT_NET_READ_BUFFER_SIZE => "MYSQLND_UH_MYSQLND_OPT_NET_READ_BUFFER_SIZE",
MYSQLND_UH_MYSQLND_OPT_SSL_KEY => "MYSQLND_UH_MYSQLND_OPT_SSL_KEY",
MYSQLND_UH_MYSQLND_OPT_SSL_CERT => "MYSQLND_UH_MYSQLND_OPT_SSL_CERT",
MYSQLND_UH_MYSQLND_OPT_SSL_CA => "MYSQLND_UH_MYSQLND_OPT_SSL_CA",
MYSQLND_UH_MYSQLND_OPT_SSL_CAPATH => "MYSQLND_UH_MYSQLND_OPT_SSL_CAPATH",
MYSQLND_UH_MYSQLND_OPT_SSL_CIPHER => "MYSQLND_UH_MYSQLND_OPT_SSL_CIPHER",
MYSQLND_UH_MYSQLND_OPT_SSL_PASSPHRASE => "MYSQLND_UH_MYSQLND_OPT_SSL_PASSPHRASE",
MYSQLND_UH_SERVER_OPTION_PLUGIN_DIR => "MYSQLND_UH_SERVER_OPTION_PLUGIN_DIR",
MYSQLND_UH_SERVER_OPTION_DEFAULT_AUTH => "MYSQLND_UH_SERVER_OPTION_DEFAULT_AUTH",
MYSQLND_UH_SERVER_OPTION_SET_CLIENT_IP => "MYSQLND_UH_SERVER_OPTION_SET_CLIENT_IP"
);
if (version_compare(PHP_VERSION, '5.3.99-dev', '>')) {
$mapping[MYSQLND_UH_MYSQLND_OPT_MAX_ALLOWED_PACKET] = "MYSQLND_UH_MYSQLND_OPT_MAX_ALLOWED_PACKET";
$mapping[MYSQLND_UH_MYSQLND_OPT_AUTH_PROTOCOL] = "MYSQLND_UH_MYSQLND_OPT_AUTH_PROTOCOL";
}
if (defined("MYSQLND_UH_MYSQLND_OPT_INT_AND_FLOAT_NATIVE")) {
/* special mysqlnd build */
$mapping["MYSQLND_UH_MYSQLND_OPT_INT_AND_FLOAT_NATIVE"] = "MYSQLND_UH_MYSQLND_OPT_INT_AND_FLOAT_NATIVE";
}
return (isset($mapping[$option])) ? $mapping[$option] : 'unknown';
}
class proxy extends MysqlndUhConnection {
public function setClientOption($res, $option, $value) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
printf("Option '%s' set to %s\n", client_option_to_string($option), var_export($value, true));
$ret = parent::setClientOption($res, $option, $value);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
?>
Powyższy przykład wyświetli:
proxy::setClientOption(array ( 0 => NULL, 1 => 210, 2 => 3221225472, )) Option 'MYSQLND_UH_MYSQLND_OPT_MAX_ALLOWED_PACKET' set to 3221225472 proxy::setClientOption returns true proxy::setClientOption(array ( 0 => NULL, 1 => 211, 2 => 'mysql_native_password', )) Option 'MYSQLND_UH_MYSQLND_OPT_AUTH_PROTOCOL' set to 'mysql_native_password' proxy::setClientOption returns true proxy::setClientOption(array ( 0 => NULL, 1 => 8, 2 => 1, )) Option 'MYSQLND_UH_MYSQLND_OPT_LOCAL_INFILE' set to 1 proxy::setClientOption returns true
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_real_connect() - Opens a connection to a mysql server
- mysqli_options() - Set options
MysqlndUhConnection::setServerOption
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::setServerOption — Sets a server option
Opis
$connection
, int $option
)Sets a server option.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
-
option -
The option to be set.
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhConnection::setServerOption() example
<?php
function server_option_to_string($option) {
$ret = 'unknown';
switch ($option) {
case MYSQLND_UH_SERVER_OPTION_MULTI_STATEMENTS_ON:
$ret = 'MYSQLND_UH_SERVER_OPTION_MULTI_STATEMENTS_ON';
break;
case MYSQLND_UH_SERVER_OPTION_MULTI_STATEMENTS_OFF:
$ret = 'MYSQLND_UH_SERVER_OPTION_MULTI_STATEMENTS_ON';
break;
}
return $ret;
}
class proxy extends MysqlndUhConnection {
public function setServerOption($res, $option) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
printf("Option '%s' set\n", server_option_to_string($option));
$ret = parent::setServerOption($res, $option);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->multi_query("SELECT 1; SELECT 2");
?>
Powyższy przykład wyświetli:
proxy::setServerOption(array ( 0 => NULL, 1 => 0, )) Option 'MYSQLND_UH_SERVER_OPTION_MULTI_STATEMENTS_ON' set proxy::setServerOption returns true
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_real_connect() - Opens a connection to a mysql server
- mysqli_options() - Set options
- mysqli_multi_query() - Performs a query on the database
MysqlndUhConnection::shutdownServer
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::shutdownServer — The shutdownServer purpose
Opis
$MYSQLND_UH_RES_MYSQLND_NAME
, string $"level"
)
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
-
MYSQLND_UH_RES_MYSQLND_NAME -
-
"level" -
Zwracane wartości
MysqlndUhConnection::simpleCommand
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::simpleCommand — Sends a basic COM_* command
Opis
$connection
, int $command
, string $arg
, int $ok_packet
, bool $silent
, bool $ignore_upsert_status
)Sends a basic COM_* command to MySQL.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
-
command -
The COM command to be send.
-
arg -
Optional COM command arguments.
-
ok_packet -
The OK packet type.
-
silent -
Whether mysqlnd may emit errors.
-
ignore_upsert_status -
Whether to ignore UPDATE/INSERT status.
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhConnection::simpleCommand() example
<?php
function server_cmd_2_string($command) {
$mapping = array(
MYSQLND_UH_MYSQLND_COM_SLEEP => "MYSQLND_UH_MYSQLND_COM_SLEEP",
MYSQLND_UH_MYSQLND_COM_QUIT => "MYSQLND_UH_MYSQLND_COM_QUIT",
MYSQLND_UH_MYSQLND_COM_INIT_DB => "MYSQLND_UH_MYSQLND_COM_INIT_DB",
MYSQLND_UH_MYSQLND_COM_QUERY => "MYSQLND_UH_MYSQLND_COM_QUERY",
MYSQLND_UH_MYSQLND_COM_FIELD_LIST => "MYSQLND_UH_MYSQLND_COM_FIELD_LIST",
MYSQLND_UH_MYSQLND_COM_CREATE_DB => "MYSQLND_UH_MYSQLND_COM_CREATE_DB",
MYSQLND_UH_MYSQLND_COM_DROP_DB => "MYSQLND_UH_MYSQLND_COM_DROP_DB",
MYSQLND_UH_MYSQLND_COM_REFRESH => "MYSQLND_UH_MYSQLND_COM_REFRESH",
MYSQLND_UH_MYSQLND_COM_SHUTDOWN => "MYSQLND_UH_MYSQLND_COM_SHUTDOWN",
MYSQLND_UH_MYSQLND_COM_STATISTICS => "MYSQLND_UH_MYSQLND_COM_STATISTICS",
MYSQLND_UH_MYSQLND_COM_PROCESS_INFO => "MYSQLND_UH_MYSQLND_COM_PROCESS_INFO",
MYSQLND_UH_MYSQLND_COM_CONNECT => "MYSQLND_UH_MYSQLND_COM_CONNECT",
MYSQLND_UH_MYSQLND_COM_PROCESS_KILL => "MYSQLND_UH_MYSQLND_COM_PROCESS_KILL",
MYSQLND_UH_MYSQLND_COM_DEBUG => "MYSQLND_UH_MYSQLND_COM_DEBUG",
MYSQLND_UH_MYSQLND_COM_PING => "MYSQLND_UH_MYSQLND_COM_PING",
MYSQLND_UH_MYSQLND_COM_TIME => "MYSQLND_UH_MYSQLND_COM_TIME",
MYSQLND_UH_MYSQLND_COM_DELAYED_INSERT => "MYSQLND_UH_MYSQLND_COM_DELAYED_INSERT",
MYSQLND_UH_MYSQLND_COM_CHANGE_USER => "MYSQLND_UH_MYSQLND_COM_CHANGE_USER",
MYSQLND_UH_MYSQLND_COM_BINLOG_DUMP => "MYSQLND_UH_MYSQLND_COM_BINLOG_DUMP",
MYSQLND_UH_MYSQLND_COM_TABLE_DUMP => "MYSQLND_UH_MYSQLND_COM_TABLE_DUMP",
MYSQLND_UH_MYSQLND_COM_CONNECT_OUT => "MYSQLND_UH_MYSQLND_COM_CONNECT_OUT",
MYSQLND_UH_MYSQLND_COM_REGISTER_SLAVED => "MYSQLND_UH_MYSQLND_COM_REGISTER_SLAVED",
MYSQLND_UH_MYSQLND_COM_STMT_PREPARE => "MYSQLND_UH_MYSQLND_COM_STMT_PREPARE",
MYSQLND_UH_MYSQLND_COM_STMT_EXECUTE => "MYSQLND_UH_MYSQLND_COM_STMT_EXECUTE",
MYSQLND_UH_MYSQLND_COM_STMT_SEND_LONG_DATA => "MYSQLND_UH_MYSQLND_COM_STMT_SEND_LONG_DATA",
MYSQLND_UH_MYSQLND_COM_STMT_CLOSE => "MYSQLND_UH_MYSQLND_COM_STMT_CLOSE",
MYSQLND_UH_MYSQLND_COM_STMT_RESET => "MYSQLND_UH_MYSQLND_COM_STMT_RESET",
MYSQLND_UH_MYSQLND_COM_SET_OPTION => "MYSQLND_UH_MYSQLND_COM_SET_OPTION",
MYSQLND_UH_MYSQLND_COM_STMT_FETCH => "MYSQLND_UH_MYSQLND_COM_STMT_FETCH",
MYSQLND_UH_MYSQLND_COM_DAEMON => "MYSQLND_UH_MYSQLND_COM_DAEMON",
MYSQLND_UH_MYSQLND_COM_END => "MYSQLND_UH_MYSQLND_COM_END",
);
return (isset($mapping[$command])) ? $mapping[$command] : 'unknown';
}
function ok_packet_2_string($ok_packet) {
$mapping = array(
MYSQLND_UH_MYSQLND_PROT_GREET_PACKET => "MYSQLND_UH_MYSQLND_PROT_GREET_PACKET",
MYSQLND_UH_MYSQLND_PROT_AUTH_PACKET => "MYSQLND_UH_MYSQLND_PROT_AUTH_PACKET",
MYSQLND_UH_MYSQLND_PROT_OK_PACKET => "MYSQLND_UH_MYSQLND_PROT_OK_PACKET",
MYSQLND_UH_MYSQLND_PROT_EOF_PACKET => "MYSQLND_UH_MYSQLND_PROT_EOF_PACKET",
MYSQLND_UH_MYSQLND_PROT_CMD_PACKET => "MYSQLND_UH_MYSQLND_PROT_CMD_PACKET",
MYSQLND_UH_MYSQLND_PROT_RSET_HEADER_PACKET => "MYSQLND_UH_MYSQLND_PROT_RSET_HEADER_PACKET",
MYSQLND_UH_MYSQLND_PROT_RSET_FLD_PACKET => "MYSQLND_UH_MYSQLND_PROT_RSET_FLD_PACKET",
MYSQLND_UH_MYSQLND_PROT_ROW_PACKET => "MYSQLND_UH_MYSQLND_PROT_ROW_PACKET",
MYSQLND_UH_MYSQLND_PROT_STATS_PACKET => "MYSQLND_UH_MYSQLND_PROT_STATS_PACKET",
MYSQLND_UH_MYSQLND_PREPARE_RESP_PACKET => "MYSQLND_UH_MYSQLND_PREPARE_RESP_PACKET",
MYSQLND_UH_MYSQLND_CHG_USER_RESP_PACKET => "MYSQLND_UH_MYSQLND_CHG_USER_RESP_PACKET",
MYSQLND_UH_MYSQLND_PROT_LAST => "MYSQLND_UH_MYSQLND_PROT_LAST",
);
return (isset($mapping[$ok_packet])) ? $mapping[$ok_packet] : 'unknown';
}
class proxy extends MysqlndUhConnection {
public function simpleCommand($conn, $command, $arg, $ok_packet, $silent, $ignore_upsert_status) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
printf("Command '%s'\n", server_cmd_2_string($command));
printf("OK packet '%s'\n", ok_packet_2_string($ok_packet));
$ret = parent::simpleCommand($conn, $command, $arg, $ok_packet, $silent, $ignore_upsert_status);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->query("SELECT 1");
?>
Powyższy przykład wyświetli:
proxy::simpleCommand(array ( 0 => NULL, 1 => 3, 2 => 'SELECT 1', 3 => 13, 4 => false, 5 => false, )) Command 'MYSQLND_UH_MYSQLND_COM_QUERY' OK packet 'MYSQLND_UH_MYSQLND_PROT_LAST' proxy::simpleCommand returns true :)proxy::simpleCommand(array ( 0 => NULL, 1 => 1, 2 => '', 3 => 13, 4 => true, 5 => true, )) Command 'MYSQLND_UH_MYSQLND_COM_QUIT' OK packet 'MYSQLND_UH_MYSQLND_PROT_LAST' proxy::simpleCommand returns true
MysqlndUhConnection::simpleCommandHandleResponse
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::simpleCommandHandleResponse — Process a response for a basic COM_* command send to the client
Opis
$connection
, int $ok_packet
, bool $silent
, int $command
, bool $ignore_upsert_status
)Process a response for a basic COM_* command send to the client.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
-
ok_packet -
The OK packet type.
-
silent -
Whether mysqlnd may emit errors.
-
command -
The COM command to process results from.
-
ignore_upsert_status -
Whether to ignore UPDATE/INSERT status.
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhConnection::simpleCommandHandleResponse() example
<?php
function server_cmd_2_string($command) {
$mapping = array(
MYSQLND_UH_MYSQLND_COM_SLEEP => "MYSQLND_UH_MYSQLND_COM_SLEEP",
MYSQLND_UH_MYSQLND_COM_QUIT => "MYSQLND_UH_MYSQLND_COM_QUIT",
MYSQLND_UH_MYSQLND_COM_INIT_DB => "MYSQLND_UH_MYSQLND_COM_INIT_DB",
MYSQLND_UH_MYSQLND_COM_QUERY => "MYSQLND_UH_MYSQLND_COM_QUERY",
MYSQLND_UH_MYSQLND_COM_FIELD_LIST => "MYSQLND_UH_MYSQLND_COM_FIELD_LIST",
MYSQLND_UH_MYSQLND_COM_CREATE_DB => "MYSQLND_UH_MYSQLND_COM_CREATE_DB",
MYSQLND_UH_MYSQLND_COM_DROP_DB => "MYSQLND_UH_MYSQLND_COM_DROP_DB",
MYSQLND_UH_MYSQLND_COM_REFRESH => "MYSQLND_UH_MYSQLND_COM_REFRESH",
MYSQLND_UH_MYSQLND_COM_SHUTDOWN => "MYSQLND_UH_MYSQLND_COM_SHUTDOWN",
MYSQLND_UH_MYSQLND_COM_STATISTICS => "MYSQLND_UH_MYSQLND_COM_STATISTICS",
MYSQLND_UH_MYSQLND_COM_PROCESS_INFO => "MYSQLND_UH_MYSQLND_COM_PROCESS_INFO",
MYSQLND_UH_MYSQLND_COM_CONNECT => "MYSQLND_UH_MYSQLND_COM_CONNECT",
MYSQLND_UH_MYSQLND_COM_PROCESS_KILL => "MYSQLND_UH_MYSQLND_COM_PROCESS_KILL",
MYSQLND_UH_MYSQLND_COM_DEBUG => "MYSQLND_UH_MYSQLND_COM_DEBUG",
MYSQLND_UH_MYSQLND_COM_PING => "MYSQLND_UH_MYSQLND_COM_PING",
MYSQLND_UH_MYSQLND_COM_TIME => "MYSQLND_UH_MYSQLND_COM_TIME",
MYSQLND_UH_MYSQLND_COM_DELAYED_INSERT => "MYSQLND_UH_MYSQLND_COM_DELAYED_INSERT",
MYSQLND_UH_MYSQLND_COM_CHANGE_USER => "MYSQLND_UH_MYSQLND_COM_CHANGE_USER",
MYSQLND_UH_MYSQLND_COM_BINLOG_DUMP => "MYSQLND_UH_MYSQLND_COM_BINLOG_DUMP",
MYSQLND_UH_MYSQLND_COM_TABLE_DUMP => "MYSQLND_UH_MYSQLND_COM_TABLE_DUMP",
MYSQLND_UH_MYSQLND_COM_CONNECT_OUT => "MYSQLND_UH_MYSQLND_COM_CONNECT_OUT",
MYSQLND_UH_MYSQLND_COM_REGISTER_SLAVED => "MYSQLND_UH_MYSQLND_COM_REGISTER_SLAVED",
MYSQLND_UH_MYSQLND_COM_STMT_PREPARE => "MYSQLND_UH_MYSQLND_COM_STMT_PREPARE",
MYSQLND_UH_MYSQLND_COM_STMT_EXECUTE => "MYSQLND_UH_MYSQLND_COM_STMT_EXECUTE",
MYSQLND_UH_MYSQLND_COM_STMT_SEND_LONG_DATA => "MYSQLND_UH_MYSQLND_COM_STMT_SEND_LONG_DATA",
MYSQLND_UH_MYSQLND_COM_STMT_CLOSE => "MYSQLND_UH_MYSQLND_COM_STMT_CLOSE",
MYSQLND_UH_MYSQLND_COM_STMT_RESET => "MYSQLND_UH_MYSQLND_COM_STMT_RESET",
MYSQLND_UH_MYSQLND_COM_SET_OPTION => "MYSQLND_UH_MYSQLND_COM_SET_OPTION",
MYSQLND_UH_MYSQLND_COM_STMT_FETCH => "MYSQLND_UH_MYSQLND_COM_STMT_FETCH",
MYSQLND_UH_MYSQLND_COM_DAEMON => "MYSQLND_UH_MYSQLND_COM_DAEMON",
MYSQLND_UH_MYSQLND_COM_END => "MYSQLND_UH_MYSQLND_COM_END",
);
return (isset($mapping[$command])) ? $mapping[$command] : 'unknown';
}
function ok_packet_2_string($ok_packet) {
$mapping = array(
MYSQLND_UH_MYSQLND_PROT_GREET_PACKET => "MYSQLND_UH_MYSQLND_PROT_GREET_PACKET",
MYSQLND_UH_MYSQLND_PROT_AUTH_PACKET => "MYSQLND_UH_MYSQLND_PROT_AUTH_PACKET",
MYSQLND_UH_MYSQLND_PROT_OK_PACKET => "MYSQLND_UH_MYSQLND_PROT_OK_PACKET",
MYSQLND_UH_MYSQLND_PROT_EOF_PACKET => "MYSQLND_UH_MYSQLND_PROT_EOF_PACKET",
MYSQLND_UH_MYSQLND_PROT_CMD_PACKET => "MYSQLND_UH_MYSQLND_PROT_CMD_PACKET",
MYSQLND_UH_MYSQLND_PROT_RSET_HEADER_PACKET => "MYSQLND_UH_MYSQLND_PROT_RSET_HEADER_PACKET",
MYSQLND_UH_MYSQLND_PROT_RSET_FLD_PACKET => "MYSQLND_UH_MYSQLND_PROT_RSET_FLD_PACKET",
MYSQLND_UH_MYSQLND_PROT_ROW_PACKET => "MYSQLND_UH_MYSQLND_PROT_ROW_PACKET",
MYSQLND_UH_MYSQLND_PROT_STATS_PACKET => "MYSQLND_UH_MYSQLND_PROT_STATS_PACKET",
MYSQLND_UH_MYSQLND_PREPARE_RESP_PACKET => "MYSQLND_UH_MYSQLND_PREPARE_RESP_PACKET",
MYSQLND_UH_MYSQLND_CHG_USER_RESP_PACKET => "MYSQLND_UH_MYSQLND_CHG_USER_RESP_PACKET",
MYSQLND_UH_MYSQLND_PROT_LAST => "MYSQLND_UH_MYSQLND_PROT_LAST",
);
return (isset($mapping[$ok_packet])) ? $mapping[$ok_packet] : 'unknown';
}
class proxy extends MysqlndUhConnection {
public function simpleCommandHandleResponse($conn, $ok_packet, $silent, $command, $ignore_upsert_status) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
printf("Command '%s'\n", server_cmd_2_string($command));
printf("OK packet '%s'\n", ok_packet_2_string($ok_packet));
$ret = parent::simpleCommandHandleResponse($conn, $ok_packet, $silent, $command, $ignore_upsert_status);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysql = mysql_connect("localhost", "root", "");
mysql_query("SELECT 1 FROM DUAL", $mysql);
?>
Powyższy przykład wyświetli:
proxy::simpleCommandHandleResponse(array ( 0 => NULL, 1 => 5, 2 => false, 3 => 27, 4 => true, )) Command 'MYSQLND_UH_MYSQLND_COM_SET_OPTION' OK packet 'MYSQLND_UH_MYSQLND_PROT_EOF_PACKET' proxy::simpleCommandHandleResponse returns true
MysqlndUhConnection::sslSet
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::sslSet — Used for establishing secure connections using SSL
Opis
$connection
, string $key
, string $cert
, string $ca
, string $capath
, string $cipher
)Used for establishing secure connections using SSL.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
-
key -
The path name to the key file.
-
cert -
The path name to the certificate file.
-
ca -
The path name to the certificate authority file.
-
capath -
The pathname to a directory that contains trusted SSL CA certificates in PEM format.
-
cipher -
A list of allowable ciphers to use for SSL encryption.
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhConnection::sslSet() example
<?php
class proxy extends MysqlndUhConnection {
public function sslSet($conn, $key, $cert, $ca, $capth, $cipher) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::sslSet($conn, $key, $cert, $ca, $capth, $cipher);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->ssl_set("key", "cert", "ca", "capath", "cipher");
?>
Powyższy przykład wyświetli:
proxy::sslSet(array ( 0 => NULL, 1 => 'key', 2 => 'cert', 3 => 'ca', 4 => 'capath', 5 => 'cipher', )) proxy::sslSet returns true
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_ssl_set() - Used for establishing secure connections using SSL
MysqlndUhConnection::stmtInit
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::stmtInit — Initializes a statement and returns a resource for use with mysqli_statement::prepare
Opis
$connection
)Initializes a statement and returns a resource for use with mysqli_statement::prepare.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
Resource of type Mysqlnd Prepared Statement (internal only - you must not modify it!). The documentation may also refer to such resources using the alias name mysqlnd_prepared_statement.
Przykłady
Przykład #1 MysqlndUhConnection::stmtInit() example
<?php
class proxy extends MysqlndUhConnection {
public function stmtInit($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
var_dump($res);
$ret = parent::stmtInit($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
var_dump($ret);
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$stmt = $mysqli->prepare("SELECT 1 AS _one FROM DUAL");
$stmt->execute();
$one = NULL;
$stmt->bind_result($one);
$stmt->fetch();
var_dump($one);
?>
Powyższy przykład wyświetli:
proxy::stmtInit(array ( 0 => NULL, )) resource(19) of type (Mysqlnd Connection) proxy::stmtInit returns NULL resource(246) of type (Mysqlnd Prepared Statement (internal only - you must not modify it!)) int(1)
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_stmt_init() - Initializes a statement and returns an object for use with mysqli_stmt_prepare
MysqlndUhConnection::storeResult
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::storeResult — Transfers a result set from the last query
Opis
$connection
)Transfers a result set from the last query.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
Resource of type Mysqlnd Resultset (internal only - you must not modify it!). The documentation may also refer to such resources using the alias name mysqlnd_resultset.
Przykłady
Przykład #1 MysqlndUhConnection::storeResult() example
<?php
class proxy extends MysqlndUhConnection {
public function storeResult($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::storeResult($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
var_dump($ret);
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$res = $mysqli->query("SELECT 'Also called buffered result' AS _msg FROM DUAL");
var_dump($res->fetch_assoc());
$mysqli->real_query("SELECT 'Good morning!' AS _msg FROM DUAL");
$res = $mysqli->store_result();
var_dump($res->fetch_assoc());
?>
Powyższy przykład wyświetli:
proxy::storeResult(array (
0 => NULL,
))
proxy::storeResult returns NULL
resource(475) of type (Mysqlnd Resultset (internal only - you must not modify it!))
array(1) {
["_msg"]=>
string(27) "Also called buffered result"
}
proxy::storeResult(array (
0 => NULL,
))
proxy::storeResult returns NULL
resource(730) of type (Mysqlnd Resultset (internal only - you must not modify it!))
array(1) {
["_msg"]=>
string(13) "Good morning!"
}
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_store_result() - Transfers a result set from the last query
- mysqli_real_query() - Execute an SQL query
MysqlndUhConnection::txCommit
(PECL mysqlnd-uh >= 1.0.1-alpha, PHP >= 5.4.0)
MysqlndUhConnection::txCommit — Commits the current transaction
Opis
$connection
)Commits the current transaction.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhConnection::txCommit() example
<?php
class proxy extends MysqlndUhConnection {
public function txCommit($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::txCommit($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->commit();
?>
Powyższy przykład wyświetli:
proxy::txCommit(array ( 0 => NULL, )) proxy::txCommit returns true
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_commit() - Commits the current transaction
MysqlndUhConnection::txRollback
(PECL mysqlnd-uh >= 1.0.1-alpha, PHP >= 5.4.0)
MysqlndUhConnection::txRollback — Rolls back current transaction
Opis
$connection
)Rolls back current transaction.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhConnection::txRollback() example
<?php
class proxy extends MysqlndUhConnection {
public function txRollback($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::txRollback($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->rollback();
?>
Powyższy przykład wyświetli:
proxy::txRollback(array ( 0 => NULL, )) proxy::txRollback returns true
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_commit() - Commits the current transaction
MysqlndUhConnection::useResult
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhConnection::useResult — Initiate a result set retrieval
Opis
$connection
)Initiate a result set retrieval.
Parametry
-
connection -
Mysqlnd connection handle. Do not modify!
Zwracane wartości
Resource of type Mysqlnd Resultset (internal only - you must not modify it!). The documentation may also refer to such resources using the alias name mysqlnd_resultset.
Przykłady
Przykład #1 MysqlndUhConnection::useResult() example
<?php
class proxy extends MysqlndUhConnection {
public function useResult($res) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::useResult($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
var_dump($ret);
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->real_query("SELECT 'Good morning!' AS _msg FROM DUAL");
$res = $mysqli->use_result();
var_dump($res->fetch_assoc());
?>
Powyższy przykład wyświetli:
proxy::useResult(array (
0 => NULL,
))
proxy::useResult returns NULL
resource(425) of type (Mysqlnd Resultset (internal only - you must not modify it!))
array(1) {
["_msg"]=>
string(13) "Good morning!"
}
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqli_use_result() - Initiate a result set retrieval
- mysqli_real_query() - Execute an SQL query
Spis treści
- MysqlndUhConnection::changeUser — Changes the user of the specified mysqlnd database connection
- MysqlndUhConnection::charsetName — Returns the default character set for the database connection
- MysqlndUhConnection::close — Closes a previously opened database connection
- MysqlndUhConnection::connect — Open a new connection to the MySQL server
- MysqlndUhConnection::__construct — The __construct purpose
- MysqlndUhConnection::endPSession — End a persistent connection
- MysqlndUhConnection::escapeString — Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection
- MysqlndUhConnection::getAffectedRows — Gets the number of affected rows in a previous MySQL operation
- MysqlndUhConnection::getErrorNumber — Returns the error code for the most recent function call
- MysqlndUhConnection::getErrorString — Returns a string description of the last error
- MysqlndUhConnection::getFieldCount — Returns the number of columns for the most recent query
- MysqlndUhConnection::getHostInformation — Returns a string representing the type of connection used
- MysqlndUhConnection::getLastInsertId — Returns the auto generated id used in the last query.
- MysqlndUhConnection::getLastMessage — Retrieves information about the most recently executed query
- MysqlndUhConnection::getProtocolInformation — Returns the version of the MySQL protocol used
- MysqlndUhConnection::getServerInformation — Returns the version of the MySQL server
- MysqlndUhConnection::getServerStatistics — Gets the current system status
- MysqlndUhConnection::getServerVersion — Returns the version of the MySQL server as an integer
- MysqlndUhConnection::getSqlstate — Returns the SQLSTATE error from previous MySQL operation
- MysqlndUhConnection::getStatistics — Returns statistics about the client connection.
- MysqlndUhConnection::getThreadId — Returns the thread ID for the current connection
- MysqlndUhConnection::getWarningCount — Returns the number of warnings from the last query for the given link
- MysqlndUhConnection::init — Initialize mysqlnd connection
- MysqlndUhConnection::killConnection — Asks the server to kill a MySQL thread
- MysqlndUhConnection::listFields — List MySQL table fields
- MysqlndUhConnection::listMethod — Wrapper for assorted list commands
- MysqlndUhConnection::moreResults — Check if there are any more query results from a multi query
- MysqlndUhConnection::nextResult — Prepare next result from multi_query
- MysqlndUhConnection::ping — Pings a server connection, or tries to reconnect if the connection has gone down
- MysqlndUhConnection::query — Performs a query on the database
- MysqlndUhConnection::queryReadResultsetHeader — Read a result set header
- MysqlndUhConnection::reapQuery — Get result from async query
- MysqlndUhConnection::refreshServer — Flush or reset tables and caches
- MysqlndUhConnection::restartPSession — Restart a persistent mysqlnd connection
- MysqlndUhConnection::selectDb — Selects the default database for database queries
- MysqlndUhConnection::sendClose — Sends a close command to MySQL
- MysqlndUhConnection::sendQuery — Sends a query to MySQL
- MysqlndUhConnection::serverDumpDebugInformation — Dump debugging information into the log for the MySQL server
- MysqlndUhConnection::setAutocommit — Turns on or off auto-commiting database modifications
- MysqlndUhConnection::setCharset — Sets the default client character set
- MysqlndUhConnection::setClientOption — Sets a client option
- MysqlndUhConnection::setServerOption — Sets a server option
- MysqlndUhConnection::shutdownServer — The shutdownServer purpose
- MysqlndUhConnection::simpleCommand — Sends a basic COM_* command
- MysqlndUhConnection::simpleCommandHandleResponse — Process a response for a basic COM_* command send to the client
- MysqlndUhConnection::sslSet — Used for establishing secure connections using SSL
- MysqlndUhConnection::stmtInit — Initializes a statement and returns a resource for use with mysqli_statement::prepare
- MysqlndUhConnection::storeResult — Transfers a result set from the last query
- MysqlndUhConnection::txCommit — Commits the current transaction
- MysqlndUhConnection::txRollback — Rolls back current transaction
- MysqlndUhConnection::useResult — Initiate a result set retrieval
The MysqlndUhPreparedStatement class
(PECL mysqlnd-uh >= 1.0.0-alpha)
Wstęp
Krótki opis klasy
MysqlndUhPreparedStatement::__construct
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhPreparedStatement::__construct — The __construct purpose
Opis
Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
MysqlndUhPreparedStatement::execute
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhPreparedStatement::execute — Executes a prepared Query
Opis
$statement
)Executes a prepared Query.
Parametry
-
statement -
Mysqlnd prepared statement handle. Do not modify! Resource of type Mysqlnd Prepared Statement (internal only - you must not modify it!).
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhPreparedStatement::execute() example
<?php
class stmt_proxy extends MysqlndUhPreparedStatement {
public function execute($res) {
printf("%s(", __METHOD__);
var_dump($res);
printf(")\n");
$ret = parent::execute($res);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
var_dump($ret);
return $ret;
}
}
mysqlnd_uh_set_statement_proxy(new stmt_proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$stmt = $mysqli->prepare("SELECT 'Labskaus' AS _msg FROM DUAL");
$stmt->execute();
$msg = NULL;
$stmt->bind_result($msg);
$stmt->fetch();
var_dump($msg);
?>
Powyższy przykład wyświetli:
stmt_proxy::execute(resource(256) of type (Mysqlnd Prepared Statement (internal only - you must not modify it!)) ) stmt_proxy::execute returns true bool(true) string(8) "Labskaus"
Zobacz też:
- mysqlnd_uh_set_statement_proxy() - Installs a proxy for mysqlnd statements
- mysqli_stmt_execute() - Executes a prepared Query
MysqlndUhPreparedStatement::prepare
(PECL mysqlnd-uh >= 1.0.0-alpha)
MysqlndUhPreparedStatement::prepare — Prepare an SQL statement for execution
Opis
$statement
, string $query
)Prepare an SQL statement for execution.
Parametry
-
statement -
Mysqlnd prepared statement handle. Do not modify! Resource of type Mysqlnd Prepared Statement (internal only - you must not modify it!).
-
query -
The query to be prepared.
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 MysqlndUhPreparedStatement::prepare() example
<?php
class stmt_proxy extends MysqlndUhPreparedStatement {
public function prepare($res, $query) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$query = "SELECT 'No more you-know-what-I-mean for lunch, please' AS _msg FROM DUAL";
$ret = parent::prepare($res, $query);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
var_dump($ret);
return $ret;
}
}
mysqlnd_uh_set_statement_proxy(new stmt_proxy());
$mysqli = new mysqli("localhost", "root", "", "test");
$stmt = $mysqli->prepare("SELECT 'Labskaus' AS _msg FROM DUAL");
$stmt->execute();
$msg = NULL;
$stmt->bind_result($msg);
$stmt->fetch();
var_dump($msg);
?>
Powyższy przykład wyświetli:
stmt_proxy::prepare(array ( 0 => NULL, 1 => 'SELECT \'Labskaus\' AS _msg FROM DUAL', )) stmt_proxy::prepare returns true bool(true) string(46) "No more you-know-what-I-mean for lunch, please"
Zobacz też:
- mysqlnd_uh_set_statement_proxy() - Installs a proxy for mysqlnd statements
- mysqli_stmt_prepare() - Prepare an SQL statement for execution
- mysqli_prepare() - Prepare an SQL statement for execution
Spis treści
- MysqlndUhPreparedStatement::__construct — The __construct purpose
- MysqlndUhPreparedStatement::execute — Executes a prepared Query
- MysqlndUhPreparedStatement::prepare — Prepare an SQL statement for execution
Mysqlnd_uh Funkcje
mysqlnd_uh_convert_to_mysqlnd
(PECL mysqlnd-uh >= 1.0.0-alpha)
mysqlnd_uh_convert_to_mysqlnd — Converts a MySQL connection handle into a mysqlnd connection handle
Opis
Converts a MySQL connection handle into a mysqlnd connection handle. After conversion you can execute mysqlnd library calls on the connection handle. This can be used to access mysqlnd functionality not made available through user space API calls.
The function can be disabled with
mysqlnd_uh.enable.
If mysqlnd_uh.enable
is set to FALSE the function will not install the proxy and
always return TRUE. Additionally, an error of the
type E_WARNING may be emitted. The error message may
read like PHP Warning: mysqlnd_uh_convert_to_mysqlnd(): (Mysqlnd User Handler)
The plugin has been disabled by setting the configuration parameter mysqlnd_uh.enable = false.
You are not allowed to call this function [...].
Parametry
-
MySQL connection handle -
A MySQL connection handle of type mysql, mysqli or PDO_MySQL.
Informacja:
The MySQL connection handle can be of no other type but mysqli if using PHP < 5.4.0.
Zwracane wartości
A mysqlnd connection handle.
Przykłady
Przykład #1 mysqlnd_uh_convert_to_mysqlnd() example
<?php
/* PDO user API gives no access to connection thread id */
$mysql_connection = new PDO("mysql:host=localhost;dbname=test", "root", "");
/* Convert PDO MySQL handle to mysqlnd handle */
$mysqlnd = mysqlnd_uh_convert_to_mysqlnd($mysql_connection);
/* Create Proxy to call mysqlnd connection class methods */
$obj = new MySQLndUHConnection();
/* Call mysqlnd_conn::get_thread_id */
var_dump($obj->getThreadId($mysqlnd));
/* Use SQL to fetch connection thread id */
var_dump($mysql_connection->query("SELECT CONNECTION_ID()")->fetchAll());
?>
Powyższy przykład wyświetli:
int(27054)
array(1) {
[0]=>
array(2) {
["CONNECTION_ID()"]=>
string(5) "27054"
[0]=>
string(5) "27054"
}
}
mysqlnd_uh_set_connection_proxy
(PECL mysqlnd-uh >= 1.0.0-alpha)
mysqlnd_uh_set_connection_proxy — Installs a proxy for mysqlnd connections
Opis
&$connection_proxy
[, mysqli &$mysqli_connection
] )Installs a proxy object to hook mysqlnd's connection objects methods. Once installed, the proxy will be used for all MySQL connections opened with mysqli, mysql or PDO_MYSQL, assuming that the listed extensions are compiled to use the mysqlnd library.
The function can be disabled with
mysqlnd_uh.enable.
If mysqlnd_uh.enable
is set to FALSE the function will not install the proxy and
always return TRUE. Additionally, an error of the
type E_WARNING may be emitted. The error message may
read like PHP Warning: mysqlnd_uh_set_connection_proxy(): (Mysqlnd User Handler)
The plugin has been disabled by setting the configuration parameter mysqlnd_uh.enable = false.
The proxy has not been installed [...].
Parametry
-
connection_proxy -
A proxy object of type MysqlndUhConnection.
-
mysqli_connection -
Object of type mysqli. If given, the proxy will be set for this particular connection only.
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Przykłady
Przykład #1 mysqlnd_uh_set_connection_proxy() example
<?php
$mysqli = new mysqli("localhost", "root", "", "test");
$mysqli->query("SELECT 'No proxy installed, yet'");
class proxy extends MysqlndUhConnection {
public function query($res, $query) {
printf("%s(%s)\n", __METHOD__, var_export(func_get_args(), true));
$ret = parent::query($res, $query);
printf("%s returns %s\n", __METHOD__, var_export($ret, true));
return $ret;
}
}
mysqlnd_uh_set_connection_proxy(new proxy());
$mysqli->query("SELECT 'mysqlnd rocks!'");
$mysql = mysql_connect("localhost", "root", "", "test");
mysql_query("SELECT 'Ahoy Andrey!'", $mysql);
$pdo = new PDO("mysql:host=localhost;dbname=test", "root", "");
$pdo->query("SELECT 'Moin Johannes!'");
?>
Powyższy przykład wyświetli:
proxy::query(array ( 0 => NULL, 1 => 'SELECT \'mysqlnd rocks!\'', )) proxy::query returns true proxy::query(array ( 0 => NULL, 1 => 'SELECT \'Ahoy Andrey!\'', )) proxy::query returns true proxy::query(array ( 0 => NULL, 1 => 'SELECT \'Moin Johannes!\'', )) proxy::query returns true
Zobacz też:
- mysqlnd_uh_set_statement_proxy() - Installs a proxy for mysqlnd statements
- mysqlnd_uh.enable
mysqlnd_uh_set_statement_proxy
(PECL mysqlnd-uh >= 1.0.0-alpha)
mysqlnd_uh_set_statement_proxy — Installs a proxy for mysqlnd statements
Opis
&$statement_proxy
)Installs a proxy for mysqlnd statements. The proxy object will be used for all mysqlnd prepared statement objects, regardless which PHP MySQL extension (mysqli, mysql, PDO_MYSQL) has created them as long as the extension is compiled to use the mysqlnd library.
The function can be disabled with
mysqlnd_uh.enable.
If mysqlnd_uh.enable
is set to FALSE the function will not install the proxy and
always return TRUE. Additionally, an error of the
type E_WARNING may be emitted. The error message may
read like PHP Warning: mysqlnd_uh_set_statement_proxy(): (Mysqlnd User Handler)
The plugin has been disabled by setting the configuration parameter mysqlnd_uh.enable = false.
The proxy has not been installed [...].
Parametry
-
statement_proxy -
The mysqlnd statement proxy object of type MysqlndUhStatement
Zwracane wartości
Returns TRUE on success.
Otherwise, returns FALSE
Zobacz też:
- mysqlnd_uh_set_connection_proxy() - Installs a proxy for mysqlnd connections
- mysqlnd_uh.enable
Spis treści
- mysqlnd_uh_convert_to_mysqlnd — Converts a MySQL connection handle into a mysqlnd connection handle
- mysqlnd_uh_set_connection_proxy — Installs a proxy for mysqlnd connections
- mysqlnd_uh_set_statement_proxy — Installs a proxy for mysqlnd statements
Change History
Spis treści
The Change History lists major changes users need to be aware if upgrading from one version to another. It is a high level summary of selected changes that may impact applications or might even break backwards compatibility. Please, consult the CHANGES file contained in the source distribution for a more complete list of changes. If you are eager to learn about all changes, even smaller ones that do not make it into the CHANGES file, you may want to monitor PECL commit messages. To do you, you could, for example, subscribe to the PECL commit message mailing list.
PECL/mysqlnd_uh 1.0 series
1.0.1-alpha
- Release date: TBD
- Motto/theme: bug fix release
Feature changes
- Support of PHP 5.4.0 or later.
- BC break: MysqlndUhConnection::changeUser() requires additional passwd_len parameter.
- BC break: MYSQLND_UH_VERSION_STR renamed to MYSQLND_UH_VERSION. MYSQLND_UH_VERSION renamed to MYSQLND_UH_VERSION_ID.
- BC break: mysqlnd_uh.enabled configuration setting renamed to mysqlnd_uh.enable.
1.0.0-alpha
- Release date: 08/2010
- Motto/theme: Initial release
- Wstęp
- Quickstart and Examples
- Instalacja/Konfiguracja
- Stałe predefiniowane
- MysqlndUhConnection — The MysqlndUhConnection class
- MysqlndUhConnection::changeUser — Changes the user of the specified mysqlnd database connection
- MysqlndUhConnection::charsetName — Returns the default character set for the database connection
- MysqlndUhConnection::close — Closes a previously opened database connection
- MysqlndUhConnection::connect — Open a new connection to the MySQL server
- MysqlndUhConnection::__construct — The __construct purpose
- MysqlndUhConnection::endPSession — End a persistent connection
- MysqlndUhConnection::escapeString — Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection
- MysqlndUhConnection::getAffectedRows — Gets the number of affected rows in a previous MySQL operation
- MysqlndUhConnection::getErrorNumber — Returns the error code for the most recent function call
- MysqlndUhConnection::getErrorString — Returns a string description of the last error
- MysqlndUhConnection::getFieldCount — Returns the number of columns for the most recent query
- MysqlndUhConnection::getHostInformation — Returns a string representing the type of connection used
- MysqlndUhConnection::getLastInsertId — Returns the auto generated id used in the last query.
- MysqlndUhConnection::getLastMessage — Retrieves information about the most recently executed query
- MysqlndUhConnection::getProtocolInformation — Returns the version of the MySQL protocol used
- MysqlndUhConnection::getServerInformation — Returns the version of the MySQL server
- MysqlndUhConnection::getServerStatistics — Gets the current system status
- MysqlndUhConnection::getServerVersion — Returns the version of the MySQL server as an integer
- MysqlndUhConnection::getSqlstate — Returns the SQLSTATE error from previous MySQL operation
- MysqlndUhConnection::getStatistics — Returns statistics about the client connection.
- MysqlndUhConnection::getThreadId — Returns the thread ID for the current connection
- MysqlndUhConnection::getWarningCount — Returns the number of warnings from the last query for the given link
- MysqlndUhConnection::init — Initialize mysqlnd connection
- MysqlndUhConnection::killConnection — Asks the server to kill a MySQL thread
- MysqlndUhConnection::listFields — List MySQL table fields
- MysqlndUhConnection::listMethod — Wrapper for assorted list commands
- MysqlndUhConnection::moreResults — Check if there are any more query results from a multi query
- MysqlndUhConnection::nextResult — Prepare next result from multi_query
- MysqlndUhConnection::ping — Pings a server connection, or tries to reconnect if the connection has gone down
- MysqlndUhConnection::query — Performs a query on the database
- MysqlndUhConnection::queryReadResultsetHeader — Read a result set header
- MysqlndUhConnection::reapQuery — Get result from async query
- MysqlndUhConnection::refreshServer — Flush or reset tables and caches
- MysqlndUhConnection::restartPSession — Restart a persistent mysqlnd connection
- MysqlndUhConnection::selectDb — Selects the default database for database queries
- MysqlndUhConnection::sendClose — Sends a close command to MySQL
- MysqlndUhConnection::sendQuery — Sends a query to MySQL
- MysqlndUhConnection::serverDumpDebugInformation — Dump debugging information into the log for the MySQL server
- MysqlndUhConnection::setAutocommit — Turns on or off auto-commiting database modifications
- MysqlndUhConnection::setCharset — Sets the default client character set
- MysqlndUhConnection::setClientOption — Sets a client option
- MysqlndUhConnection::setServerOption — Sets a server option
- MysqlndUhConnection::shutdownServer — The shutdownServer purpose
- MysqlndUhConnection::simpleCommand — Sends a basic COM_* command
- MysqlndUhConnection::simpleCommandHandleResponse — Process a response for a basic COM_* command send to the client
- MysqlndUhConnection::sslSet — Used for establishing secure connections using SSL
- MysqlndUhConnection::stmtInit — Initializes a statement and returns a resource for use with mysqli_statement::prepare
- MysqlndUhConnection::storeResult — Transfers a result set from the last query
- MysqlndUhConnection::txCommit — Commits the current transaction
- MysqlndUhConnection::txRollback — Rolls back current transaction
- MysqlndUhConnection::useResult — Initiate a result set retrieval
- MysqlndUhPreparedStatement — The MysqlndUhPreparedStatement class
- MysqlndUhPreparedStatement::__construct — The __construct purpose
- MysqlndUhPreparedStatement::execute — Executes a prepared Query
- MysqlndUhPreparedStatement::prepare — Prepare an SQL statement for execution
- Mysqlnd_uh Funkcje
- mysqlnd_uh_convert_to_mysqlnd — Converts a MySQL connection handle into a mysqlnd connection handle
- mysqlnd_uh_set_connection_proxy — Installs a proxy for mysqlnd connections
- mysqlnd_uh_set_statement_proxy — Installs a proxy for mysqlnd statements
- Change History
- Overview of the MySQL PHP drivers
- Mysql — Oryginalne API MySQL
- Mysqli — MySQL Improved Extension
- Wstęp
- Overview
- Quick start guide
- Instalacja/Konfiguracja
- The mysqli Extension and Persistent Connections
- Stałe predefiniowane
- Notes
- The MySQLi Extension Function Summary
- mysqli — The mysqli class
- mysqli_stmt — The mysqli_stmt class
- mysqli_result — The mysqli_result class
- mysqli_driver — The mysqli_driver class
- mysqli_warning — The mysqli_warning class
- mysqli_sql_exception — The mysqli_sql_exception class
- Aliases and deprecated Mysqli Funkcje
- Mysqlnd — MySQL Native Driver
- mysqlnd_ms — Mysqlnd replication and load balancing plugin
- mysqlnd_qc — Mysqlnd query result cache plugin
- mysqlnd_uh — Mysqlnd user handler plugin
- Wstęp
- Quickstart and Examples
- Instalacja/Konfiguracja
- Stałe predefiniowane
- MysqlndUhConnection — The MysqlndUhConnection class
- MysqlndUhPreparedStatement — The MysqlndUhPreparedStatement class
- Mysqlnd_uh Funkcje
- Change History
Oracle OCI8
Wstęp
These functions allow you to access Oracle Database 11g, 10g, 9i and 8i. They support SQL and PL/SQL statements. Basic features include transaction control, binding of PHP variables to Oracle placeholders, and support for large object (LOB) types and collections. Oracle's scalability features such as Database Resident Connection Pooling (DRCP) and result caching are also supported.
Instalacja/Konfiguracja
Spis treści
Wymagania
The OCI8 extension requires Oracle 9iR2, 10g or 11g Client libraries. If the Oracle Database is on the same machine as PHP, the database software already contains the necessary libraries. When PHP is on a different machine, use the free » Oracle Instant Client libraries.
To use Oracle Instant Client, install the basic or basiclite Oracle Instant Client ZIP file or RPM package. When building PHP from source code, also install the sdk ZIP file or devel RPM package.
On Windows, the php_oci8 DLL needs client libraries from version 10gR2 or greater. In PHP 5.3 up to and including PHP 5.3.5, the php_oci8_11g DLL requires Oracle 11gR1 or greater client libraries. From PHP 5.3.6 the php_oci8_11g DLL requires Oracle 11gR2 or greater client libraries. With some versions of Instant Client you may additionally need mfc71.dll and msvcr71.dll libraries.
You should run PHP with the same, or more recent, version of the Oracle libraries that OCI8 was built with.
Informacja:
If OCI8 uses 9iR2 or 10g client libraries, then PHP can connect to Oracle Database 8i, 9iR2, 10g or 11g. If OCI8 uses 11g client libraries, the database can be 9iR2, 10g or 11g.
Informacja:
Full OCI8 feature support is only available when using the most recent versions of the client libraries and database.
Instalacja
Configuring PHP with OCI8
Review the previous Requirements section before configuring OCI8.
To enable the OCI8 extension, configure PHP with the option --with-oci8 .
Before starting the web server, OCI8 typically requires several Oracle environment variables (see below) to locate libraries, point to configuration files, and set some basic properties such as the character set used by Oracle libraries. The variables should be set before any PHP process starts.
PHP should be run with the same, or more recent, major version of Oracle libraries as it was configured with. For example, if you build OCI8 with Oracle 11.2 libraries, then PHP should also be deployed and run with Oracle 11.2 libraries.
Installing OCI8 as a Shared Extension
The configuration shared option builds OCI8 as a shared library that can be dynamically loaded into PHP. Building a shared extension allows OCI8 to be upgraded easily without impacting the rest of PHP.
Configure OCI8 using one of the following configure options.
-
If using Oracle Instant Client, then do:
./configure --with-oci8=shared,instantclient,/path/to/instant/client/lib
If Instant Client is installed from ZIP files, make sure to create the library symbolic link, for example ln -s libclntsh.so.11.1 libclntsh.so.
If using an RPM-based installation of Oracle Instant Client, the configure line will look like this:
./configure --with-oci8=shared,instantclient,/usr/lib/oracle/<version>/client/lib
For example, --with-oci8=shared,instantclient,/usr/lib/oracle/11.2/client/lib .
Note that Oracle Instant Client support first appeared in PHP 4.3.11 and 5.0.4 and originally used the option --with-oci8-instant-client to configure PHP.
-
If using an Oracle database or full Oracle Client installation then do:
./configure --with-oci8=shared,$ORACLE_HOME
Make sure the web server user (nobody, www) has access to the libraries, initialization files and tnsnames.ora (if used) under the $ORACLE_HOME directory. With Oracle 10gR2, you may need to run the $ORACLE_HOME/install/changePerm.sh utility to give directory access.
After configuration, follow the usual PHP building procedure, e.g. make install. The OCI8 shared extension oci8.so library will be created. It may need to be manually moved to the PHP extension directory, specified by the extension_dir option in your php.ini file.
To complete installation of OCI8, edit php.ini and add the line:
extension=oci8.so
Installing OCI8 as a Statically Compiled Extension
Configure OCI8 using one of the following configure options.
-
If using Oracle Instant Client, then do:
./configure --with-oci8=instantclient,/path/to/instant/client/lib
-
If using an Oracle database or full Oracle Client installation then do:
./configure --with-oci8=$ORACLE_HOME
After configuration, follow the usual PHP building procedure, e.g. make install. After successful compilation, you do not need to add oci8.so to php.ini. No additional build steps are required.
Installing OCI8 from PECL
The OCI8 extension can be added to an existing PHP installation either automatically or manually from » http://pecl.php.net/. Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/oci8.
For an automated install follow these steps:
-
If you are behind a firewall, set PEAR's proxy, for example:
pear config-set http_proxy http://my-proxy.example.com:80/
-
Run
pecl install oci8
When prompted, enter either the value of $ORACLE_HOME, or instantclient,/path/to/instant/client/lib.
Note: Do not enter the variable $ORACLE_HOME because it will not be expanded. Instead, enter the actual path of the Oracle home directory.
For a manual install, download the PECL OCI8 package, e.g. oci8-1.3.5.tgz.
-
Extract the package:
tar -zxf oci8-1.3.5.tgz cd oci8-1.3.5
-
Prepare the package:
phpize
-
Configure the package, either using $ORACLE_HOME or Instant Client
./configure -with-oci8=shared,$ORACLE_HOME
or
./configure -with-oci8=shared,instantclient,/path/to/instant/client/lib
-
Install the package:
make install
After either an automatic or manual install, edit your php.ini file and add the line:
extension=oci8.so
Make sure the php.ini directive extension_dir is set to the directory that oci8.so was installed in.
Installing OCI8 on Windows
On Windows, uncomment the php.ini line extension=php_oci8.dll when using Oracle 10gR2 client libraries. Uncomment extension=php_oci8_11g.dll when using Oracle 11g client libraries. These two DLLs contain equivalent functionality and only one may be enabled at a time. Make sure extension_dir is set to the directory containing the PHP extension DLLs.
If using Instant Client, set the system PATH environment variable to the Oracle library directory.
Setting the Oracle Environment
Before using this extension, make sure that the Oracle environment variables are properly set for the web daemon user. If your web server is automatically started at boot time then make sure that the boot-time environment is also configured correctly.
Informacja:
Do not set Oracle environment variables using putenv() in a PHP script because Oracle libraries may be loaded and initialized before your script runs. Variables set with putenv() may then cause conflicts, crashes, or unpredictable behavior. Some functions may work but others might give subtle errors. The variables should be set up before the web server is started.
On Red Hat Linux and variants, export variables at the end of /etc/sysconfig/httpd. Other systems with Apache 2 may use an envvars script in the Apache bin directory. A third option, the Apache SetEnv directive in httpd.conf, may work in some systems but is known to be insufficient in others.
To check that environment variables are set correctly, use phpinfo() and check the Environment (not the Apache Environment) section contains the expected variables.
The variables that might be needed are included in the following table. Refer to the Oracle documentation for more information on all the variables.
| Name | Purpose |
|---|---|
| ORACLE_HOME | Contains the directory of the full Oracle Database software. Do not set this when using Oracle Instant Client as it is unnecessary and may cause installation problems. |
| ORACLE_SID | Contains the name of the database on the local machine to be connected to. There is no need to set this if you using Oracle Instant Client, or always pass the connection parameter to oci_connect(). |
| LD_LIBRARY_PATH | Set this (or its platform equivalent, such as DYLD_LIBRARY_PATH, LIBPATH, or SHLIB_PATH) to the location of the Oracle libraries, for example $ORACLE_HOME/lib or /usr/lib/oracle/11.1/client/lib. This variable is not needed if the libraries are located by a different search mechanism, such as with ldconfig or with LD_PRELOAD. |
| NLS_LANG | This is the primary variable for setting the character set and globalization information used by the Oracle libraries. |
| ORA_SDTZ | Sets the Oracle session timezone. |
| TNS_ADMIN | Contains the directory where the Oracle Net Services configuration files such as tnsnames.ora and sqlnet.ora are kept. Not needed if the oci_connect() connection string uses the Easy Connect naming syntax such as localhost/XE. Not needed if the network configuration files are in one of the default locations such as $ORACLE_HOME/network/admin or /etc. |
Troubleshooting
The most common problem with installing OCI8 is not having the Oracle environment correctly set. This typically appears as a problem using oci_connect() or oci_pconnect(). The error may be a PHP error such as Call to undefined function oci_connect(), an Oracle error such as ORA-12705, or even an Apache crash. Check the Apache log files for startup errors and see the sections above to resolve this problem.
While network errors like ORA-12154 or ORA-12514 indicate an Oracle network naming or configuration issue, the root cause may be because the PHP environment is incorrectly set up and Oracle libraries are unable to locate the tnsnames.ora configuration file.
On Windows, having multiple versions of Oracle on the one machine can easily cause library clashes unless care is taken to make sure PHP only uses the correct version of Oracle.
A utility to examine what libraries are being looked for and loaded can help resolve missing or clashing library issues, particularly on Windows.
Informacja: If the web server doesn't start or crashes at startup
Check that Apache is linked with the pthread library:
# ldd /www/apache/bin/httpd libpthread.so.0 => /lib/libpthread.so.0 (0x4001c000) libm.so.6 => /lib/libm.so.6 (0x4002f000) libcrypt.so.1 => /lib/libcrypt.so.1 (0x4004c000) libdl.so.2 => /lib/libdl.so.2 (0x4007a000) libc.so.6 => /lib/libc.so.6 (0x4007e000) /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)If the libpthread is not listed, then reinstall Apache:
# cd /usr/src/apache_1.3.xx # make clean # LIBS=-lpthread ./config.status # make # make installPlease note that on some systems like UnixWare, it is libthread instead of libpthread. PHP and Apache have to be configured with EXTRA_LIBS=-lthread.
Testing
The OCI8 test suite is in ext/oci8/tests. After OCI8 tests are run this directory will also contain logs of any failures.
Before running PHP's tests, edit details.inc and set $user, $password and the $dbase connection string. The OCI8 test suite has been developed using the SYSTEM account. Some tests will fail if the test user does not have equivalent permissions.
If Oracle 11g Database Resident Connection Pooling is being
tested, set $test_drcp to TRUE and ensure the
connection string uses an appropriate DRCP pooled server.
An alternative to editing details.inc is the set environment variables, for example:
$ export PHP_OCI8_TEST_USER=system
$ export PHP_OCI8_TEST_PASS=oracle
$ export PHP_OCI8_TEST_DB=localhost/XE
$ export PHP_OCI8_TEST_DRCP=FALSE
Next, set any necessary environment for the Oracle database. With Oracle 10gR2 XE do:
$ . /usr/lib/oracle/xe/app/oracle/product/10.2.0/server/bin/oracle_env.sh
With Oracle 11gR2 XE do:
$ . /u01/app/oracle/product/11.2.0/xe/bin/oracle_env.sh
For other versions of the Oracle database do:
$ . /usr/local/bin/oraenv
Some shells require that php.ini has E in the variables_order parameter, for example:
variables_order = "EGPCS"
Run all the PHP tests with:
$ cd your_php_src_directory
$ make test
$ cd your_php_src_directory
$ make test TESTS=ext/oci8
When the tests have completed, review any test failures. On slow systems, some tests may take longer than the default test timeout in run-tests.php. To correct this, set the environment variable TEST_TIMEOUT to a larger number of seconds.
On fast machines with a local database configured for light load (e.g. Oracle 11gR2 XE) some tests might fail with ORA-12516 or ORA-12520 errors. To prevent this, increase the database PROCESSES parameter using the following steps:
Connect as the oracle software owner:
$ su - oracle
Set the necessary Oracle environment with oracle_env.sh or oraenv, as described above.
Start the SQL*Plus command line tool and increase PROCESSES
$ sqlplus / as sysdba
SQL> alter system set processes=100 scope=spfile
Restart the database:
SQL> startup force
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| oci8.connection_class | "" | PHP_INI_ALL | Available since PHP 5.3 (PECL OCI8 1.3). |
| oci8.default_prefetch | "100" | PHP_INI_SYSTEM | Available since PHP 5.1.2 (PECL OCI8 1.1). |
| oci8.events | Off | PHP_INI_SYSTEM | Available since PHP 5.3 (PECL OCI8 1.3). |
| oci8.max_persistent | "-1" | PHP_INI_SYSTEM | Available since PHP 5.1.2 (PECL OCI8 1.1). |
| oci8.old_oci_close_semantics | Off | PHP_INI_SYSTEM | Available since PHP 5.1.2 (PECL OCI8 1.1). |
| oci8.persistent_timeout | "-1" | PHP_INI_SYSTEM | Available since PHP 5.1.2 (PECL OCI8 1.1). |
| oci8.ping_interval | "60" | PHP_INI_SYSTEM | Available since PHP 5.1.2 (PECL OCI8 1.1). |
| oci8.privileged_connect | Off | PHP_INI_SYSTEM | Available since PHP 5.1.2 (PECL OCI8 1.1). |
| oci8.statement_cache_size | "20" | PHP_INI_SYSTEM | Available since PHP 5.1.2 (PECL OCI8 1.1). |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
oci8.connection_classstring -
This user defined text is used by Oracle 11g Database Resident Connection Pooling (DRCP) connections to sub-partition the connection pool. It allows OCI8 persistent connections from an application to reuse database sessions from a previous PHP script, giving better scalability. When an application uses a database pooled process previously used with a different connection class, the session settings such as the default Oracle date format are reset. This prevents accidental sharing of information between different applications.
The value can be set at runtime with ini_set() prior to connecting.
To use DRCP, OCI8 must be linked with Oracle 11g libraries and the database must be Oracle 11g. The connection pool must be enabled in the database, the oci8.connection_class should be set to the same string for all web servers running the same application, and the OCI8 connection string must specify to use a pooled server.
-
oci8.default_prefetchint -
This option sets the default number of extra rows that will be fetched and cached automatically whenever a low-level request for data from the database is made. Setting a value of 0 turns off prefetching.
The prefetch value does not alter the number of rows that functions like oci_fetch_array() return to the user; the prefetching and caching of rows is handled internally in OCI8.
The value can be set per-statement with oci_set_prefetch() prior to statement execution.
In PHP 5.3 (PECL OCI8 1.3.4) the default value was increased from 10 to 100.
In PHP 5.3.2 (PECL OCI8 1.4) the minimum value settable was reduced from 1 to 0, allowing prefetching to be turned off.
Informacja: A larger prefetch can result in improved performance, at the cost of some increased memory usage. For queries that return large amounts of data, the performance benefit can be significant.
-
oci8.eventsboolean -
Using On allows PHP to be notified of database Fast Application Notification (FAN) events.
Without FAN, when a database instance or machine node fails unexpectedly, PHP applications may be blocked waiting for a database response until a TCP timeout expires. With FAN events, PHP applications are quickly notified of failures that affect their established database connections. The OCI8 extension will clean up unusable connections in the persistent connection cache.
When using On, the database must also be configured to post FAN events.
FAN support is available when OCI8 is linked with Oracle 10gR2 (or later) libraries and connected to Oracle Database 10gR2 (or later).
-
oci8.max_persistentint -
The maximum number of persistent OCI8 connections per PHP process. Setting this option to -1 means that there is no limit.
-
oci8.old_oci_close_semanticsboolean -
This option controls oci_close() behaviour. Enabling it means that oci_close() will do nothing; the connection will not be closed until the end of the script. This is for backward compatibility only. If you find that you need to enable this setting, you are strongly encouraged to adjust the oci_close() calls in your application instead of enabling this option.
-
oci8.persistent_timeoutint -
The maximum number of seconds that a PHP process is allowed to keep an idle persistent connection open. Setting this option to -1 means that idle persistent connections will be retained until the PHP process terminates or the connection is explicitly closed with oci_close().
Informacja: In PHP, the expiry of idle resources is not alarm-based. It occurs when PHP finishes processing a script and checks the last-used timestamp of resources. Hence there is a paradox that idle connections can only be closed when there is some activity (though not necessarily OCI8 related) in the PHP process. If there is more than one PHP process then each must individually be activated in order to trigger expiry of its idle resources. The introduction of Database Resident Connection Pooling (DRCP) in Oracle 11g resolves the memory and resource issues that oci8.max_persistent and oci8.persistent_timeout previously attempted to overcome.
Informacja: In PHP 5.3 (PECL OCI8 1.3), persistent connections can be closed with oci_close().
-
oci8.ping_intervalint -
The number of seconds that must pass before issuing a ping during oci_pconnect(). A ping ensures that the database connection is valid. When set to 0, persistent connections will be pinged every time oci_pconnect() is called. To disable pings completely, set this option to -1.
Informacja: Disabling pings allows oci_pconnect() to operate at the highest efficiency, but PHP may not be able to detect unusable connections, such as caused by network dropout, or if the Oracle database has gone down since PHP connected, until the connection is used later in the script. Consult the oci_pconnect() documentation for more information.
-
oci8.privileged_connectboolean -
This option allows connections to use the privileged external credentials
OCI_SYSOPERorOCI_SYSDBA.Informacja: Seting this On can allow scripts on web servers running with the appropriate OS user privileges to connect as privileged database users without requiring a database password. This can be a security risk.
-
oci8.statement_cache_sizeint -
This option enables statement caching, and specifies how many statements to cache. To disable statement caching just set this option to 0.
Statement caching removes the need to transmit the statement text to the database and removes the need to transmit any meta data about the statement back to PHP. This can significantly improve overall system performance in applications which reuse statements during the lifetime of a connection. Some extra database "cursors" may be held open under the assumption that statements will be reused.
Set this value to the size of the working set of statements used by your application. Setting too small a value can cause statements to be flushed from the cache before they are reused.
This option is of most use with persistent connections.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
| Constant | Description |
|---|---|
OCI_ASSOC |
Used with oci_fetch_all() and oci_fetch_array() to get results as an associative array. |
OCI_BOTH |
Used with oci_fetch_all() and oci_fetch_array() to get results as an array with both associative and number indices. |
OCI_COMMIT_ON_SUCCESS |
Statement execution mode for oci_execute() call. Automatically commit changes when the statement has succeeded. |
OCI_CRED_EXT |
Used with oci_connect() for using Oracles' External or OS authentication. Introduced in PHP 5.3 and PECL OCI8 1.3.4. |
OCI_DEFAULT |
Statement execution mode
for oci_execute(). The transaction is
not automatically committed when using this mode. From PHP
5.3.2 (PECL OCI8 1.4) onwards,
OCI_NO_AUTO_COMMIT is preferred instead
of OCI_DEFAULT.
|
OCI_DESCRIBE_ONLY |
Statement execution mode for oci_execute(). Use this mode if you want meta data such as the column names but don't want to fetch rows from the query. |
OCI_EXACT_FETCH |
Obsolete. Statement fetch mode. Used when the application knows in advance exactly how many rows it will be fetching. This mode turns prefetching off for Oracle release 8 or later mode. The cursor is canceled after the desired rows are fetched which may result in reduced server-side resource usage. |
OCI_FETCHSTATEMENT_BY_COLUMN |
Default mode of oci_fetch_all(). |
OCI_FETCHSTATEMENT_BY_ROW |
Alternative mode of oci_fetch_all(). |
OCI_LOB_BUFFER_FREE |
Used with OCI-Lob::flush to free buffers used. |
OCI_NO_AUTO_COMMIT |
Statement execution mode
for oci_execute(). The statement is not
committed automatically when using this mode. For
readability in new code, use this value instead of the
obsolete OCI_DEFAULT constant.
Introduced in PHP 5.3.2 (PECL OCI8 1.4).
|
OCI_NUM |
Used with oci_fetch_all() and oci_fetch_array() to get results as an enumerated array. |
OCI_RETURN_LOBS |
Used with oci_fetch_array() to get the data value of the LOB instead of the descriptor. |
OCI_RETURN_NULLS |
Used with oci_fetch_array() to get empty
array elements if the row items value is NULL.
|
OCI_SEEK_CUR |
Used with OCI-Lob::seek to set the seek position. |
OCI_SEEK_END |
Used with OCI-Lob::seek to set the seek position. |
OCI_SEEK_SET |
Used with OCI-Lob::seek to set the seek position. |
OCI_SYSDATE |
Obsolete. |
OCI_SYSDBA |
Used with oci_connect() to connect with the SYSDBA privilege. The php.ini setting oci8.privileged_connect should be enabled to use this. |
OCI_SYSOPER |
Used with oci_connect() to connect with the SYSOPER privilege. The php.ini setting oci8.privileged_connect should be enabled to use this. |
OCI_TEMP_BLOB |
Used with OCI-Lob::writeTemporary to indicate that a temporary BLOB should be created. |
OCI_TEMP_CLOB |
Used with OCI-Lob::writeTemporary to indicate that a temporary CLOB should be created. |
| Constant | Description |
|---|---|
OCI_B_BFILE |
Used with oci_bind_by_name() when binding BFILEs. |
OCI_B_BIN |
Used with oci_bind_by_name() to bind RAW values. |
OCI_B_BLOB |
Used with oci_bind_by_name() when binding BLOBs. |
OCI_B_CFILEE |
Used with oci_bind_by_name() when binding CFILEs. |
OCI_B_CLOB |
Used with oci_bind_by_name() when binding CLOBs. |
OCI_B_CURSOR |
Used with oci_bind_by_name() when binding cursors, previously allocated with oci_new_descriptor(). |
OCI_B_INT |
Used with oci_bind_array_by_name() to bind arrays of INTEGER. |
OCI_B_NTY |
Used with oci_bind_by_name() when binding
named data types. Note: in PHP < 5.0 it was called
OCI_B_SQLT_NTY.
|
OCI_B_NUM |
Used with oci_bind_array_by_name() to bind arrays of NUMBER. |
OCI_B_ROWID |
Used with oci_bind_by_name() when binding ROWIDs. |
SQLT_AFC |
Used with oci_bind_array_by_name() to bind arrays of CHAR. |
SQLT_AVC |
Used with oci_bind_array_by_name() to bind arrays of VARCHAR2. |
SQLT_BDOUBLE |
Not supported. |
SQLT_BFILEE |
The same as OCI_B_BFILE.
|
SQLT_BFLOAT |
Not supported. |
SQLT_BIN |
The same as OCI_B_BIN.
|
SQLT_BLOB |
The same as OCI_B_BLOB.
|
SQLT_CFILEE |
The same as OCI_B_CFILEE.
|
SQLT_CHR |
Used with oci_bind_array_by_name() to bind arrays of VARCHAR2. Also used with oci_bind_by_name(). |
SQLT_CLOB |
The same as OCI_B_CLOB.
|
SQLT_FLT |
Used with oci_bind_array_by_name() to bind arrays of FLOAT. |
SQLT_INT |
The same as OCI_B_INT.
|
SQLT_LBI |
Used with oci_bind_by_name() to bind LONG RAW values. |
SQLT_LNG |
Used with oci_bind_by_name() to bind LONG values. |
SQLT_LVC |
Used with oci_bind_array_by_name() to bind arrays of LONG VARCHAR. |
SQLT_NTY |
The same as OCI_B_NTY.
|
SQLT_NUM |
The same as OCI_B_NUM.
|
SQLT_ODT |
Used with oci_bind_array_by_name() to bind arrays of LONG. |
SQLT_RDD |
The same as OCI_B_ROWID.
|
SQLT_RSET |
The same as OCI_B_CURSOR.
|
SQLT_STR |
Used with oci_bind_array_by_name() to bind arrays of STRING. |
SQLT_UIN |
Not supported. |
SQLT_VCS |
Used with oci_bind_array_by_name() to bind arrays of VARCHAR. |
| Constant | Description |
|---|---|
OCI_DTYPE_FILE |
This flag tells oci_new_descriptor() to initialize a new FILE descriptor. |
OCI_DTYPE_LOB |
This flag tells oci_new_descriptor() to initialize a new LOB descriptor. |
OCI_DTYPE_ROWID |
This flag tells oci_new_descriptor() to initialize a new ROWID descriptor. |
OCI_D_FILE |
The same as OCI_DTYPE_FILE.
|
OCI_D_LOB |
The same as OCI_DTYPE_LOB.
|
OCI_D_ROWID |
The same as OCI_DTYPE_ROWID.
|
Przykłady
These examples connect as the HR user, which is the sample "Human Resources" schema supplied with the Oracle database. The account may need to be unlocked and the password reset before you can use it.
The examples connect to the XE database on your machine. Change the connect string to your database before running the examples.
Przykład #1 Basic query
This shows querying and displaying results. Statements in OCI8 use a prepare-execute-fetch sequence of steps.
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
// Prepare the statement
$stid = oci_parse($conn, 'SELECT * FROM departments');
if (!$stid) {
$e = oci_error($conn);
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
// Perform the logic of the query
$r = oci_execute($stid);
if (!$r) {
$e = oci_error($stid);
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
// Fetch the results of the query
print "<table border='1'>\n";
while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
print "<tr>\n";
foreach ($row as $item) {
print " <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : " ") . "</td>\n";
}
print "</tr>\n";
}
print "</table>\n";
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #2 Inserting with bind variables
Bind variables improve performance by allowing reuse of execution contexts and caches. Bind variables improve security by preventing some kinds of SQL Injection problems.
<?php
// Before running, create the table:
// CREATE TABLE MYTABLE (mid NUMBER, myd VARCHAR2(20));
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$stid = oci_parse($conn, 'INSERT INTO MYTABLE (mid, myd) VALUES(:myid, :mydata)');
$id = 60;
$data = 'Some data';
oci_bind_by_name($stid, ':myid', $id);
oci_bind_by_name($stid, ':mydata', $data);
$r = oci_execute($stid); // executes and commits
if ($r) {
print "One row inserted";
}
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #3 Inserting data into a CLOB column
For large data use binary long object (BLOB) or character long object (CLOB) types. This example uses CLOB.
<?php
// Before running, create the table:
// CREATE TABLE MYTABLE (mykey NUMBER, myclob CLOB);
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$mykey = 12343; // arbitrary key for this example;
$sql = "INSERT INTO mytable (mykey, myclob)
VALUES (:mykey, EMPTY_CLOB())
RETURNING myclob INTO :myclob";
$stid = oci_parse($conn, $sql);
$clob = oci_new_descriptor($conn, OCI_D_LOB);
oci_bind_by_name($stid, ":mykey", $mykey, 5);
oci_bind_by_name($stid, ":myclob", $clob, -1, OCI_B_CLOB);
oci_execute($stid, OCI_NO_AUTO_COMMIT); // use OCI_DEFAULT for PHP <= 5.3.1
$clob->save("A very long string");
oci_commit($conn);
// Fetching CLOB data
$query = 'SELECT myclob FROM mytable WHERE mykey = :mykey';
$stid = oci_parse ($conn, $query);
oci_bind_by_name($stid, ":mykey", $mykey, 5);
oci_execute($stid);
print '<table border="1">';
while ($row = oci_fetch_array($stid, OCI_ASSOC)) {
$result = $row['MYCLOB']->load();
print '<tr><td>'.$result.'</td></tr>';
}
print '</table>';
?>
Przykład #4 Using a PL/SQL stored function
You must bind a variable for the return value and optionally for any PL/SQL function arguments.
<?php
/*
Before running the PHP program, create a stored function in
SQL*Plus or SQL Developer:
CREATE OR REPLACE FUNCTION myfunc(p IN NUMBER) RETURN NUMBER AS
BEGIN
RETURN p * 3;
END;
*/
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$p = 8;
$stid = oci_parse($conn, 'begin :r := myfunc(:p); end;');
oci_bind_by_name($stid, ':p', $p);
oci_bind_by_name($stid, ':r', $r, 40);
oci_execute($stid);
print "$r\n"; // prints 24
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #5 Using a PL/SQL stored procedure
With stored procedures, you should bind variables for any arguments.
<?php
/*
Before running the PHP program, create a stored procedure in
SQL*Plus or SQL Developer:
CREATE OR REPLACE PROCEDURE myproc(p1 IN NUMBER, p2 OUT NUMBER) AS
BEGIN
p2 := p1 * 2;
END;
*/
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$p1 = 8;
$stid = oci_parse($conn, 'begin myproc(:p1, :p2); end;');
oci_bind_by_name($stid, ':p1', $p1);
oci_bind_by_name($stid, ':p2', $p2, 40);
oci_execute($stid);
print "$p2\n"; // prints 16
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #6 Calling a PL/SQL function that returns a REF CURSOR
Each returned value from the query is a REF CURSOR that can be fetched from.
<?php
/*
Create the PL/SQL stored function as:
CREATE OR REPLACE FUNCTION myfunc(p1 IN NUMBER) RETURN SYS_REFCURSOR AS
rc SYS_REFCURSOR;
BEGIN
OPEN rc FOR SELECT city FROM locations WHERE ROWNUM < p1;
RETURN rc;
END;
*/
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
$stid = oci_parse($conn, 'SELECT myfunc(5) AS mfrc FROM dual');
oci_execute($stid);
echo "<table border='1'>\n";
while (($row = oci_fetch_array($stid, OCI_ASSOC))) {
echo "<tr>\n";
$rc = $row['MFRC'];
oci_execute($rc); // returned column value from the query is a ref cursor
while (($rc_row = oci_fetch_array($rc, OCI_ASSOC))) {
echo " <td>" . $rc_row['CITY'] . "</td>\n";
}
oci_free_statement($rc);
echo "</tr>\n";
}
echo "</table>\n";
// Output is:
// Beijing
// Bern
// Bombay
// Geneva
oci_free_statement($stid);
oci_close($conn);
?>
Connection Handling
Connection Functions
The OCI8 extension provides three different functions for connecting to Oracle. The standard connection function is oci_connect(). This creates a connection to an Oracle database and returns a resource used by subsequent database calls.
Connecting to an Oracle server is a reasonably expensive operation in terms of the time that it takes to complete. The oci_pconnect() function uses a persistent cache of connections that can be re-used across different script requests. This means that the connection overhead will typically only occur once per PHP process (or Apache child).
If the application connects to Oracle using a different set of credentials for each web user, the persistent cache employed by oci_pconnect() will become less useful as the number of concurrent users increases, to the point where it may start to adversely affect the overall performance of the Oracle server due to maintaining too many idle connections. If the application is structured in this way, it is recommended to either tune the application using the oci8.max_persistent and oci8.persistent_timeout configuration settings (these will give control over the persistent connection cache size and lifetime), use Oracle 11g Database Resident Connection Pooling, or use oci_connect() instead.
Both oci_connect() and oci_pconnect() employ a connection cache; if multiple calls to oci_connect() use the same parameters in a given script, the second and subsequent calls return the existing connection handle. The cache used by oci_connect() is cleaned up at the end of the script run, or when the connection handle is explicitly closed. The function oci_pconnect() has similar behavior, although its cache is maintained separately and survives between HTTP requests.
This caching feature means the two handles are not transactionally isolated (they are in fact the same connection handle, so there is no isolation of any kind). If the application needs two separate, transactionally isolated connections, then use oci_new_connect().
The oci_pconnect() cache is cleared and any database connections closed when the PHP process terminates, so effective use of persistent connections requires that PHP be an Apache module or used with FGCI, or similar. Persistent connections will not have any benefits over oci_connect() when PHP is used with CGI or via the command-line.
The function oci_new_connect() always creates a new connection to the Oracle server, regardless of what other connections might already exist. High traffic web applications should avoid using oci_new_connect(), especially in the busiest sections of the application.
DRCP Connection Pooling
PHP 5.3 (PECL OCI8 1.3) supports Oracle 11g Database Resident Connection Pooling (DRCP). DRCP allows more efficient use of database machine memory and provides high scalability. No, or minimal, application changes are needed to use DRCP.
DRCP is suited for applications that connect using few database schemas and hold database connections open for a short period of time. Other applications should use Oracle's default Dedicated database server processes, or use Shared servers.
DRCP benefits all three connection functions, but gives the highest scalability when connections are created with oci_pconnect().
For DRCP to be available in OCI8, Oracle client libraries used by PHP and the version of the Oracle Database must both be 11g.
Documentation on DRCP is found in several Oracle manuals. For example, see » Configuring Database Resident Connection Pooling in the Oracle documentation for usage information. A » DRCP white paper contains background information on DRCP.
To use DRCP, build PHP with the OCI8 1.3 extension and Oracle 11g libraries and then follow these steps:
-
As a privileged database administrator, use a program like SQL*Plus to start the connection pool in the database:
SQL> execute dbms_connection_pool.start_pool; -
Optionally use dbms_connection_pool.alter_param() to configure DRCP settings. The current pool settings can be queried from the DBA_CPOOL_INFO view.
-
Update the connection strings used. For PHP applications that currently connect using a Network Connect Name like MYDB:
$c = oci_pconnect("myuser", "mypassword", "MYDB");modify the tnsnames.ora file and add a (SERVER=POOLED) clause, for example:
MYDB = (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp) (HOST=myhost.dom.com) (PORT=1521))(CONNECT_DATA=(SERVICE_NAME=sales) (SERVER=POOLED)))Alternatively, modify the Easy Connect syntax in PHP and add :POOLED after the service name:
$c = oci_pconnect("myuser", "mypassword", "myhost.dom.com:1521/sales:POOLED"); -
Edit php.ini and choose a connection class name. This name indicates a logical division of the connection pool and can be used to isolate pooling for separate applications. Any PHP applications with the same user name and connection class value will be able to share connections in the pool, giving greater scalability.
oci8.connection_class = "MY_APPLICATION_NAME" -
Run the application, connecting to the 11g database.
Informacja:
Applications using Oracle 10g that require the performance of persistent connections can reduce the amount of database server memory needed by using Oracle Shared servers (previously known as Multi Threaded Servers). Refer to Oracle documentation for information.
DRCP Recommendations and Known Limitations
Changing a password over DRCP connections will fail with the error ORA-56609: Usage not supported with DRCP. This is a documented restriction of Oracle Database 11g.
With the OCI8 1.3 extension, persistent connections can now be closed by the user, allowing greater control over connection resource usage. Persistent connections will now also be closed automatically when there is no PHP variable referencing them, such as at the end of scope of a PHP user function. This will rollback any uncommitted transaction. These changes to persistent connections make them behave similarly to non-persistent connections, simplifying the interface, allowing for greater application consistency and predictability. Use oci8.old_oci_close_semantics set to On to retain the historical behavior.
If the Oracle Database is version 11.1.0.6, then the Oracle database patch for Oracle bug 6474441 must be applied to use DRCP. Without this patch, errors such as ORA-01000: maximum open cursors exceeded, ORA-01001 invalid cursor or ORA-01002 fetch out of sequence may occur. This bug was fixed in Oracle 11.1.0.7 onwards.
If the Oracle 11.1.0.6 database patch cannot be applied, one of the following three workarounds can be used instead:
- Connect using Oracle Dedicated or Shared servers instead of DRCP.
- Set PHP's oci8.statement_cache_size to 0.
- Set an event in the database initialization parameter file: event="56699 trace name context forever, level 128".
Oracle Database 11.1.0.7 and the Oracle Database 11.1.0.6 patch for Oracle bug 6474441 allow PHP applications with DRCP connection to use a database LOGON trigger to set session properties at the time of session creation. Examples of such settings are the NLS language and the date format.
If the Oracle 11.1.0.6 database patch cannot be applied, one of the following workarounds can be used instead of using LOGON triggers:
- After logon, explicitly set the session properties using PHP application code.
- Connect using Oracle Dedicated or Shared servers instead of DRCP.
The automatic re-establishment of PHP persistent connections after an Apache or FGCI process respawns means LOGON triggers in PHP are only recommended for setting session attributes and not for per-application user connection requests. This is even more so with DRCP due to the automatic pool sizing and with the way LOGON triggers fire with DRCP authentication.
Fast Application Notification (FAN) Support
FAN support gives fast connection failover, a high availability feature. This allows PHP OCI8 scripts to be notified when a database machine or database instance becomes unavailable. Without FAN, OCI8 can hang until a TCP timeout occurs and an error is returned, which might be several minutes. Enabling FAN in OCI8 can allow applications to detect errors and re-connect to an available database instance without the web user being aware of an outage.
FAN support is available when the Oracle client libraries that PHP links with and the Oracle Database are either version 10gR2 or 11g.
FAN benefits users of Oracle's clustering technology (RAC) because connections to surviving database instances can be immediately made. Users of Oracle's Data Guard with a broker will see the FAN events generated when the standby database goes online. Standalone databases will send FAN events when the database restarts.
For active connections, when a machine or database instance becomes unavailable, a connection failure error will be returned by the OCI8 extension function currently being called. On a subsequent PHP script re-connect, a connection to a surviving database instance will be established. The OCI8 extension also transparently cleans up any idle connections affected by a database machine or instance failure so PHP connect calls will establish a fresh connection without the script being aware of any service disruption.
When oci8.events is On, it is suggested to set oci8.ping_interval to -1 to disable pinging, since enabling FAN events provide pro-active connection management of idle connections made invalid by a service disruption.
To enable FAN support in PHP, build PHP with Oracle 10gR2 or 11g libraries and then follow these steps:
-
As a privileged database administrator, use a program like
SQL*Plus to enable the database service to post FAN events, for
example:
SQL> execute dbms_service.modify_service( SERVICE_NAME => 'sales', AQ_HA_NOTIFICATIONS => TRUE); -
Edit php.ini and add
oci8.events = On - If the application does not already handle OCI8 error conditions, modify it to detect failures and take appropriate action. This may include re-connecting and re-executing statements.
- Run the application, connecting to an Oracle 10gR2 or 11g database.
Supported Datatypes
| Type | Mapping |
|---|---|
SQLT_NTY |
Maps a native collection type from a PHP collection object, such as those created by oci_new_collection(). |
SQLT_BFILEE |
Maps a native descriptor, such as those created by oci_new_descriptor(). |
SQLT_CFILEE |
Maps a native descriptor, such as those created by oci_new_descriptor(). |
SQLT_CLOB |
Maps a native descriptor, such as those created by oci_new_descriptor(). |
SQLT_BLOB |
Maps a native descriptor, such as those created by oci_new_descriptor(). |
SQLT_RDD |
Maps a native descriptor, such as those created by oci_new_descriptor(). |
SQLT_NUM |
Converts the PHP parameter to a 'C' long type, and binds to that value. |
SQLT_RSET |
Maps a native statement handle, such as those created by oci_parse() or those retrieved from other OCI queries. |
SQLT_CHR and any other type |
Converts the PHP parameter to a string type and binds as a string. |
| Type | Mapping |
|---|---|
SQLT_RSET |
Creates an oci statement resource to represent the cursor. |
SQLT_RDD |
Creates a ROWID object. |
SQLT_BLOB |
Creates a LOB object. |
SQLT_CLOB |
Creates a LOB object. |
SQLT_BFILE |
Creates a LOB object. |
SQLT_LNG |
Bound as SQLT_CHR, returned as a string |
SQLT_LBI |
Bound as SQLT_BIN, returned as a string |
| Any other type | Bound as SQLT_CHR, returned as a string |
OCI8 Funkcje
OCI-Collection::append
(PHP 5, PECL OCI8 >= 1.1.0)
OCI-Collection::append — Appends element to the collection
Parametry
-
value -
The value to be added to the collection. Can be a string or a number.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
OCI-Collection::assign
(PHP 5, PECL OCI8 >= 1.1.0)
OCI-Collection::assign — Assigns a value to the collection from another existing collection
Opis
$from
)Assigns a value to the collection from another, previously created collection. Both collections must be created with oci_new_collection() prior to using them.
Parametry
-
from -
An instance of OCI-Collection.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
OCI-Collection::assignElem
(PHP 5, PECL OCI8 >= 1.1.0)
OCI-Collection::assignElem — Assigns a value to the element of the collection
Opis
Assigns a value to the element with index index.
Parametry
-
index -
The element index. First index is 1.
-
value -
Can be a string or a number.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
OCI-Collection::free
(PHP 5, PECL OCI8 >= 1.1.0)
OCI-Collection::free — Frees the resources associated with the collection object
Opis
Frees the resources associated with the collection object.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
OCI-Collection::getElem
(PHP 5, PECL OCI8 >= 1.1.0)
OCI-Collection::getElem — Returns value of the element
Opis
Returns element's value with the index index (1-based).
Parametry
-
index -
The element index. First index is 1.
Zwracane wartości
Returns FALSE if such element doesn't exist; NULL if element is NULL;
string if element is column of a string datatype or number if element is
numeric field.
OCI-Collection::max
(PHP 5, PECL OCI8 >= 1.1.0)
OCI-Collection::max — Returns the maximum number of elements in the collection
Opis
Returns the maximum number of elements in the collection.
Zwracane wartości
Returns the maximum number as an integer, or FALSE on errors.
If the returned value is 0, then the number of elements is not limited.
OCI-Collection::size
(PHP 5, PECL OCI8 >= 1.1.0)
OCI-Collection::size — Returns size of the collection
Opis
Returns the size of the collection.
Zwracane wartości
Returns the number of elements in the collection or FALSE on error.
OCI-Collection::trim
(PHP 5, PECL OCI8 >= 1.1.0)
OCI-Collection::trim — Trims elements from the end of the collection
Opis
$num
)
Trims num of elements from the end of the
collection.
Parametry
-
num -
The number of elements to be trimmed.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
OCI-Lob::append
(PHP 5, PECL OCI8 >= 1.1.0)
OCI-Lob::append — Appends data from the large object to another large object
Opis
$lob_from
)Appends data from the large object to the end of another large object.
Writing to the large object with this method will fail if buffering was previously enabled. You must disable buffering before appending. You may need to flush buffers with OCI-Lob::flush before disabling buffering.
Parametry
-
lob_from -
The copied LOB.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
OCI-Lob::close
(PHP 5, PECL OCI8 >= 1.1.0)
OCI-Lob::close — Closes LOB descriptor
Opis
Closes descriptor of LOB or FILE. This function should be used only with OCI-Lob::writeTemporary.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
OCI-Lob::eof
(PHP 5, PECL OCI8 >= 1.1.0)
OCI-Lob::eof — Tests for end-of-file on a large object's descriptor
Opis
Tells whether the internal pointer of large object is at the end of LOB.
Zwracane wartości
Returns TRUE if internal pointer of large object is at the end of LOB.
Otherwise returns FALSE.
OCI-Lob::erase
(PHP 5, PECL OCI8 >= 1.1.0)
OCI-Lob::erase — Erases a specified portion of the internal LOB data
Opis
$offset
[, int $length
]] )
Erases a specified portion of the internal LOB data starting at a
specified offset. If called without parameters, it
erases all LOB data.
For BLOBs, erasing means that the existing LOB value is overwritten with zero-bytes. For CLOBs, the existing LOB value is overwritten with spaces.
Parametry
-
offset -
-
length -
Zwracane wartości
Returns the actual number of characters/bytes erased lub FALSE w przypadku niepowodzenia.
OCI-Lob::export
(PHP 5, PECL OCI8 >= 1.1.0)
OCI-Lob::export — Exports LOB's contents to a file
Opis
$filename
[, int $start
[, int $length
]] )Exports LOB contents to a file.
Parametry
-
filename -
Path to the file.
-
start -
Indicates from where to start exporting.
-
length -
Indicates the length of data to be exported.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
OCI-Lob::flush
(PHP 5, PECL OCI8 >= 1.1.0)
OCI-Lob::flush — Flushes/writes buffer of the LOB to the server
Opis
$flag
] )OCI-Lob::flush() actually writes data to the server.
Parametry
-
flag -
By default, resources are not freed, but using flag
OCI_LOB_BUFFER_FREEyou can do it explicitly. Be sure you know what you're doing - next read/write operation to the same part of LOB will involve a round-trip to the server and initialize new buffer resources. It is recommended to useOCI_LOB_BUFFER_FREEflag only when you are not going to work with the LOB anymore.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Returns FALSE if buffering was not enabled or an error occurred.
OCI-Lob::free
(PHP 5, PECL OCI8 >= 1.1.0)
OCI-Lob::free — Frees resources associated with the LOB descriptor
Opis
Frees resources associated with the descriptor, previously allocated with oci_new_descriptor().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
OCI-Lob::getBuffering
(PHP 5, PECL OCI8 >= 1.1.0)
OCI-Lob::getBuffering — Returns current state of buffering for the large object
Opis
Tells whether the buffering for the large object is on or off.
Zwracane wartości
Returns FALSE if buffering for the large object is off and TRUE if
buffering is used.
OCI-Lob::import
(PHP 5, PECL OCI8 >= 1.1.0)
OCI-Lob::import — Imports file data to the LOB
Opis
$filename
)
Writes data from the filename in to the current
position of large object.
Parametry
-
filename -
Path to the file.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
OCI-Lob::load
(PHP 5, PECL OCI8 >= 1.1.0)
OCI-Lob::load — Returns large object's contents
Opis
Returns large object's contents. As script execution is terminated when the memory_limit is reached, ensure that the LOB does not exceed this limit. In most cases it's recommended to use OCI-Lob::read instead.
Zwracane wartości
Returns the contents of the object, or FALSE on errors.
OCI-Lob::read
(PHP 5, PECL OCI8 >= 1.1.0)
OCI-Lob::read — Reads part of the large object
Opis
$length
)
Reads length bytes from the current position of
LOB's internal pointer.
Reading stops when length bytes have been read or
end of the large object is reached. Internal pointer of the large object
will be shifted on the amount of bytes read.
Parametry
-
length -
The length of data to read, in bytes.
Zwracane wartości
Returns the contents as a string, lub FALSE w przypadku niepowodzenia.
OCI-Lob::rewind
(PHP 5, PECL OCI8 >= 1.1.0)
OCI-Lob::rewind — Moves the internal pointer to the beginning of the large object
Opis
Sets the internal pointer to the beginning of the large object.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
OCI-Lob::save
(PHP 5, PECL OCI8 >= 1.1.0)
OCI-Lob::save — Saves data to the large object
Opis
$data
[, int $offset
] )
Saves data to the large object.
Parametry
-
data -
The data to be saved.
-
offset -
Can be used to indicate offset from the beginning of the large object.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Opis
Ta funkcja jest aliasem dla: OCI-Lob::import().
OCI-Lob::seek
(PHP 5, PECL OCI8 >= 1.1.0)
OCI-Lob::seek — Sets the internal pointer of the large object
Opis
$offset
[, int $whence = OCI_SEEK_SET
] )Sets the internal pointer of the large object.
Parametry
-
offset -
Indicates the amount of bytes, on which internal pointer should be moved from the position, pointed by
whence. -
whence -
May be one of:
-
OCI_SEEK_SET- sets the position equal tooffset -
OCI_SEEK_CUR- addsoffsetbytes to the current position -
OCI_SEEK_END- addsoffsetbytes to the end of large object (use negative value to move to a position before the end of large object)
-
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
OCI-Lob::setBuffering
(PHP 5, PECL OCI8 >= 1.1.0)
OCI-Lob::setBuffering — Changes current state of buffering for the large object
Opis
$on_off
)
Sets the buffering for the large object, depending on the value of the
on_off parameter.
Use of this function may provide performance improvements by buffering small reads and writes of LOBs by reducing the number of network round-trips and LOB versions. OCI-Lob::flush() should be used to flush buffers, when you have finished working with the large object.
Parametry
-
on_off -
TRUEfor on andFALSEfor off.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu. Repeated calls to this method with the same flag will
return TRUE.
OCI-Lob::size
(PHP 5, PECL OCI8 >= 1.1.0)
OCI-Lob::size — Returns size of large object
Opis
Gets the size of the large object.
Zwracane wartości
Returns length of large object value lub FALSE w przypadku niepowodzenia.
Empty objects have zero length.
OCI-Lob::tell
(PHP 5, PECL OCI8 >= 1.1.0)
OCI-Lob::tell — Returns the current position of internal pointer of large object
Opis
Gets the current position of a LOB's internal pointer.
Zwracane wartości
Returns current position of a LOB's internal pointer or FALSE if an
error occurred.
OCI-Lob::truncate
(PHP 5, PECL OCI8 >= 1.1.0)
OCI-Lob::truncate — Truncates large object
Opis
$length = 0
] )Truncates the LOB.
Parametry
-
length -
If provided, this method will truncate the LOB to
lengthbytes. Otherwise, it will completely purge the LOB.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
OCI-Lob::write
(PHP 5, PECL OCI8 >= 1.1.0)
OCI-Lob::write — Writes data to the large object
Opis
$data
[, int $length
] )
Writes data from the parameter data into the
current position of LOB's internal pointer.
Parametry
-
data -
The data to write in the LOB.
-
length -
If this parameter is given, writing will stop after
lengthbytes have been written or the end ofdatais reached, whichever comes first.
Zwracane wartości
Returns the number of bytes written lub FALSE w przypadku niepowodzenia.
OCI-Lob::writeTemporary
(PHP 5, PECL OCI8 >= 1.1.0)
OCI-Lob::writeTemporary — Writes a temporary large object
Opis
$data
[, int $lob_type = OCI_TEMP_CLOB
] )
Creates a temporary large object and writes data
to it.
You should use OCI-Lob::close when you are done with this object.
Parametry
-
data -
The data to write.
-
lob_type -
Can be one of the following:
-
OCI_TEMP_BLOBis used to create temporary BLOBs -
OCI_TEMP_CLOBis used to create temporary CLOBs
-
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Opis
Ta funkcja jest aliasem dla: OCI-Lob::export().
oci_bind_array_by_name
(PHP 5 >= 5.1.2, PECL OCI8 >= 1.2.0)
oci_bind_array_by_name — Binds a PHP array to an Oracle PL/SQL array parameter
Opis
$statement
, string $name
, array &$var_array
, int $max_table_length
[, int $max_item_length = -1
[, int $type = SQLT_AFC
]] )
Binds the PHP array var_array to the Oracle
placeholder name, which points to an Oracle PL/SQL
array. Whether it will be used for input or output will be determined at
run-time.
Parametry
-
statement -
A valid OCI statement identifier.
-
name -
The Oracle placeholder.
-
var_array -
An array.
-
max_table_length -
Sets the maximum length both for incoming and result arrays.
-
max_item_length -
Sets maximum length for array items. If not specified or equals to -1, oci_bind_array_by_name() will find the longest element in the incoming array and will use it as the maximum length.
-
type -
Should be used to set the type of PL/SQL array items. See list of available types below:
-
SQLT_NUM- for arrays of NUMBER. -
SQLT_INT- for arrays of INTEGER (Note: INTEGER it is actually a synonym for NUMBER(38), butSQLT_NUMtype won't work in this case even though they are synonyms). -
SQLT_FLT- for arrays of FLOAT. -
SQLT_AFC- for arrays of CHAR. -
SQLT_CHR- for arrays of VARCHAR2. -
SQLT_VCS- for arrays of VARCHAR. -
SQLT_AVC- for arrays of CHARZ. -
SQLT_STR- for arrays of STRING. -
SQLT_LVC- for arrays of LONG VARCHAR. -
SQLT_ODT- for arrays of DATE.
-
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 oci_bind_array_by_name() example
<?php
$c = oci_connect("scott", "tiger");
$create = "CREATE TABLE bind_example(name VARCHAR(20))";
$statement = oci_parse($c, $create);
oci_execute($statement);
$create_pkg = "
CREATE OR REPLACE PACKAGE ARRAYBINDPKG1 AS
TYPE ARRTYPE IS TABLE OF VARCHAR(20) INDEX BY BINARY_INTEGER;
PROCEDURE iobind(c1 IN OUT ARRTYPE);
END ARRAYBINDPKG1;";
$statement = oci_parse($c, $create_pkg);
oci_execute($statement);
$create_pkg_body = "
CREATE OR REPLACE PACKAGE BODY ARRAYBINDPKG1 AS
CURSOR CUR IS SELECT name FROM bind_example;
PROCEDURE iobind(c1 IN OUT ARRTYPE) IS
BEGIN
FOR i IN 1..5 LOOP
INSERT INTO bind_example VALUES (c1(i));
END LOOP;
IF NOT CUR%ISOPEN THEN
OPEN CUR;
END IF;
FOR i IN REVERSE 1..5 LOOP
FETCH CUR INTO c1(i);
IF CUR%NOTFOUND THEN
CLOSE CUR;
EXIT;
END IF;
END LOOP;
END iobind;
END ARRAYBINDPKG1;";
$statement = oci_parse($c, $create_pkg_body);
oci_execute($statement);
$statement = oci_parse($c, "BEGIN ARRAYBINDPKG1.iobind(:c1); END;");
$array = array("one", "two", "three", "four", "five");
oci_bind_array_by_name($statement, ":c1", $array, 5, -1, SQLT_CHR);
oci_execute($statement);
var_dump($array);
?>
oci_bind_by_name
(PHP 5, PECL OCI8 >= 1.1.0)
oci_bind_by_name — Binds a PHP variable to an Oracle placeholder
Opis
$statement
, string $bv_name
, mixed &$variable
[, int $maxlength = -1
[, int $type = SQLT_CHR
]] )
Binds a PHP variable variable to the Oracle
bind variable placeholder bv_name. Binding
is important for Oracle database performance and also as a way to
avoid SQL Injection security issues.
Binding allows the database to reuse the statement context and caches from previous executions of the statement, even if another user or process originally executed it. Binding reduces SQL Injection concerns because the data associated with a bind variable is never treated as part of the SQL statement. It does not need quoting or escaping.
PHP variables that have been bound can be changed and the statement re-executed without needing to re-parse the statement or re-bind.
In Oracle, bind variables are commonly divided into IN binds for values that are passed into the database, and OUT binds for values that are returned to PHP. A bind variable may be both IN and OUT. Whether a bind variable will be used for input or output is determined at run-time.
You must specify maxlength when using
an OUT bind so that PHP allocates enough memory
to hold the returned value.
For IN binds it is recommended to set
the maxlength length if the statement is
re-executed multiple times with different values for the PHP
variable. Otherwise Oracle may truncate data to the length of the
initial PHP variable value. If you don't know what the maximum
length will be, then re-call oci_bind_by_name()
with the current data size prior to
each oci_execute() call. Binding an
unnecessarily large length will have an impact on process memory
in the database.
A bind call tells Oracle which memory address to read data from. For IN binds that address needs to contain valid data when oci_execute() is called. This means that the variable bound must remain in scope until execution. If it doesn't, unexpected results or errors such as "ORA-01460: unimplemented or unreasonable conversion requested" may occur. For OUT binds one symptom is no value being set in the PHP variable.
For a statement that is repeatedly executed, binding values that never change may reduce the ability of the Oracle optimizer to choose the best statement execution plan. Long running statements that are rarely re-executed may not benefit from binding. However in both cases, binding might be safer than joining strings into a SQL statement, as this can be a security risk if unfiltered user text is concatenated.
Parametry
-
statement -
A valid OCI8 statement identifer.
-
bv_name -
The colon-prefixed bind variable placeholder used in the statement. The colon is optional in
bv_name. Oracle does not use question marks for placeholders. -
variable -
The PHP variable to be associated with
bv_name -
maxlength -
Sets the maximum length for the data. If you set it to -1, this function will use the current length of
variableto set the maximum length. In this case thevariablemust exist and contain data when oci_bind_by_name() is called. -
type -
The datatype that Oracle will treat the data as. The default
typeused isSQLT_CHR. Oracle will convert the data between this type and the database column (or PL/SQL variable type), when possible.If you need to bind an abstract datatype (LOB/ROWID/BFILE) you need to allocate it first using the oci_new_descriptor() function. The
lengthis not used for abstract datatypes and should be set to -1.Possible values for
typeare:-
SQLT_BFILEEorOCI_B_BFILE- for BFILEs; -
SQLT_CFILEEorOCI_B_CFILEE- for CFILEs; -
SQLT_CLOBorOCI_B_CLOB- for CLOBs; -
SQLT_BLOBorOCI_B_BLOB- for BLOBs; -
SQLT_RDDorOCI_B_ROWID- for ROWIDs; -
SQLT_NTYorOCI_B_NTY- for named datatypes; -
SQLT_INTorOCI_B_INT- for integers; -
SQLT_CHR- for VARCHARs; -
SQLT_BINorOCI_B_BIN- for RAW columns; -
SQLT_LNG- for LONG columns; -
SQLT_LBI- for LONG RAW columns; -
SQLT_RSET- for cursors created with oci_new_cursor().
-
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Inserting data with oci_bind_by_name()
<?php
// Create the table with:
// CREATE TABLE mytab (id NUMBER, text VARCHAR2(40));
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}
$stid = oci_parse($conn,"INSERT INTO mytab (id, text) VALUES(:id_bv, :text_bv)");
$id = 1;
$text = "Data to insert ";
oci_bind_by_name($stid, ":id_bv", $id);
oci_bind_by_name($stid, ":text_bv", $text);
oci_execute($stid);
// Table now contains: 1, 'Data to insert '
?>
Przykład #2 Binding once for multiple executions
<?php
// Create the table with:
// CREATE TABLE mytab (id NUMBER);
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}
$a = array(1,3,5,7,11); // data to insert
$stid = oci_parse($conn, 'INSERT INTO mytab (id) VALUES (:bv)');
oci_bind_by_name($stid, ':bv', $v, 20);
foreach ($a as $v) {
$r = oci_execute($stid, OCI_DEFAULT); // don't auto commit
}
oci_commit($conn); // commit everything at once
// Table contains five rows: 1, 3, 5, 7, 11
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #3 Binding with a foreach() loop
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}
$sql = 'SELECT * FROM departments WHERE department_name = :dname AND location_id = :loc';
$stid = oci_parse($conn, $sql);
$ba = array(':dname' => 'IT Support', ':loc' => 1700);
foreach ($ba as $key => $val) {
// oci_bind_by_name($stid, $key, $val) does not work
// because it binds each placeholder to the same location: $val
// instead use the actual location of the data: $ba[$key]
oci_bind_by_name($stid, $key, $ba[$key]);
}
oci_execute($stid);
$row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS);
foreach ($row as $item) {
print $item."<br>\n";
}
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #4 Binding in a WHERE clause
<?php
$conn = oci_connect("hr", "hrpwd", "localhost/XE");
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}
$sql = 'SELECT last_name FROM employees WHERE employee_id = :eidbv';
$stid = oci_parse($conn, $sql);
$myeid = 101;
oci_bind_by_name($stid, ':eidbv', $myeid);
oci_execute($stid);
$row = oci_fetch_array($stid, OCI_ASSOC);
echo $row['LAST_NAME'] ."<br>\n";
// Output is
// Kochhar
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #5 Binding with a LIKE clause
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}
// Find all cities that begin with 'South'
$stid = oci_parse($conn, "SELECT city FROM locations WHERE city LIKE :bv");
$city = 'South%'; // '%' is a wildcard in SQL
oci_bind_by_name($stid, ":bv", $city);
oci_execute($stid);
oci_fetch_all($stid, $res);
foreach ($res['CITY'] as $c) {
print $c . "<br>\n";
}
// Output is
// South Brunswick
// South San Francisco
// Southlake
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #6 Binding with REGEXP_LIKE
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}
// Find all cities that contain 'ing'
$stid = oci_parse($conn, "SELECT city FROM locations WHERE REGEXP_LIKE(city, :bv)");
$city = '.*ing.*';
oci_bind_by_name($stid, ":bv", $city);
oci_execute($stid);
oci_fetch_all($stid, $res);
foreach ($res['CITY'] as $c) {
print $c . "<br>\n";
}
// Output is
// Beijing
// Singapore
oci_free_statement($stid);
oci_close($conn);
?>
For a small, fixed number of IN clause conditions, use individual bind variables. Values unknown at run time can be set to NULL. This allows a single statement to be used by all application users, maximizing Oracle DB cache efficiency.
Przykład #7 Binding Multiple Values in an IN Clause
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}
$sql = 'SELECT last_name FROM employees WHERE employee_id in (:e1, :e2, :e3)';
$stid = oci_parse($conn, $sql);
$mye1 = 103;
$mye2 = 104;
$mye3 = NULL; // pretend we were not given this value
oci_bind_by_name($stid, ':e1', $mye1);
oci_bind_by_name($stid, ':e2', $mye2);
oci_bind_by_name($stid, ':e3', $mye3);
oci_execute($stid);
oci_fetch_all($stid, $res);
foreach ($res['LAST_NAME'] as $name) {
print $name ."<br>\n";
}
// Output is
// Ernst
// Hunold
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #8 Binding a ROWID returned by a query
<?php
// Create the table with:
// CREATE TABLE mytab (id NUMBER, salary NUMBER, name VARCHAR2(40));
// INSERT INTO mytab (id, salary, name) VALUES (1, 100, 'Chris');
// COMMIT;
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}
$stid = oci_parse($conn, 'SELECT ROWID, name FROM mytab WHERE id = :id_bv FOR UPDATE');
$id = 1;
oci_bind_by_name($stid, ':id_bv', $id);
oci_execute($stid);
$row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS);
$rid = $row['ROWID'];
$name = $row['NAME'];
// Change name to upper case & save the changes
$name = strtoupper($name);
$stid = oci_parse($conn, 'UPDATE mytab SET name = :n_bv WHERE ROWID = :r_bv');
oci_bind_by_name($stid, ':n_bv', $name);
oci_bind_by_name($stid, ':r_bv', $rid, -1, OCI_B_ROWID);
oci_execute($stid);
// The table now contains 1, 100, CHRIS
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #9 Binding a ROWID on INSERT
<?php
// This example inserts an id & name, and then updates the salary
// Create the table with:
// CREATE TABLE mytab (id NUMBER, salary NUMBER, name VARCHAR2(40));
//
// Based on original ROWID example by thies at thieso dot net (980221)
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}
$sql = "INSERT INTO mytab (id, name) VALUES(:id_bv, :name_bv)
RETURNING ROWID INTO :rid";
$ins_stid = oci_parse($conn, $sql);
$rowid = oci_new_descriptor($conn, OCI_D_ROWID);
oci_bind_by_name($ins_stid, ":id_bv", $id, 10);
oci_bind_by_name($ins_stid, ":name_bv", $name, 32);
oci_bind_by_name($ins_stid, ":rid", $rowid, -1, OCI_B_ROWID);
$sql = "UPDATE mytab SET salary = :salary WHERE ROWID = :rid";
$upd_stid = oci_parse($conn, $sql);
oci_bind_by_name($upd_stid, ":rid", $rowid, -1, OCI_B_ROWID);
oci_bind_by_name($upd_stid, ":salary", $salary, 32);
// ids and names to insert
$data = array(1111 => "Larry",
2222 => "Bill",
3333 => "Jim");
// Salary of each person
$salary = 10000;
// Insert and immediately update each row
foreach ($data as $id => $name) {
oci_execute($ins_stid);
oci_execute($upd_stid);
}
$rowid->free();
oci_free_statement($upd_stid);
oci_free_statement($ins_stid);
// Show the new rows
$stid = oci_parse($conn, "SELECT * FROM mytab");
oci_execute($stid);
while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
var_dump($row);
}
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #10 Binding for a PL/SQL stored function
<?php
// Before running the PHP program, create a stored function in
// SQL*Plus or SQL Developer:
//
// CREATE OR REPLACE FUNCTION myfunc(p IN NUMBER) RETURN NUMBER AS
// BEGIN
// RETURN p * 3;
// END;
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message']), E_USER_ERROR);
}
$p = 8;
$stid = oci_parse($conn, 'begin :r := myfunc(:p); end;');
oci_bind_by_name($stid, ':p', $p);
// The return value is an OUT bind. The default type will be a string
// type so binding a length 40 means that at most 40 digits will be
// returned.
oci_bind_by_name($stid, ':r', $r, 40);
oci_execute($stid);
print "$r\n"; // prints 24
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #11 Binding parameters for a PL/SQL stored procedure
<?php
// Before running the PHP program, create a stored procedure in
// SQL*Plus or SQL Developer:
//
// CREATE OR REPLACE PROCEDURE myproc(p1 IN NUMBER, p2 OUT NUMBER) AS
// BEGIN
// p2 := p1 * 2;
// END;
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message']), E_USER_ERROR);
}
$p1 = 8;
$stid = oci_parse($conn, 'begin myproc(:p1, :p2); end;');
oci_bind_by_name($stid, ':p1', $p1);
// The second procedure parameter is an OUT bind. The default type
// will be a string type so binding a length 40 means that at most 40
// digits will be returned.
oci_bind_by_name($stid, ':p2', $p2, 40);
oci_execute($stid);
print "$p2\n"; // prints 16
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #12 Binding a CLOB column
<?php
// Before running, create the table:
// CREATE TABLE mytab (mykey NUMBER, myclob CLOB);
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message']), E_USER_ERROR);
}
$mykey = 12343; // arbitrary key for this example;
$sql = "INSERT INTO mytab (mykey, myclob)
VALUES (:mykey, EMPTY_CLOB())
RETURNING myclob INTO :myclob";
$stid = oci_parse($conn, $sql);
$clob = oci_new_descriptor($conn, OCI_D_LOB);
oci_bind_by_name($stid, ":mykey", $mykey, 5);
oci_bind_by_name($stid, ":myclob", $clob, -1, OCI_B_CLOB);
oci_execute($stid, OCI_DEFAULT);
$clob->save("A very long string");
oci_commit($conn);
// Fetching CLOB data
$query = 'SELECT myclob FROM mytab WHERE mykey = :mykey';
$stid = oci_parse ($conn, $query);
oci_bind_by_name($stid, ":mykey", $mykey, 5);
oci_execute($stid);
print '<table border="1">';
while ($row = oci_fetch_array($stid, OCI_ASSOC)) {
$result = $row['MYCLOB']->load();
print '<tr><td>'.$result.'</td></tr>';
}
print '</table>';
?>
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Notatki
Do not use magic_quotes_gpc or addslashes() and oci_bind_by_name() simultaneously as no quoting is needed. Any magically applied quotes will be written into your database because oci_bind_by_name() inserts data verbatim and does not remove quotes or escape characters.
Informacja:
If you bind a string to a CHAR column in a WHERE clause, remember that Oracle uses blank-padded comparison semantics for CHAR columns. Your PHP variable should be blank padded to the same width as the column for the WHERE clause to succeed.
Informacja:
The PHP
variableargument is a reference. Some forms of loops do not work as expected:<?php
foreach ($myarray as $key => $value) {
oci_bind_by_name($stid, $key, $value);
}
?>This binds each key to the location of $value, so all bound variables end up pointing to the last loop iteration's value. Instead use the following:
<?php
foreach ($myarray as $key => $value) {
oci_bind_by_name($stid, $key, $myarray[$key]);
}
?>
Informacja:
In PHP versions before 5.0.0 you must use ocibindbyname() instead. The old function name can still be used in current versions, however it is deprecated and not recommended.
Zobacz też:
- oci_bind_array_by_name() - Binds a PHP array to an Oracle PL/SQL array parameter
- oci_parse() - Prepares an Oracle statement for execution
oci_cancel
(PHP 5, PECL OCI8 >= 1.1.0)
oci_cancel — Anuluje odczytywanie z kursora
Opis
$instrukcja
)Unieważnia kursor uwalniając wszystkie powiązane z nim zasoby i końcy mozliwość odczytywania z niego.
Parametry
-
instrukcja -
Instrukcja OCI.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
oci_client_version
(PHP 5.3.7, PECL OCI8 >= 1.4.6)
oci_client_version — Returns the Oracle client library version
Opis
Returns a string containing the version number of the Oracle C client library that PHP is linked with.
Parametry
None
Zwracane wartości
Returns the version number as a string.
Przykłady
Przykład #1 oci_client_version() example
<?php
echo "Client Version: " . oci_client_version(); // Client version: 11.2.0.2
?>
Notatki
Informacja:
Oracle libraries before 10gR2 do not have the underlying functionality to get the client library version number. The string "Unknown" will be returned in this case.
oci_close
(PHP 5, PECL OCI8 >= 1.1.0)
oci_close — Closes an Oracle connection
Opis
$connection
)
Unsets connection. The underlying database
connection is closed if no other resources are using it and if it
was created with oci_connect()
or oci_new_connect().
It is recommended to close connections that are no longer needed because this makes database resources available for other users.
Parametry
-
connection -
An Oracle connection identifier returned by oci_connect(), oci_pconnect(), or oci_new_connect().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Closing a connection
Resources associated with a connection should be closed to ensure the underlying database connection is properly terminated and the database resources are released.
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$stid = oci_parse($conn, 'SELECT * FROM departments');
$r = oci_execute($stid);
oci_fetch_all($stid, $res);
var_dump($res);
// Free the statement identifier when closing the connection
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #2 Database connections are not closed until all references are closed
The internal refcount of a connection identifier must be zero before the underlying connection to the database is closed.
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$stid = oci_parse($conn, 'SELECT * FROM departments'); // this increases the refcount on $conn
oci_execute($stid);
oci_fetch_all($stid, $res);
var_dump($res);
oci_close($conn);
// $conn is no long usable in the script but the underlying database
// connection is still held open until $stid is freed.
var_dump($conn); // prints NULL
// While PHP sleeps, querying the Oracle V$SESSION view in a
// terminal window will show that the database user is still connected.
sleep(10);
// When $stid is freed, the database connection is physically closed
oci_free_statement($stid);
// While PHP sleeps, querying the Oracle V$SESSION view in a
// terminal window will show that the database user has disconnected.
sleep(10);
?>
Przykład #3 Closing a connection opened more than once
When database credentials are reused, both connections must be closed before the underlying database connection is closed.
<?php
$conn1 = oci_connect('hr', 'welcome', 'localhost/XE');
// Using the same credentials reuses the same underlying database connection
// Any uncommitted changes done on $conn1 will be visible in $conn2
$conn2 = oci_connect('hr', 'welcome', 'localhost/XE');
// While PHP sleeps, querying the Oracle V$SESSION view in a
// terminal window will show that only one database user is connected.
sleep(10);
oci_close($conn1); // doesn't close the underlying database connection
var_dump($conn1); // prints NULL because the variable $conn1 is no longer usable
var_dump($conn2); // displays that $conn2 is still a valid connection resource
?>
Przykład #4 Connections are closed when variables go out of scope
When all variables referencing a connection go out of scope and are freed by PHP, a rollback occurs (if necessary) and the underlying connection to the database is closed.
<?php
function myfunc() {
$conn = oci_connect('hr', 'hrpwd', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$stid = oci_parse($conn, 'UPDATE mytab SET id = 100');
oci_execute($stid, OCI_NO_AUTO_COMMIT);
return "Finished";
}
$r = myfunc();
// At this point a rollback occurred and the underlying database connection was released.
print $r; // displays the function return value "Finished"
?>
Notatki
Informacja:
Variables that have a dependency on the connection identifier, such as statement identifiers returned by oci_parse(), must also be freed before the underlying database connection is closed.
Informacja:
Prior to version PHP 5.1.2 (PECL OCI8 1.1) oci_close() was a no-op. In more recent versions it correctly closes the Oracle connection. Use oci8.old_oci_close_semantics option to restore old behavior of this function.
Informacja:
The oci_close() function does not close the underlying database connections created with oci_pconnect().
Informacja:
In PHP versions before 5.0.0 you must use ocilogoff() instead. The old function name can still be used in current versions, however it is deprecated and not recommended.
Zobacz też:
- oci_connect() - Connect to an Oracle database
- oci_free_statement() - Frees all resources associated with statement or cursor
oci_commit
(PHP 5, PECL OCI8 >= 1.1.0)
oci_commit — Commits the outstanding database transaction
Opis
$connection
)
Commits the outstanding transaction for the
Oracle connection. A commit ends the
current transaction and makes permanent all changes. It releases
all locks held.
A transaction begins when the first SQL statement that changes data
is executed with oci_execute() using
the OCI_NO_AUTO_COMMIT flag. Further data
changes made by other statements become part of the same
transaction. Data changes made in a transaction are temporary
until the transaction is committed or rolled back. Other users of
the database will not see the changes until they are committed.
When inserting or updating data, using transactions is recommended for relational data consistency and for performance reasons.
Parametry
-
connection -
An Oracle connection identifier, returned by oci_connect(), oci_pconnect(), or oci_new_connect().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 oci_commit() example
<?php
// Insert into several tables, rolling back the changes if an error occurs
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
$stid = oci_parse($conn, "INSERT INTO mysalary (id, name) VALUES (1, 'Chris')");
// The OCI_NO_AUTO_COMMIT flag tells Oracle not to commit the INSERT immediately
// Use OCI_DEFAULT as the flag for PHP <= 5.3.1. The two flags are equivalent
$r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
if (!$r) {
$e = oci_error($stid);
trigger_error(htmlentities($e['message']), E_USER_ERROR);
}
$stid = oci_parse($conn, 'INSERT INTO myschedule (startday) VALUES (12)');
$r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
if (!$r) {
$e = oci_error($stid);
oci_rollback($conn); // rollback changes to both tables
trigger_error(htmlentities($e['message']), E_USER_ERROR);
}
// Commit the changes to both tables
$r = oci_commit($conn);
if (!r) {
$e = oci_error($conn);
trigger_error(htmlentities($e['message']), E_USER_ERROR);
}
?>
Notatki
Informacja:
Transactions are automatically rolled back when you close the connection, or when the script ends, whichever is soonest. You need to explicitly call oci_commit() to commit the transaction.
Any call to oci_execute() that uses
OCI_COMMIT_ON_SUCCESSmode explicitly or by default will commit any previous uncommitted transaction.Any Oracle DDL statement such as CREATE or DROP will automatically commit any uncommitted transaction.
Informacja:
In PHP versions before 5.0.0 you must use ocicommit() instead. The old function name can still be used in current versions, however it is deprecated and not recommended.
Zobacz też:
- oci_execute() - Executes a statement
- oci_rollback() - Rolls back the outstanding database transaction
oci_connect
(PHP 5, PECL OCI8 >= 1.1.0)
oci_connect — Connect to an Oracle database
Opis
$username
, string $password
[, string $connection_string
[, string $character_set
[, int $session_mode
]]] )Returns a connection identifier needed for most other OCI8 operations.
See Connection Handling for general information on connection management and connection pooling.
From PHP 5.1.2 (PECL OCI8 1.1) oci_close() can be used to close the connection.
The second and subsequent calls to oci_connect() with the same parameters will return the connection handle returned from the first call. This means that transactions in one handle are also in the other handles, because they use the same underlying database connection. If two handles need to be transactionally isolated from each other, use oci_new_connect() instead.
Parametry
-
username -
The Oracle user name.
-
password -
The password for
username. -
connection_string -
Contains the Oracle instance to connect to. It can be an » Easy Connect string, or a Connect Name from the tnsnames.ora file, or the name of a local Oracle instance.
If not specified, PHP uses environment variables such as
TWO_TASK(on Linux) orLOCAL(on Windows) andORACLE_SIDto determine the Oracle instance to connect to.To use the Easy Connect naming method, PHP must be linked with Oracle 10g or greater Client libraries. The Easy Connect string for Oracle 10g is of the form: [//]host_name[:port][/service_name]. With Oracle 11g, the syntax is: [//]host_name[:port][/service_name][:server_type][/instance_name]. Service names can be found by running the Oracle utility lsnrctl status on the database server machine.
The tnsnames.ora file can be in the Oracle Net search path, which includes $ORACLE_HOME/network/admin and /etc. Alternatively set TNS_ADMIN so that $TNS_ADMIN/tnsnames.ora is read. Make sure the web daemon has read access to the file.
-
character_set -
Determines the character set used by the Oracle Client libraries. The character set does not need to match the character set used by the database. If it doesn't match, Oracle will do its best to convert data to and from the database character set. Depending on the character sets this may not give usable results. Conversion also adds some time overhead.
If not specified, the Oracle Client libraries determine a character set from the
NLS_LANGenvironment variable.Passing this parameter can reduce connection time.
-
session_mode -
This parameter is available since version PHP 5 (PECL OCI8 1.1) and accepts the following values:
OCI_DEFAULT,OCI_SYSOPERandOCI_SYSDBA. If eitherOCI_SYSOPERorOCI_SYSDBAwere specified, this function will try to establish privileged connection using external credentials. Privileged connections are disabled by default. To enable them you need to set oci8.privileged_connect to On.PHP 5.3 (PECL OCI8 1.3.4) introduced the
OCI_CRED_EXTmode value. This tells Oracle to use External or OS authentication, which must be configured in the database. TheOCI_CRED_EXTflag can only be used with username of "/" and a empty password. oci8.privileged_connect may be On or Off.OCI_CRED_EXTmay be combined with theOCI_SYSOPERorOCI_SYSDBAmodes.OCI_CRED_EXTis not supported on Windows for security reasons.
Zwracane wartości
Returns a connection identifier or FALSE on error.
Przykłady
Przykład #1 Basic oci_connect() using Easy Connect syntax
<?php
// Connects to the XE service (i.e. database) on the "localhost" machine
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$stid = oci_parse($conn, 'SELECT * FROM employees');
oci_execute($stid);
echo "<table border='1'>\n";
while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
echo "<tr>\n";
foreach ($row as $item) {
echo " <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : " ") . "</td>\n";
}
echo "</tr>\n";
}
echo "</table>\n";
?>
Przykład #2 Basic oci_connect() using a Network Connect name
<?php
// Connects to the MYDB database described in tnsnames.ora file,
// One example tnsnames.ora entry for MYDB could be:
// MYDB =
// (DESCRIPTION =
// (ADDRESS = (PROTOCOL = TCP)(HOST = mymachine.oracle.com)(PORT = 1521))
// (CONNECT_DATA =
// (SERVER = DEDICATED)
// (SERVICE_NAME = XE)
// )
// )
$conn = oci_connect('hr', 'welcome', 'MYDB');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$stid = oci_parse($conn, 'SELECT * FROM employees');
oci_execute($stid);
echo "<table border='1'>\n";
while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
echo "<tr>\n";
foreach ($row as $item) {
echo " <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : " ") . "</td>\n";
}
echo "</tr>\n";
}
echo "</table>\n";
?>
Przykład #3 oci_connect() with an explicit character set
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE', 'AL32UTF8');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$stid = oci_parse($conn, 'SELECT * FROM employees');
oci_execute($stid);
echo "<table border='1'>\n";
while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
echo "<tr>\n";
foreach ($row as $item) {
echo " <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : " ") . "</td>\n";
}
echo "</tr>\n";
}
echo "</table>\n";
?>
Przykład #4 Using multiple calls to oci_connect()
<?php
$c1 = oci_connect("hr", "welcome", 'localhost/XE');
$c2 = oci_connect("hr", "welcome", 'localhost/XE');
// Both $c1 and $c2 show the same PHP resource id meaning they use the
// same underlying database connection
echo "c1 is $c1<br>\n";
echo "c2 is $c2<br>\n";
function create_table($conn)
{
$stmt = oci_parse($conn, "create table hallo (test varchar2(64))");
oci_execute($stmt);
echo "Created table<br>\n";
}
function drop_table($conn)
{
$stmt = oci_parse($conn, "drop table hallo");
oci_execute($stmt);
echo "Dropped table<br>\n";
}
function insert_data($connname, $conn)
{
$stmt = oci_parse($conn, "insert into hallo
values(to_char(sysdate,'DD-MON-YY HH24:MI:SS'))");
oci_execute($stmt, OCI_DEFAULT);
echo "$connname inserted row without committing<br>\n";
}
function rollback($connname, $conn)
{
oci_rollback($conn);
echo "$connname rollback<br>\n";
}
function select_data($connname, $conn)
{
$stmt = oci_parse($conn, "select * from hallo");
oci_execute($stmt, OCI_DEFAULT);
echo "$connname ----selecting<br>\n";
while (oci_fetch($stmt)) {
echo " " . oci_result($stmt, "TEST") . "<br>\n";
}
echo "$connname ----done<br>\n";
}
create_table($c1);
insert_data('c1', $c1); // Insert a row using c1
sleep(2); // sleep to show a different timestamp for the 2nd row
insert_data('c2', $c2); // Insert a row using c2
select_data('c1', $c1); // Results of both inserts are returned
select_data('c2', $c2); // Results of both inserts are returned
rollback('c1', $c1); // Rollback using c1
select_data('c1', $c1); // Both inserts have been rolled back
select_data('c2', $c2);
drop_table($c1);
// Closing one of the connections makes the PHP variable unusable, but
// the other could be used
oci_close($c1);
echo "c1 is $c1<br>\n";
echo "c2 is $c2<br>\n";
// Output is:
// c1 is Resource id #5
// c2 is Resource id #5
// Created table
// c1 inserted row without committing
// c2 inserted row without committing
// c1 ----selecting
// 09-DEC-09 12:14:43
// 09-DEC-09 12:14:45
// c1 ----done
// c2 ----selecting
// 09-DEC-09 12:14:43
// 09-DEC-09 12:14:45
// c2 ----done
// c1 rollback
// c1 ----selecting
// c1 ----done
// c2 ----selecting
// c2 ----done
// Dropped table
// c1 is
// c2 is Resource id #5
?>
Notatki
Informacja:
An incorrectly installed or configured OCI8 extension will often manifest itself as a connection problem or error. See Installing/Configuring for troubleshooting information.
Informacja:
In PHP versions before 5.0.0 use ocilogon() instead. The old function name can still be used in current versions, however it is deprecated and not recommended.
Zobacz też:
- oci_pconnect() - Connect to an Oracle database using a persistent connection
- oci_new_connect() - Connect to the Oracle server using a unique connection
- oci_close() - Closes an Oracle connection
oci_define_by_name
(PHP 5, PECL OCI8 >= 1.1.0)
oci_define_by_name — Associates a PHP variable with a column for query fetches
Opis
$statement
, string $column_name
, mixed &$variable
[, int $type = SQLT_CHR
] )Associates a PHP variable with a column for query fetches using oci_fetch().
The oci_define_by_name() call must occur before executing oci_execute().
Parametry
-
statement -
A valid OCI8 statement identifier created by oci_parse() and executed by oci_execute(), or a REF CURSOR statement identifier.
-
column_name -
The column name used in the query.
Use uppercase for Oracle's default, non-case sensitive column names. Use the exact column name case for case-sensitive column names.
-
variable -
The PHP variable that will contain the returned column value.
-
type -
The data type to be returned. Generally not needed. Note that Oracle-style data conversions are not performed. For example, SQLT_INT will be ignored and the returned data type will still be SQLT_CHR.
You can optionally use oci_new_descriptor() to allocate LOB/ROWID/BFILE descriptors.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 oci_define_by_name() example
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
$stid = oci_parse($conn, $sql);
// The defines MUST be done before executing
oci_define_by_name($stid, 'LOCATION_ID', $locid);
oci_define_by_name($stid, 'CITY', $city);
oci_execute($stid);
// Each fetch populates the previously defined variables with the next row's data
while (oci_fetch($stid)) {
echo "Location id $locid is $city<br>\n";
}
// Displays:
// Location id 1000 is Roma
// Location id 1100 is Venice
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #2 oci_define_by_name() with case sensitive column names
<?php
/*
Before running, create the table with a case sensitive column name:
CREATE TABLE mytab (id NUMBER, "MyDescription" VARCHAR2(30));
INSERT INTO mytab (id, "MyDescription") values (1, 'Iced Coffee');
COMMIT;
*/
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$stid = oci_parse($conn, 'SELECT * FROM mytab');
// Use uppercase for non case-sensitive column names
oci_define_by_name($stid, 'ID', $id);
// Use the exact case for case-sensitive column names
oci_define_by_name($stid, 'MyDescription', $mydesc);
oci_execute($stid);
while (oci_fetch($stid)) {
echo "id $id is $mydesc<br>\n";
}
// Displays:
// id 1 is Iced Coffee
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #3 oci_define_by_name() with LOB columns
<?php
/*
Before running, create the table:
CREATE TABLE mytab (id NUMBER, fruit CLOB);
INSERT INTO mytab (id, fruit) values (1, 'apple');
INSERT INTO mytab (id, fruit) values (2, 'orange');
COMMIT;
*/
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$stid = oci_parse($conn, 'SELECT * FROM mytab');
// The defines MUST be done before executing
oci_define_by_name($stid, 'ID', $id);
oci_define_by_name($stid, 'FRUIT', $fruit); // $fruit will become a LOB descriptor
oci_execute($stid);
while (oci_fetch($stid)) {
echo $id . " is " . $fruit->load(100) . "<br>\n";
}
// Displays:
// 1 is apple
// 2 is orange
$fruit->free();
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #4 oci_define_by_name() with an explicit type
<?php
/*
Before running, create the table:
CREATE TABLE mytab (id NUMBER, fruit CLOB);
INSERT INTO mytab (id, fruit) values (1, 'apple');
INSERT INTO mytab (id, fruit) values (2, 'orange');
COMMIT;
*/
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$stid = oci_parse($conn, 'SELECT * FROM mytab');
// The defines MUST be done before executing
oci_define_by_name($stid, 'ID', $id);
$fruit = oci_new_descriptor($conn, OCI_D_LOB);
oci_define_by_name($stid, 'FRUIT', $fruit, OCI_D_CLOB);
oci_execute($stid);
while (oci_fetch($stid)) {
echo $id . " is " . $fruit->load(100) . "<br>\n";
}
// Displays:
// 1 is apple
// 2 is orange
$fruit->free();
oci_free_statement($stid);
oci_close($conn);
?>
Notatki
Informacja:
In PHP versions before 5.0.0 use ocidefinebyname() instead. The old function name can still be used in current versions, however it is deprecated and not recommended.
Zobacz też:
- oci_fetch() - Fetches the next row from a query into internal buffers
- oci_new_descriptor() - Initializes a new empty LOB or FILE descriptor
oci_error
(PHP 5, PECL OCI8 >= 1.1.0)
oci_error — Returns the last error found
Opis
$resource
] )Returns the last error found.
The function should be called immediately after an error occurs. Errors are cleared by a successful statement.
Parametry
-
resource -
For most errors,
resourceis the resource handle that was passed to the failing function call. For connection errors with oci_connect(), oci_new_connect() or oci_pconnect() do not passresource.
Zwracane wartości
If no error is found, oci_error() returns
FALSE. Otherwise, oci_error() returns the
error information as an associative array.
| Array key | Type | Opis |
|---|---|---|
| code | integer | The Oracle error number. |
| message | string | The Oracle error text. |
| offset | integer | The byte position of an error in the SQL statement. If there was no statement, this is 0 |
| sqltext | string | The SQL statement text. If there was no statement, this is an empty string. |
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.3.0 | The offset and sqltext entries were added. |
Przykłady
Przykład #1 Displaying the Oracle error message after a connection error
<?php
$conn = oci_connect("hr", "welcome", "localhost/XE");
if (!$conn) {
$e = oci_error(); // For oci_connect errors do not pass a handle
trigger_error(htmlentities($e['message']), E_USER_ERROR);
}
?>
Przykład #2 Displaying the Oracle error message after a parsing error
<?php
$stid = oci_parse($conn, "select ' from dual"); // note mismatched quote
if (!$stid) {
$e = oci_error($conn); // For oci_parse errors pass the connection handle
trigger_error(htmlentities($e['message']), E_USER_ERROR);
}
?>
Przykład #3 Displaying the Oracle error message, the problematic statement, and the position of the problem of an execution error
<?php
$stid = oci_parse($conn, "select does_not_exist from dual");
$r = oci_execute($stid);
if (!$r) {
$e = oci_error($stid); // For oci_execute errors pass the statement handle
print htmlentities($e['message']);
print "\n<pre>\n";
print htmlentities($e['sqltext']);
printf("\n%".($e['offset']+1)."s", "^");
print "\n</pre>\n";
}
?>
Notatki
Informacja:
In PHP versions before 5.0.0 you must use ocierror() instead. The old function name can still be used in current versions, however it is deprecated and not recommended.
oci_execute
(PHP 5, PECL OCI8 >= 1.1.0)
oci_execute — Executes a statement
Opis
$statement
[, int $mode = OCI_COMMIT_ON_SUCCESS
] )
Executes a statement previously returned
from oci_parse().
After execution, statements like INSERT will have data committed to the database by default. For statements like SELECT, execution performs the logic of the query. Query results can subsequently be fetched in PHP with functions like oci_fetch_array().
Each parsed statement may be executed multiple times, saving the cost of re-parsing. This is commonly used for INSERT statements when data is bound with oci_bind_by_name().
Parametry
-
statement -
A valid OCI statement identifier.
-
mode -
An optional second parameter can be one of the following constants:
Execution Modes Constant Description OCI_COMMIT_ON_SUCCESSAutomatically commit all outstanding changes for this connection when the statement has succeeded. This is the default. OCI_DEFAULTObsolete as of PHP 5.3.2 (PECL OCI8 1.4) but still available for backward compatibility. Use the equivalent OCI_NO_AUTO_COMMITin new code.OCI_DESCRIBE_ONLYMake query meta data available to functions like oci_field_name() but do not create a result set. Any subsequent fetch call such as oci_fetch_array() will fail. OCI_NO_AUTO_COMMITDo not automatically commit changes. Prior to PHP 5.3.2 (PECL OCI8 1.4) use OCI_DEFAULTwhich is an alias forOCI_NO_AUTO_COMMIT.Using
OCI_NO_AUTO_COMMITmode starts a transaction. Transactions are automatically rolled back when the connection is closed, or when the script ends. Explicitly call oci_commit() to commit a transaction, or oci_rollback() to abort it.When inserting or updating data, using transactions is recommended for relational data consistency and for performance reasons.
If
OCI_NO_AUTO_COMMITmode is used for any statement including queries, and oci_commit() or oci_rollback() is not subsequently called, then OCI8 will perform a rollback at the end of the script even if no data was changed. To avoid an unnecessary rollback, many scripts do not useOCI_NO_AUTO_COMMITmode for queries or PL/SQL. Be careful to ensure the appropriate transactional consistency for the application when using oci_execute() with different modes in the same script.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 oci_execute() for queries
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
$stid = oci_parse($conn, 'SELECT * FROM employees');
oci_execute($stid);
echo "<table border='1'>\n";
while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
echo "<tr>\n";
foreach ($row as $item) {
echo " <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : " ") . "</td>\n";
}
echo "</tr>\n";
}
echo "</table>\n";
?>
Przykład #2 oci_execute() without specifying a mode example
<?php
// Before running, create the table:
// CREATE TABLE MYTABLE (col1 NUMBER);
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
$stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (123)');
oci_execute($stid); // The row is committed and immediately visible to other users
?>
Przykład #3 oci_execute() with OCI_NO_AUTO_COMMIT example
<?php
// Before running, create the table:
// CREATE TABLE MYTABLE (col1 NUMBER);
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
$stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (:bv)');
oci_bind_by_name($stid, ':bv', $i, 10);
for ($i = 1; $i <= 5; ++$i) {
oci_execute($stid, OCI_NO_AUTO_COMMIT); // use OCI_DEFAULT for PHP <= 5.3.1
}
oci_commit($conn); // commits all new values: 1, 2, 3, 4, 5
?>
Przykład #4 oci_execute() with different commit modes example
<?php
// Before running, create the table:
// CREATE TABLE MYTABLE (col1 NUMBER);
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
$stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (123)');
oci_execute($stid, OCI_NO_AUTO_COMMIT); // data not committed
$stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (456)');
oci_execute($stid); // commits both 123 and 456 values
?>
Przykład #5 oci_execute() with
OCI_DESCRIBE_ONLY example
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
$stid = oci_parse($conn, 'SELECT * FROM locations');
oci_execute($s, OCI_DESCRIBE_ONLY);
for ($i = 1; $i <= oci_num_fields($stid); ++$i) {
echo oci_field_name($stid, $i) . "<br>\n";
}
?>
Notatki
Informacja:
Transactions are automatically rolled back when connections are closed, or when the script ends, whichever is soonest. Explicitly call oci_commit() to commit a transaction.
Any call to oci_execute() that uses
OCI_COMMIT_ON_SUCCESSmode explicitly or by default will commit any previous uncommitted transaction.Any Oracle DDL statement such as CREATE or DROP will automatically commit any uncommitted transaction.
Informacja:
Because the oci_execute() function generally sends the statement to the database, oci_execute() can identify some statement syntax errors that the lightweight, local oci_parse() function does not.
Informacja:
In PHP versions before 5.0.0 use ociexecute() instead. The old function name can still be used in current versions, however it is deprecated and not recommended.
oci_fetch_all
(PHP 5, PECL OCI8 >= 1.1.0)
oci_fetch_all — Fetches multiple rows from a query into a two-dimensional array
Opis
$statement
, array &$output
[, int $skip = 0
[, int $maxrows = -1
[, int $flags = OCI_FETCHSTATEMENT_BY_COLUMN + OCI_ASSOC
]]] )Fetches multiple rows from a query into a two-dimensional array. By default, all rows are returned.
This function can be called only once for each query executed with oci_execute().
Parametry
-
statement -
A valid OCI8 statement identifier created by oci_parse() and executed by oci_execute(), or a REF CURSOR statement identifier.
-
output -
The variable to contain the returned rows.
LOB columns are returned as strings, where Oracle supports conversion.
See oci_fetch_array() for more information on how data and types are fetched.
-
skip -
The number of initial rows to discard when fetching the result. The default value is 0, so the first row onwards is returned.
-
maxrows -
The number of rows to return. The default is -1 meaning return all the rows from
skip+ 1 onwards. -
flags -
Parameter
flagsindicates the array structure and whether associative arrays should be used.oci_fetch_all() Array Structure Modes Constant Description OCI_FETCHSTATEMENT_BY_ROWThe outer array will contain one sub-array per query row. OCI_FETCHSTATEMENT_BY_COLUMNThe outer array will contain one sub-array per query column. This is the default. Arrays can be indexed by column heading or numerically.
oci_fetch_all() Array Index Modes Constant Description OCI_NUMNumeric indexes are used for each column's array. OCI_ASSOCAssociative indexes are used for each column's array. This is the default. Use the addition operator "+" to choose a combination of array structure and index modes.
Oracle's default, non-case sensitive column names will have uppercase array keys. Case-sensitive column names will have array keys using the exact column case. Use var_dump() on
outputto verify the appropriate case to use for each query.Queries that have more than one column with the same name should use column aliases. Otherwise only one of the columns will appear in an associative array.
Zwracane wartości
Returns the number of rows in output, which
may be 0 or more, lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 oci_fetch_all() example
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$stid = oci_parse($conn, 'SELECT POSTAL_CODE, CITY FROM locations WHERE ROWNUM < 3');
oci_execute($stid);
$nrows = oci_fetch_all($stid, $res);
echo "$nrows rows fetched<br>\n";
var_dump($res);
// var_dump output is:
// 2 rows fetched
// array(2) {
// ["POSTAL_CODE"]=>
// array(2) {
// [0]=>
// string(6) "00989x"
// [1]=>
// string(6) "10934x"
// }
// ["CITY"]=>
// array(2) {
// [0]=>
// string(4) "Roma"
// [1]=>
// string(6) "Venice"
// }
// }
// Pretty-print the results
echo "<table border='1'>\n";
foreach ($res as $col) {
echo "<tr>\n";
foreach ($col as $item) {
echo " <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "")."</td>\n";
}
echo "</tr>\n";
}
echo "</table>\n";
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #2 oci_fetch_all() example with OCI_FETCHSTATEMENT_BY_ROW
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$stid = oci_parse($conn, 'SELECT POSTAL_CODE, CITY FROM locations WHERE ROWNUM < 3');
oci_execute($stid);
$nrows = oci_fetch_all($stid, $res, null, null, OCI_FETCHSTATEMENT_BY_ROW);
echo "$nrows rows fetched<br>\n";
var_dump($res);
// Output is:
// 2 rows fetched
// array(2) {
// [0]=>
// array(2) {
// ["POSTAL_CODE"]=>
// string(6) "00989x"
// ["CITY"]=>
// string(4) "Roma"
// }
// [1]=>
// array(2) {
// ["POSTAL_CODE"]=>
// string(6) "10934x"
// ["CITY"]=>
// string(6) "Venice"
// }
// }
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #3 oci_fetch_all() with OCI_NUM
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$stid = oci_parse($conn, 'SELECT POSTAL_CODE, CITY FROM locations WHERE ROWNUM < 3');
oci_execute($stid);
$nrows = oci_fetch_all($stid, $res, null, null, OCI_FETCHSTATEMENT_BY_ROW + OCI_NUM);
echo "$nrows rows fetched<br>\n";
var_dump($res);
// Output is:
// 2 rows fetched
// array(2) {
// [0]=>
// array(2) {
// [0]=>
// string(6) "00989x"
// [1]=>
// string(4) "Roma"
// }
// [1]=>
// array(2) {
// [0]=>
// string(6) "10934x"
// [1]=>
// string(6) "Venice"
// }
// }
oci_free_statement($stid);
oci_close($conn);
?>
Notatki
Informacja:
Using
skipis very inefficient. All the rows to be skipped are included in the result set that is returned from the database to PHP. They are then discarded. It is more efficient to use SQL to restrict the offset and range of rows in the query. See oci_fetch_array() for an example.
Informacja:
Queries that return a large number of rows can be more memory efficient if a single-row fetching function like oci_fetch_array() is used.
Informacja:
For queries returning a large number of rows, performance can be significantly improved by increasing oci8.default_prefetch or using oci_set_prefetch().
Informacja:
In PHP versions before 5.0.0 you must use ocifetchstatement() instead. The old function name can still be used in current versions, however it is deprecated and not recommended.
Zobacz też:
- oci_fetch() - Fetches the next row from a query into internal buffers
- oci_fetch_array() - Returns the next row from a query as an associative or numeric array
- oci_fetch_assoc() - Returns the next row from a query as an associative array
- oci_fetch_object() - Returns the next row from a query as an object
- oci_fetch_row() - Returns the next row from a query as a numeric array
- oci_set_prefetch() - Sets number of rows to be prefetched by queries
oci_fetch_array
(PHP 5, PECL OCI8 >= 1.1.0)
oci_fetch_array — Returns the next row from a query as an associative or numeric array
Opis
$statement
[, int $mode
] )
Returns an array containing the next result-set row of a query.
Each array entry corresponds to a column of the row. This function
is typically called in a loop until it returns FALSE, indicating
no more rows exist.
For details on the data type mapping performed by the OCI8 extension, see the datatypes supported by the driver
Parametry
-
statement -
A valid OCI8 statement identifier created by oci_parse() and executed by oci_execute(), or a REF CURSOR statement identifier.
-
mode -
An optional second parameter can be any combination of the following constants:
oci_fetch_array() Modes Constant Description OCI_BOTHReturns an array with both associative and numeric indices. This is the same as OCI_ASSOC+OCI_NUMand is the default behavior.OCI_ASSOCReturns an associative array. OCI_NUMReturns a numeric array. OCI_RETURN_NULLSCreates elements for NULLfields. The element values will be a PHPNULL.OCI_RETURN_LOBSReturns the contents of LOBs instead of the LOB descriptors. The default
modeisOCI_BOTH.Use the addition operator "+" to specify more than one mode at a time.
Zwracane wartości
Returns an array with associative and/or numeric indices. If there
are no more rows in the statement then
FALSE is returned.
By default, LOB columns are returned as LOB descriptors.
DATE columns are returned as strings formatted to the current date format. The default format can be changed with Oracle environment variables such as NLS_LANG or by a previously executed ALTER SESSION SET NLS_DATE_FORMAT command.
Oracle's default, non-case sensitive column names will have uppercase associative indices in the result array. Case-sensitive column names will have array indices using the exact column case. Use var_dump() on the result array to verify the appropriate case to use for each query.
Przykłady
Przykład #1 oci_fetch_array() with OCI_BOTH
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$stid = oci_parse($conn, 'SELECT department_id, department_name FROM departments');
oci_execute($stid);
while (($row = oci_fetch_array($stid, OCI_BOTH))) {
// Use the uppercase column names for the associative array indices
echo $row[0] . " and " . $row['DEPARTMENT_ID'] . " are the same<br>\n";
echo $row[1] . " and " . $row['DEPARTMENT_NAME'] . " are the same<br>\n";
}
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #2 oci_fetch_array() with OCI_NUM
<?php
/*
Before running, create the table:
CREATE TABLE mytab (id NUMBER, description CLOB);
INSERT INTO mytab (id, description) values (1, 'A very long string');
COMMIT;
*/
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$stid = oci_parse($conn, 'SELECT id, description FROM mytab');
oci_execute($stid);
while (($row = oci_fetch_array($stid, OCI_NUM))) {
echo $row[0] . "<br>\n";
echo $row[1]->read(11) . "<br>\n"; // this will output first 11 bytes from DESCRIPTION
}
// Output is:
// 1
// A very long
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #3 oci_fetch_array() with OCI_ASSOC
<?php
/*
Before running, create the table:
CREATE TABLE mytab (id NUMBER, description CLOB);
INSERT INTO mytab (id, description) values (1, 'A very long string');
COMMIT;
*/
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$stid = oci_parse($conn, 'SELECT id, description FROM mytab');
oci_execute($stid);
while (($row = oci_fetch_array($stid, OCI_ASSOC))) {
echo $row['ID'] . "<br>\n";
echo $row['DESCRIPTION']->read(11) . "<br>\n"; // this will output first 11 bytes from DESCRIPTION
}
// Output is:
// 1
// A very long
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #4 oci_fetch_array() with OCI_RETURN_NULLS
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$stid = oci_parse($conn, 'SELECT 1, null FROM dual');
oci_execute($stid);
while (($row = oci_fetch_array ($stid, OCI_ASSOC))) { // Ignore NULLs
var_dump($row);
}
/*
The above code prints:
array(1) {
[1]=>
string(1) "1"
}
*/
$stid = oci_parse($conn, 'SELECT 1, null FROM dual');
oci_execute($stid);
while (($row = oci_fetch_array ($stid, OCI_ASSOC+OCI_RETURN_NULLS))) { // Fetch NULLs
var_dump($row);
}
/*
The above code prints:
array(2) {
[1]=>
string(1) "1"
["NULL"]=>
NULL
}
*/
?>
Przykład #5 oci_fetch_array() with OCI_RETURN_LOBS
<?php
/*
Before running, create the table:
CREATE TABLE mytab (id NUMBER, description CLOB);
INSERT INTO mytab (id, description) values (1, 'A very long string');
COMMIT;
*/
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$stid = oci_parse($conn, 'SELECT id, description FROM mytab');
oci_execute($stid);
while (($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_LOBS))) {
echo $row['ID'] . "<br>\n";
echo $row['DESCRIPTION'] . "<br>\n"; // this contains all of DESCRIPTION
}
// Output is:
// 1
// A very long string
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #6 oci_fetch_array() with case sensitive column names
<?php
/*
Before running, create the table:
CREATE TABLE mytab ("Name" VARCHAR2(20), city VARCHAR2(20));
INSERT INTO mytab ("Name", city) values ('Chris', 'Melbourne');
COMMIT;
*/
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$stid = oci_parse($conn, 'select * from mytab');
oci_execute($stid);
$row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS);
// Because 'Name' was created as a case-sensitive column, that same
// case is used for the array index. However uppercase 'CITY' must
// be used for the case-insensitive column index
print $row['Name'] . "<br>\n"; // prints Chris
print $row['CITY'] . "<br>\n"; // prints Melbourne
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #7 oci_fetch_array() with columns having duplicate names
<?php
/*
Before running, create the tables:
CREATE TABLE mycity (id NUMBER, name VARCHAR2(20));
INSERT INTO mycity (id, name) values (1, 'Melbourne');
CREATE TABLE mycountry (id NUMBER, name VARCHAR2(20));
INSERT INTO mycountry (id, name) values (1, 'Australia');
COMMIT;
*/
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$sql = 'SELECT mycity.name, mycountry.name
FROM mycity, mycountry
WHERE mycity.id = mycountry.id';
$stid = oci_parse($conn, $sql);
oci_execute($stid);
$row = oci_fetch_array($stid, OCI_ASSOC);
var_dump($row);
// Output only contains one "NAME" entry:
// array(1) {
// ["NAME"]=>
// string(9) "Australia"
// }
// To query a repeated column name, use an SQL column alias like "AS ctnm":
$sql = 'SELECT mycity.name AS ctnm, mycountry.name
FROM mycity, mycountry
WHERE mycity.id = mycountry.id';
$stid = oci_parse($conn, $sql);
oci_execute($stid);
$row = oci_fetch_array($stid, OCI_ASSOC);
var_dump($row);
// Output now contains both columns selected:
// array(2) {
// ["CTNM"]=>
// string(9) "Melbourne"
// ["NAME"]=>
// string(9) "Australia"
// }
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #8 oci_fetch_array() with DATE columns
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
// Set the date format for this connection.
// For performance reasons, consider changing the format
// in a trigger or with environment variables instead
$stid = oci_parse($conn, "ALTER SESSION SET NLS_DATE_FORMAT = 'YYYY-MM-DD'");
oci_execute($stid);
$stid = oci_parse($conn, 'SELECT hire_date FROM employees WHERE employee_id = 188');
oci_execute($stid);
$row = oci_fetch_array($stid, OCI_ASSOC);
echo $row['HIRE_DATE'] . "<br>\n"; // prints 1997-06-14
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #9 oci_fetch_array() with REF CURSOR
<?php
/*
Create the PL/SQL stored procedure as:
CREATE OR REPLACE PROCEDURE myproc(p1 OUT SYS_REFCURSOR) AS
BEGIN
OPEN p1 FOR SELECT * FROM all_objects WHERE ROWNUM < 5000;
END;
*/
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$stid = oci_parse($conn, 'BEGIN myproc(:rc); END;');
$refcur = oci_new_cursor($conn);
oci_bind_by_name($stid, ':rc', $refcur, -1, OCI_B_CURSOR);
oci_execute($stid);
// Execute the returned REF CURSOR and fetch from it like a statement identifier
oci_execute($refcur);
echo "<table border='1'>\n";
while ($row = oci_fetch_array($refcur, OCI_ASSOC+OCI_RETURN_NULLS)) {
echo "<tr>\n";
foreach ($row as $item) {
echo " <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : " ")."</td>\n";
}
echo "</tr>\n";
}
echo "</table>\n";
oci_free_statement($refcur);
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #10 oci_fetch_array() with a LIMIT-like query
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
// This is the query you want to execute
$sql = 'SELECT city, postal_code FROM locations ORDER BY city';
// This nested query selects a subset of rows from $sql.
// In production environments, be careful to avoid SQL Injection
// issues with concatenated SQL statements
$limit_sql =
'select *
from ( select a.*, rownum as rnum
from (' . $sql . ') a
where rownum < :FIRST_ROW + :NUM_ROWS )
where rnum >= :FIRST_ROW';
$first = 1; // start with the first row
$num = 5; // return 5 rows
$stid = oci_parse($conn, $limit_sql);
oci_bind_by_name($stid, ':FIRST_ROW', $first);
oci_bind_by_name($stid, ':NUM_ROWS', $num);
oci_execute($stid);
while (($row = oci_fetch_array($stid, OCI_ASSOC))) {
echo $row['CITY'] . " " . $row['POSTAL_CODE'] . "<br>\n";
}
// Output is:
// Beijing 190518x
// Bern 3095x
// Bombay 490231x
// Geneva 1730x
// Hiroshima 6823x
oci_free_statement($stid);
oci_close($conn);
?>
Notatki
Informacja:
Associative array indices need to be in uppercase for standard Oracle columns that were created with case insensitive names.
Informacja:
For queries returning a large number of rows, performance can be significantly improved by increasing oci8.default_prefetch or using oci_set_prefetch().
Informacja:
The function oci_fetch_array() is insignificantly slower than oci_fetch_assoc() or oci_fetch_row(), but is more flexible.
Zobacz też:
- oci_fetch() - Fetches the next row from a query into internal buffers
- oci_fetch_all() - Fetches multiple rows from a query into a two-dimensional array
- oci_fetch_assoc() - Returns the next row from a query as an associative array
- oci_fetch_object() - Returns the next row from a query as an object
- oci_fetch_row() - Returns the next row from a query as a numeric array
- oci_set_prefetch() - Sets number of rows to be prefetched by queries
oci_fetch_assoc
(PHP 5, PECL OCI8 >= 1.1.0)
oci_fetch_assoc — Returns the next row from a query as an associative array
Opis
$statement
)
Returns an associative array containing the next result-set row of a query.
Each array entry corresponds to a column of the row. This function
is typically called in a loop until it returns FALSE, indicating
no more rows exist.
Calling oci_fetch_assoc() is identical to
calling oci_fetch_array()
with OCI_ASSOC
+ OCI_RETURN_NULLS.
Parametry
-
statement -
A valid OCI8 statement identifier created by oci_parse() and executed by oci_execute(), or a REF CURSOR statement identifier.
Zwracane wartości
Returns an associative array. If there are no more rows in
the statement then FALSE is returned.
Notatki
Informacja:
See oci_fetch_array() for examples of fetching rows.
Zobacz też:
- oci_fetch() - Fetches the next row from a query into internal buffers
- oci_fetch_all() - Fetches multiple rows from a query into a two-dimensional array
- oci_fetch_array() - Returns the next row from a query as an associative or numeric array
- oci_fetch_object() - Returns the next row from a query as an object
- oci_fetch_row() - Returns the next row from a query as a numeric array
oci_fetch_object
(PHP 5, PECL OCI8 >= 1.1.0)
oci_fetch_object — Returns the next row from a query as an object
Opis
$statement
)
Returns an object containing the next result-set row of a query.
Each attribute of the object corresponds to a column of the row.
This function is typically called in a loop until it returns
FALSE, indicating no more rows exist.
For details on the data type mapping performed by the OCI8 extension, see the datatypes supported by the driver
Parametry
-
statement -
A valid OCI8 statement identifier created by oci_parse() and executed by oci_execute(), or a REF CURSOR statement identifier.
Zwracane wartości
Returns an object. Each attribute of the object corresponds to a
column of the row. If there are no more rows in
the statement then FALSE is returned.
Any LOB columns are returned as LOB descriptors.
DATE columns are returned as strings formatted to the current date format. The default format can be changed with Oracle environment variables such as NLS_LANG or by a previously executed ALTER SESSION SET NLS_DATE_FORMAT command.
Oracle's default, non-case sensitive column names will have uppercase attribute names. Case-sensitive column names will have attribute names using the exact column case. Use var_dump() on the result object to verify the appropriate case to use for each query.
Attribute values will be NULL for any NULL
data fields.
Przykłady
Przykład #1 oci_fetch_object() example
<?php
/*
Before running, create the table:
CREATE TABLE mytab (id NUMBER, description VARCHAR2(30));
INSERT INTO mytab (id, description) values (1, 'Fish and Chips');
COMMIT;
*/
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$stid = oci_parse($conn, 'SELECT id, description FROM mytab');
oci_execute($stid);
while (($row = oci_fetch_object($stid))) {
// Use upper case attribute names for each standard Oracle column
echo $row->ID . "<br>\n";
echo $row->DESCRIPTION . "<br>\n";
}
// Output is:
// 1
// Fish and Chips
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #2 oci_fetch_object() with case sensitive column names
<?php
/*
Before running, create the table with a case sensitive column name:
CREATE TABLE mytab (id NUMBER, "MyDescription" VARCHAR2(30));
INSERT INTO mytab (id, "MyDescription") values (1, 'Iced Coffee');
COMMIT;
*/
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$stid = oci_parse($conn, 'SELECT id, "MyDescription" FROM mytab');
oci_execute($stid);
while (($row = oci_fetch_object($stid))) {
// Use upper case attribute names for each standard Oracle column
echo $row->ID . "<br>\n";
// Use the exact case for the case sensitive column name
echo $row->MyDescription . "<br>\n";
}
// Output is:
// 1
// Iced Coffee
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #3 oci_fetch_object() with LOBs
<?php
/*
Before running, create the table:
CREATE TABLE mytab (id NUMBER, description CLOB);
INSERT INTO mytab (id, description) values (1, 'A very long string');
COMMIT;
*/
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$stid = oci_parse($conn, 'SELECT id, description FROM mytab');
oci_execute($stid);
while (($row = oci_fetch_object($stid))) {
echo $row->ID . "<br>\n";
// The following will output the first 11 bytes from DESCRIPTION
echo $row->DESCRIPTION->read(11) . "<br>\n";
}
// Output is:
// 1
// A very long
oci_free_statement($stid);
oci_close($conn);
?>
Zobacz też:
- oci_fetch() - Fetches the next row from a query into internal buffers
- oci_fetch_all() - Fetches multiple rows from a query into a two-dimensional array
- oci_fetch_assoc() - Returns the next row from a query as an associative array
- oci_fetch_array() - Returns the next row from a query as an associative or numeric array
- oci_fetch_row() - Returns the next row from a query as a numeric array
oci_fetch_row
(PHP 5, PECL OCI8 >= 1.1.0)
oci_fetch_row — Returns the next row from a query as a numeric array
Opis
$statement
)
Returns a numerically indexed array containing the next result-set row of a query.
Each array entry corresponds to a column of the row. This function
is typically called in a loop until it returns FALSE, indicating
no more rows exist.
Calling oci_fetch_row() is identical to calling
oci_fetch_array()
with OCI_NUM
+ OCI_RETURN_NULLS.
Parametry
-
statement -
A valid OCI8 statement identifier created by oci_parse() and executed by oci_execute(), or a REF CURSOR statement identifier.
Zwracane wartości
Returns a numerically indexed array. If there are no more rows in
the statement then FALSE is returned.
Notatki
Informacja:
See oci_fetch_array() for examples of fetching rows.
Zobacz też:
- oci_fetch() - Fetches the next row from a query into internal buffers
- oci_fetch_all() - Fetches multiple rows from a query into a two-dimensional array
- oci_fetch_array() - Returns the next row from a query as an associative or numeric array
- oci_fetch_assoc() - Returns the next row from a query as an associative array
- oci_fetch_object() - Returns the next row from a query as an object
oci_fetch
(PHP 5, PECL OCI8 >= 1.1.0)
oci_fetch — Fetches the next row from a query into internal buffers
Opis
$statement
)Fetches the next row from a query into internal buffers accessible either with oci_result(), or by using variables previously defined with oci_define_by_name().
See oci_fetch_array() for general information about fetching data.
Parametry
-
statement -
A valid OCI8 statement identifier created by oci_parse() and executed by oci_execute(), or a REF CURSOR statement identifier.
Zwracane wartości
Returns TRUE on success or FALSE if there are no more rows in the
statement.
Przykłady
Przykład #1 oci_fetch() with defined variables
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
$stid = oci_parse($conn, $sql);
// The defines MUST be done before executing
oci_define_by_name($stid, 'LOCATION_ID', $locid);
oci_define_by_name($stid, 'CITY', $city);
oci_execute($stid);
// Each fetch populates the previously defined variables with the next row's data
while (oci_fetch($stid)) {
echo "Location id $locid is $city<br>\n";
}
// Displays:
// Location id 1000 is Roma
// Location id 1100 is Venice
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #2 oci_fetch() with oci_result()
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
$stid = oci_parse($conn, $sql);
oci_execute($stid);
while (oci_fetch($stid)) {
echo oci_result($stid, 'LOCATION_ID') . " is ";
echo oci_result($stid, 'CITY') . "<br>\n";
}
// Displays:
// 1000 is Roma
// 1100 is Venice
oci_free_statement($stid);
oci_close($conn);
?>
Notatki
Informacja:
In PHP versions before 5.0.0 use ocifetch() instead. The old function name can still be used in current versions, however it is deprecated and not recommended.
Zobacz też:
- oci_define_by_name() - Associates a PHP variable with a column for query fetches
- oci_fetch_all() - Fetches multiple rows from a query into a two-dimensional array
- oci_fetch_array() - Returns the next row from a query as an associative or numeric array
- oci_fetch_assoc() - Returns the next row from a query as an associative array
- oci_fetch_object() - Returns the next row from a query as an object
- oci_fetch_row() - Returns the next row from a query as a numeric array
- oci_result() - Returns field's value from the fetched row
oci_field_is_null
(PHP 5, PECL OCI8 >= 1.1.0)
oci_field_is_null — Checks if the field is NULL
Opis
Checks if the given field from the
statement is NULL.
Parametry
-
statement -
A valid OCI statement identifier.
-
field -
Can be a field's index or a field's name (uppercased).
Zwracane wartości
Returns TRUE if field is NULL, FALSE otherwise.
Notatki
Informacja:
In PHP versions before 5.0.0 you must use ocicolumnisnull() instead. This name still can be used, it was left as alias of oci_field_is_null() for downwards compatability. This, however, is deprecated and not recommended.
oci_field_name
(PHP 5, PECL OCI8 >= 1.1.0)
oci_field_name — Returns the name of a field from the statement
Opis
$statement
, int $field
)
Returns the name of the field.
Parametry
-
statement -
A valid OCI statement identifier.
-
field -
Can be the field's index (1-based) or name.
Zwracane wartości
Returns the name as a string, or FALSE on errors.
Przykłady
Przykład #1 oci_field_name() example
<?php
$conn = oci_connect("scott", "tiger");
$stmt = oci_parse($conn, "SELECT * FROM emp");
oci_execute($stmt);
echo "<table border=\"1\">";
echo "<tr>";
echo "<th>Name</th>";
echo "<th>Type</th>";
echo "<th>Length</th>";
echo "</tr>";
$ncols = oci_num_fields($stmt);
for ($i = 1; $i <= $ncols; $i++) {
$column_name = oci_field_name($stmt, $i);
$column_type = oci_field_type($stmt, $i);
$column_size = oci_field_size($stmt, $i);
echo "<tr>";
echo "<td>$column_name</td>";
echo "<td>$column_type</td>";
echo "<td>$column_size</td>";
echo "</tr>";
}
echo "</table>\n";
oci_free_statement($stmt);
oci_close($conn);
?>
Notatki
Informacja:
In PHP versions before 5.0.0 you must use ocicolumnname() instead. This name still can be used, it was left as alias of oci_field_name() for downwards compatability. This, however, is deprecated and not recommended.
Zobacz też:
- oci_num_fields() - Returns the number of result columns in a statement
- oci_field_type() - Returns field's data type
- oci_field_size() - Returns field's size
oci_field_precision
(PHP 5, PECL OCI8 >= 1.1.0)
oci_field_precision — Tell the precision of a field
Opis
$statement
, int $field
)
Returns precision of the field.
For FLOAT columns, precision is nonzero and scale is -127. If precision is 0, then column is NUMBER. Else it's NUMBER(precision, scale).
Parametry
-
statement -
A valid OCI statement identifier.
-
field -
Can be the field's index (1-based) or name.
Zwracane wartości
Returns the precision as an integer, or FALSE on errors.
Notatki
Informacja:
In PHP versions before 5.0.0 you must use ocicolumnprecision() instead. This name still can be used, it was left as alias of oci_field_precision() for downwards compatability. This, however, is deprecated and not recommended.
Zobacz też:
- oci_field_scale() - Tell the scale of the field
- oci_field_type() - Returns field's data type
oci_field_scale
(PHP 5, PECL OCI8 >= 1.1.0)
oci_field_scale — Tell the scale of the field
Opis
$statement
, int $field
)
Returns the scale of the column with field index.
For FLOAT columns, precision is nonzero and scale is -127. If precision is 0, then column is NUMBER. Else it's NUMBER(precision, scale).
Parametry
-
statement -
A valid OCI statement identifier.
-
field -
Can be the field's index (1-based) or name.
Zwracane wartości
Returns the scale as an integer, or FALSE on errors.
Notatki
Informacja:
In PHP versions before 5.0.0 you must use ocicolumnscale() instead. This name still can be used, it was left as alias of oci_field_scale() for downwards compatability. This, however, is deprecated and not recommended.
Zobacz też:
- oci_field_precision() - Tell the precision of a field
- oci_field_type() - Returns field's data type
oci_field_size
(PHP 5, PECL OCI8 >= 1.1.0)
oci_field_size — Returns field's size
Parametry
-
statement -
A valid OCI statement identifier.
-
field -
Can be the field's index (1-based) or name.
Zwracane wartości
Returns the size of a field in bytes, or FALSE on
errors.
Przykłady
Przykład #1 oci_field_size() example
<?php
$conn = oci_connect("scott", "tiger");
$stmt = oci_parse($conn, "SELECT * FROM emp");
oci_execute($stmt);
echo "<table border=\"1\">";
echo "<tr>";
echo "<th>Name</th>";
echo "<th>Type</th>";
echo "<th>Length</th>";
echo "</tr>";
$ncols = oci_num_fields($stmt);
for ($i = 1; $i <= $ncols; $i++) {
$column_name = oci_field_name($stmt, $i);
$column_type = oci_field_type($stmt, $i);
$column_size = oci_field_size($stmt, $i);
echo "<tr>";
echo "<td>$column_name</td>";
echo "<td>$column_type</td>";
echo "<td>$column_size</td>";
echo "</tr>";
}
echo "</table>";
oci_free_statement($stmt);
oci_close($conn);
?>
Notatki
Informacja:
In PHP versions before 5.0.0 you must use ocicolumnsize() instead. This name still can be used, it was left as alias of oci_field_size() for downwards compatability. This, however, is deprecated and not recommended.
Zobacz też:
- oci_num_fields() - Returns the number of result columns in a statement
- oci_field_name() - Returns the name of a field from the statement
oci_field_type_raw
(PHP 5, PECL OCI8 >= 1.1.0)
oci_field_type_raw — Tell the raw Oracle data type of the field
Opis
$statement
, int $field
)
Returns Oracle's raw data type of the field.
However, if you want to get field's type, then oci_field_type() will suit you better.
Parametry
-
statement -
A valid OCI statement identifier.
-
field -
Can be the field's index (1-based) or name.
Zwracane wartości
Returns Oracle's raw data type as a string, or FALSE on errors.
Notatki
Informacja:
In PHP versions before 5.0.0 you must use ocicolumntyperaw() instead. This name still can be used, it was left as alias of oci_field_type_raw() for downwards compatability. This, however, is deprecated and not recommended.
oci_field_type
(PHP 5, PECL OCI8 >= 1.1.0)
oci_field_type — Returns field's data type
Parametry
-
statement -
A valid OCI statement identifier.
-
field -
Can be the field's index (1-based) or name.
Zwracane wartości
Returns the field data type as a string, or FALSE on errors.
Zwracane wartości
Przykład #1 oci_field_type() example
<?php
$conn = oci_connect("scott", "tiger");
$stmt = oci_parse($conn, "SELECT * FROM emp");
oci_execute($stmt);
echo "<table border=\"1\">";
echo "<tr>";
echo "<th>Name</th>";
echo "<th>Type</th>";
echo "<th>Length</th>";
echo "</tr>";
$ncols = oci_num_fields($stmt);
for ($i = 1; $i <= $ncols; $i++) {
$column_name = oci_field_name($stmt, $i);
$column_type = oci_field_type($stmt, $i);
$column_size = oci_field_size($stmt, $i);
echo "<tr>";
echo "<td>$column_name</td>";
echo "<td>$column_type</td>";
echo "<td>$column_size</td>";
echo "</tr>";
}
echo "</table>\n";
oci_free_statement($stmt);
oci_close($conn);
?>
Notatki
Informacja:
In PHP versions before 5.0.0 you must use ocicolumntype() instead. This name still can be used, it was left as alias of oci_field_type() for downwards compatability. This, however, is deprecated and not recommended.
Zobacz też:
- oci_num_fields() - Returns the number of result columns in a statement
- oci_field_name() - Returns the name of a field from the statement
- oci_field_size() - Returns field's size
oci_free_statement
(PHP 5, PECL OCI8 >= 1.1.0)
oci_free_statement — Frees all resources associated with statement or cursor
Opis
$statement
)Frees resources associated with Oracle's cursor or statement, which was received from as a result of oci_parse() or obtained from Oracle.
Parametry
-
statement -
A valid OCI statement identifier.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
oci_internal_debug
(PHP 5, PECL OCI8 >= 1.1.0)
oci_internal_debug — Enables or disables internal debug output
Opis
$onoff
)Enables or disables internal debug output.
Parametry
-
onoff -
Set this to
FALSEto turn debug output off orTRUEto turn it on.
Zwracane wartości
Nie jest zwracana żadna wartość.
Notatki
Informacja:
In PHP versions before 5.0.0 you must use ociinternaldebug() instead. This name still can be used, it was left as alias of oci_internal_debug() for downwards compatability. This, however, is deprecated and not recommended.
oci_lob_copy
(PHP 5, PECL OCI8 >= 1.1.0)
oci_lob_copy — Copies large object
Opis
$lob_to
, OCI-Lob $lob_from
[, int $length = 0
] )Copies a large object or a part of a large object to another large object. Old LOB-recipient data will be overwritten.
If you need to copy a particular part of a LOB to a particular position of a LOB, use OCI-Lob::seek() to move LOB internal pointers.
Parametry
-
lob_to -
The destination LOB.
-
lob_from -
The copied LOB.
-
length -
Indicates the length of data to be copied.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
oci_lob_is_equal
(PHP 5, PECL OCI8 >= 1.1.0)
oci_lob_is_equal — Compares two LOB/FILE locators for equality
Opis
$lob1
, OCI-Lob $lob2
)Compares two LOB/FILE locators.
Parametry
-
lob1 -
A LOB identifier.
-
lob2 -
A LOB identifier.
Zwracane wartości
Returns TRUE if these objects are equal, FALSE otherwise.
oci_new_collection
(PHP 5, PECL OCI8 >= 1.1.0)
oci_new_collection — Allocates new collection object
Opis
$connection
, string $tdo
[, string $schema = NULL
] )Allocates a new collection object.
Parametry
-
connection -
An Oracle connection identifier, returned by oci_connect() or oci_pconnect().
-
tdo -
Should be a valid named type (uppercase).
-
schema -
Should point to the scheme, where the named type was created. The name of the current user is the default value.
Zwracane wartości
Returns a new OCICollection object or FALSE on
error.
Notatki
Informacja:
In PHP versions before 5.0.0 you must use ocinewcollection() instead. This name still can be used, it was left as alias of oci_new_collection() for downwards compatability. This, however, is deprecated and not recommended.
oci_new_connect
(PHP 5, PECL OCI8 >= 1.1.0)
oci_new_connect — Connect to the Oracle server using a unique connection
Opis
$username
, string $password
[, string $connection_string
[, string $character_set
[, int $session_mode
]]] )Establishes a new connection to an Oracle server and logs on.
Unlike oci_connect() and oci_pconnect(), oci_new_connect() does not cache connections and will always return a brand-new freshly opened connection handle. This is useful if your application needs transactional isolation between two sets of queries.
Parametry
-
username -
The Oracle user name.
-
password -
The password for
username. -
connection_string -
Contains the Oracle instance to connect to. It can be an » Easy Connect string, or a Connect Name from the tnsnames.ora file, or the name of a local Oracle instance.
If not specified, PHP uses environment variables such as
TWO_TASK(on Linux) orLOCAL(on Windows) andORACLE_SIDto determine the Oracle instance to connect to.To use the Easy Connect naming method, PHP must be linked with Oracle 10g or greater Client libraries. The Easy Connect string for Oracle 10g is of the form: [//]host_name[:port][/service_name]. With Oracle 11g, the syntax is: [//]host_name[:port][/service_name][:server_type][/instance_name]. Service names can be found by running the Oracle utility lsnrctl status on the database server machine.
The tnsnames.ora file can be in the Oracle Net search path, which includes $ORACLE_HOME/network/admin and /etc. Alternatively set TNS_ADMIN so that $TNS_ADMIN/tnsnames.ora is read. Make sure the web daemon has read access to the file.
-
character_set -
Determines the character set used by the Oracle Client libraries. The character set does not need to match the character set used by the database. If it doesn't match, Oracle will do its best to convert data to and from the database character set. Depending on the character sets this may not give usable results. Conversion also adds some time overhead.
If not specified, the Oracle Client libraries determine a character set from the
NLS_LANGenvironment variable.Passing this parameter can reduce connection time.
-
session_mode -
This parameter is available since version PHP 5 (PECL OCI8 1.1) and accepts the following values:
OCI_DEFAULT,OCI_SYSOPERandOCI_SYSDBA. If eitherOCI_SYSOPERorOCI_SYSDBAwere specified, this function will try to establish privileged connection using external credentials. Privileged connections are disabled by default. To enable them you need to set oci8.privileged_connect to On.PHP 5.3 (PECL OCI8 1.3.4) introduced the
OCI_CRED_EXTmode value. This tells Oracle to use External or OS authentication, which must be configured in the database. TheOCI_CRED_EXTflag can only be used with username of "/" and a empty password. oci8.privileged_connect may be On or Off.OCI_CRED_EXTmay be combined with theOCI_SYSOPERorOCI_SYSDBAmodes.OCI_CRED_EXTis not supported on Windows for security reasons.
Zwracane wartości
Returns a connection identifier or FALSE on error.
Przykłady
The following demonstrates how you can separate connections.
Przykład #1 oci_new_connect() example
<?php
echo "<html><pre>";
$db = "";
$c1 = oci_connect("scott", "tiger", $db);
$c2 = oci_new_connect("scott", "tiger", $db);
function create_table($conn)
{
$stmt = oci_parse($conn, "create table scott.hallo (test
varchar2(64))");
oci_execute($stmt);
echo $conn . " created table\n\n";
}
function drop_table($conn)
{
$stmt = oci_parse($conn, "drop table scott.hallo");
oci_execute($stmt);
echo $conn . " dropped table\n\n";
}
function insert_data($conn)
{
$stmt = oci_parse($conn, "insert into scott.hallo
values('$conn' || ' ' || to_char(sysdate,'DD-MON-YY HH24:MI:SS'))");
oci_execute($stmt, OCI_DEFAULT);
echo $conn . " inserted hallo\n\n";
}
function delete_data($conn)
{
$stmt = oci_parse($conn, "delete from scott.hallo");
oci_execute($stmt, OCI_DEFAULT);
echo $conn . " deleted hallo\n\n";
}
function commit($conn)
{
oci_commit($conn);
echo $conn . " committed\n\n";
}
function rollback($conn)
{
oci_rollback($conn);
echo $conn . " rollback\n\n";
}
function select_data($conn)
{
$stmt = oci_parse($conn, "select * from scott.hallo");
oci_execute($stmt, OCI_DEFAULT);
echo $conn . "----selecting\n\n";
while (oci_fetch($stmt)) {
echo $conn . " <" . oci_result($stmt, "TEST") . ">\n\n";
}
echo $conn . "----done\n\n";
}
create_table($c1);
insert_data($c1);
select_data($c1);
select_data($c2);
rollback($c1);
select_data($c1);
select_data($c2);
insert_data($c2);
commit($c2);
select_data($c1);
delete_data($c1);
select_data($c1);
select_data($c2);
commit($c1);
select_data($c1);
select_data($c2);
drop_table($c1);
echo "</pre></html>";
?>
Notatki
Informacja:
In PHP versions before 5.0.0 you must use ocinlogon() instead. The old function name can still be used in current versions, however it is deprecated and not recommended.
Zobacz też:
- oci_connect() - Connect to an Oracle database
- oci_pconnect() - Connect to an Oracle database using a persistent connection
oci_new_cursor
(PHP 5, PECL OCI8 >= 1.1.0)
oci_new_cursor — Allocates and returns a new cursor (statement handle)
Opis
$connection
)Allocates a new statement handle on the specified connection.
Zwracane wartości
Returns a new statement handle, or FALSE on error.
Przykłady
Przykład #1 Using REF CURSOR in an Oracle's stored procedure
<?php
// suppose your stored procedure info.output returns a ref cursor in :data
$conn = oci_connect("scott", "tiger");
$curs = oci_new_cursor($conn);
$stmt = oci_parse($conn, "begin info.output(:data); end;");
oci_bind_by_name($stmt, "data", $curs, -1, OCI_B_CURSOR);
oci_execute($stmt);
oci_execute($curs);
while ($data = oci_fetch_row($curs)) {
var_dump($data);
}
oci_free_statement($stmt);
oci_free_statement($curs);
oci_close($conn);
?>
Przykład #2 Using REF CURSOR in an Oracle's select statement
<?php
echo "<html><body>";
$conn = oci_connect("scott", "tiger");
$count_cursor = "CURSOR(select count(empno) num_emps from emp " .
"where emp.deptno = dept.deptno) as EMPCNT from dept";
$stmt = oci_parse($conn, "select deptno,dname,$count_cursor");
oci_execute($stmt);
echo "<table border=\"1\">";
echo "<tr>";
echo "<th>DEPT NAME</th>";
echo "<th>DEPT #</th>";
echo "<th># EMPLOYEES</th>";
echo "</tr>";
while ($data = oci_fetch_assoc($stmt)) {
echo "<tr>";
$dname = $data["DNAME"];
$deptno = $data["DEPTNO"];
echo "<td>$dname</td>";
echo "<td>$deptno</td>";
oci_execute($data["EMPCNT"]);
while ($subdata = oci_fetch_assoc($data["EMPCNT"])) {
$num_emps = $subdata["NUM_EMPS"];
echo "<td>$num_emps</td>";
}
echo "</tr>";
}
echo "</table>";
echo "</body></html>";
oci_free_statement($stmt);
oci_close($conn);
?>
Notatki
Informacja:
In PHP versions before 5.0.0 you must use ocinewcursor() instead. This name still can be used, it was left as alias of oci_new_cursor() for downwards compatability. This, however, is deprecated and not recommended.
oci_new_descriptor
(PHP 5, PECL OCI8 >= 1.1.0)
oci_new_descriptor — Initializes a new empty LOB or FILE descriptor
Opis
$connection
[, int $type = OCI_DTYPE_LOB
] )Allocates resources to hold descriptor or LOB locator.
Parametry
-
connection -
An Oracle connection identifier, returned by oci_connect() or oci_pconnect().
-
type -
Valid values for
typeare:OCI_DTYPE_FILE,OCI_DTYPE_LOBandOCI_DTYPE_ROWID.
Zwracane wartości
Returns a new LOB or FILE descriptor on success, FALSE on error.
Przykłady
Przykład #1 oci_new_descriptor() example
<?php
/* This script is designed to be called from a HTML form.
* It expects $user, $password, $table, $where, and $commitsize
* to be passed in from the form. The script then deletes
* the selected rows using the ROWID and commits after each
* set of $commitsize rows. (Use with care, there is no rollback)
*/
$conn = oci_connect($user, $password);
$stmt = oci_parse($conn, "select rowid from $table $where");
$rowid = oci_new_descriptor($conn, OCI_D_ROWID);
oci_define_by_name($stmt, "ROWID", $rowid);
oci_execute($stmt);
while (oci_fetch($stmt)) {
$nrows = oci_num_rows($stmt);
$delete = oci_parse($conn, "delete from $table where ROWID = :rid");
oci_bind_by_name($delete, ":rid", $rowid, -1, OCI_B_ROWID);
oci_execute($delete);
echo "$nrows\n";
if (($nrows % $commitsize) == 0) {
oci_commit($conn);
}
}
$nrows = oci_num_rows($stmt);
echo "$nrows deleted...\n";
oci_free_statement($stmt);
oci_close($conn);
?>
<?php
/* This script demonstrates file upload to LOB columns
* The formfield used for this example looks like this
* <form action="upload.php" method="post" enctype="multipart/form-data">
* <input type="file" name="lob_upload" />
* ...
*/
if (!isset($lob_upload) || $lob_upload == 'none'){
?>
<form action="upload.php" method="post" enctype="multipart/form-data">
Upload file: <input type="file" name="lob_upload" /><br />
<input type="submit" value="Upload" /> - <input type="reset" value="Reset" />
</form>
<?php
} else {
// $lob_upload contains the temporary filename of the uploaded file
// see also the features section on file upload,
// if you would like to use secure uploads
$conn = oci_connect($user, $password);
$lob = oci_new_descriptor($conn, OCI_D_LOB);
$stmt = oci_parse($conn, "insert into $table (id, the_blob)
values(my_seq.NEXTVAL, EMPTY_BLOB()) returning the_blob into :the_blob");
oci_bind_by_name($stmt, ':the_blob', $lob, -1, OCI_B_BLOB);
oci_execute($stmt, OCI_DEFAULT);
if ($lob->savefile($lob_upload)){
oci_commit($conn);
echo "Blob successfully uploaded\n";
}else{
echo "Couldn't upload Blob\n";
}
oci_free_descriptor($lob);
oci_free_statement($stmt);
oci_close($conn);
}
?>
Przykład #2 oci_new_descriptor() example
<?php
/* Calling PL/SQL stored procedures which contain clobs as input
* parameters (PHP 4 >= 4.0.6).
* Example PL/SQL stored procedure signature is:
*
* PROCEDURE save_data
* Argument Name Type In/Out Default?
* ------------------------------ ----------------------- ------ --------
* KEY NUMBER(38) IN
* DATA CLOB IN
*
*/
$conn = oci_connect($user, $password);
$stmt = oci_parse($conn, "begin save_data(:key, :data); end;");
$clob = oci_new_descriptor($conn, OCI_D_LOB);
oci_bind_by_name($stmt, ':key', $key);
oci_bind_by_name($stmt, ':data', $clob, -1, OCI_B_CLOB);
$clob->write($data);
oci_execute($stmt, OCI_DEFAULT);
oci_commit($conn);
$clob->free();
oci_free_statement($stmt);
?>
Notatki
Informacja:
In PHP versions before 5.0.0 you must use ocinewdescriptor() instead. This name still can be used, it was left as alias of oci_new_descriptor() for downwards compatability. This, however, is deprecated and not recommended.
oci_num_fields
(PHP 5, PECL OCI8 >= 1.1.0)
oci_num_fields — Returns the number of result columns in a statement
Opis
$statement
)
Gets the number of columns in the given statement.
Parametry
-
statement -
A valid OCI statement identifier.
Zwracane wartości
Returns the number of columns as an integer, or FALSE on errors.
Przykłady
Przykład #1 oci_num_fields() example
<?php
$conn = oci_connect("scott", "tiger");
$stmt = oci_parse($conn, "select * from emp");
oci_execute($stmt);
while (oci_fetch($stmt)) {
echo "\n";
$ncols = oci_num_fields($stmt);
for ($i = 1; $i <= $ncols; $i++) {
$column_name = oci_field_name($stmt, $i);
$column_value = oci_result($stmt, $i);
echo $column_name . ': ' . $column_value . "\n";
}
echo "\n";
}
oci_free_statement($stmt);
oci_close($conn);
?>
Notatki
Informacja:
In PHP versions before 5.0.0 you must use ocinumcols() instead. This name still can be used, it was left as alias of oci_num_fields() for downwards compatability. This, however, is deprecated and not recommended.
oci_num_rows
(PHP 5, PECL OCI8 >= 1.1.0)
oci_num_rows — Returns number of rows affected during statement execution
Opis
$statement
)Gets the number of rows affected during statement execution.
Parametry
-
statement -
A valid OCI statement identifier.
Zwracane wartości
Returns the number of rows affected as an integer, or FALSE on errors.
Przykłady
Przykład #1 oci_num_rows() example
<?php
$conn = oci_connect("scott", "tiger");
$stmt = oci_parse($conn, "create table emp2 as select * from emp");
oci_execute($stmt);
echo oci_num_rows($stmt) . " rows inserted.<br />";
oci_free_statement($stmt);
$stmt = oci_parse($conn, "delete from emp2");
oci_execute($stmt, OCI_DEFAULT);
echo oci_num_rows($stmt) . " rows deleted.<br />";
oci_commit($conn);
oci_free_statement($stmt);
$stmt = oci_parse($conn, "drop table emp2");
oci_execute($stmt);
oci_free_statement($stmt);
oci_close($conn);
?>
Notatki
Informacja:
This function does not return number of rows selected! For SELECT statements this function will return the number of rows, that were fetched to the buffer with oci_fetch*() functions.
Informacja:
In PHP versions before 5.0.0 you must use ocirowcount() instead. This name still can be used, it was left as alias of oci_num_rows() for downwards compatability. This, however, is deprecated and not recommended.
oci_parse
(PHP 5, PECL OCI8 >= 1.1.0)
oci_parse — Prepares an Oracle statement for execution
Opis
$connection
, string $sql_text
)
Prepares sql_text using
connection and returns the statement identifier,
which can be used with oci_bind_by_name(),
oci_execute() and other functions.
Statement identifiers can be freed
with oci_free_statement() or by setting the
variable to NULL.
Parametry
-
connection -
An Oracle connection identifier, returned by oci_connect(), oci_pconnect(), or oci_new_connect().
-
sql_text -
The SQL or PL/SQL statement.
SQL statements should not end with a semi-colon (";"). PL/SQL statements should end with a semi-colon (";").
Zwracane wartości
Returns a statement handle on success, or FALSE on error.
Przykłady
Przykład #1 oci_parse() example for SQL statements
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
// Parse the statement. Note there is no final semi-colon in the SQL statement
$stid = oci_parse($conn, 'SELECT * FROM employees');
oci_execute($stid);
echo "<table border='1'>\n";
while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
echo "<tr>\n";
foreach ($row as $item) {
echo " <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : " ") . "</td>\n";
}
echo "</tr>\n";
}
echo "</table>\n";
?>
Przykład #2 oci_parse() example for PL/SQL statements
<?php
/*
Before running the PHP program, create a stored procedure in
SQL*Plus or SQL Developer:
CREATE OR REPLACE PROCEDURE myproc(p1 IN NUMBER, p2 OUT NUMBER) AS
BEGIN
p2 := p1 * 2;
END;
*/
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$p1 = 8;
// When parsing PL/SQL programs, there should be a final semi-colon in the string
$stid = oci_parse($conn, 'begin myproc(:p1, :p2); end;');
oci_bind_by_name($stid, ':p1', $p1);
oci_bind_by_name($stid, ':p2', $p2, 40);
oci_execute($stid);
print "$p2\n"; // prints 16
oci_free_statement($stid);
oci_close($conn);
?>
Notatki
Informacja:
This function does not validate
sql_text. The only way to find out ifsql_textis a valid SQL or PL/SQL statement is to execute it.
Informacja:
In PHP versions before 5.0.0 use ociparse() instead. The old function name can still be used in current versions, however it is deprecated and not recommended.
Zobacz też:
- oci_execute() - Executes a statement
- oci_free_statement() - Frees all resources associated with statement or cursor
oci_password_change
(PHP 5, PECL OCI8 >= 1.1.0)
oci_password_change — Changes password of Oracle's user
Opis
$connection
, string $username
, string $old_password
, string $new_password
)$dbname
, string $username
, string $old_password
, string $new_password
)
Changes password for user with username.
The oci_password_change() function is most useful for PHP command-line scripts, or when non-persistent connections are used throughout the PHP application.
Parametry
-
connection -
An Oracle connection identifier, returned by oci_connect() or oci_pconnect().
-
username -
The Oracle user name.
-
old_password -
The old password.
-
new_password -
The new password to be set.
-
dbname -
The database name.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Notatki
Informacja:
Changing the password either with this function or directly in Oracle should be done carefully. This is because PHP applications may continue to successfully reuse persistent connections by authenticating with the old password. The best practice is to restart all web servers whenever the user password is changed.
Informacja:
If upgrading the Oracle client libraries or the database from a release prior to 11.2.0.3 to version 11.2.0.3 or higher, oci_password_change() may give the error "ORA-1017: invalid username/password" unless both client and server versions are upgraded at the same time.
Informacja: The second oci_password_change() syntax is available since OCI8 version 1.1.
Informacja:
In PHP versions before 5.0.0 you must use ocipasswordchange() instead. This name still can be used, it was left as alias of oci_password_change() for downwards compatability. This, however, is deprecated and not recommended.
oci_pconnect
(PHP 5, PECL OCI8 >= 1.1.0)
oci_pconnect — Connect to an Oracle database using a persistent connection
Opis
$username
, string $password
[, string $connection_string
[, string $character_set
[, int $session_mode
]]] )Creates a persistent connection to an Oracle server and logs on.
Persistent connections are cached and re-used between requests, resulting in reduced overhead on each page load; a typical PHP application will have a single persistent connection open against an Oracle server per Apache child process (or PHP FastCGI/CGI process). See the Persistent Database Connections section for more information.
Parametry
-
username -
The Oracle user name.
-
password -
The password for
username. -
connection_string -
Contains the Oracle instance to connect to. It can be an » Easy Connect string, or a Connect Name from the tnsnames.ora file, or the name of a local Oracle instance.
If not specified, PHP uses environment variables such as
TWO_TASK(on Linux) orLOCAL(on Windows) andORACLE_SIDto determine the Oracle instance to connect to.To use the Easy Connect naming method, PHP must be linked with Oracle 10g or greater Client libraries. The Easy Connect string for Oracle 10g is of the form: [//]host_name[:port][/service_name]. With Oracle 11g, the syntax is: [//]host_name[:port][/service_name][:server_type][/instance_name]. Service names can be found by running the Oracle utility lsnrctl status on the database server machine.
The tnsnames.ora file can be in the Oracle Net search path, which includes $ORACLE_HOME/network/admin and /etc. Alternatively set TNS_ADMIN so that $TNS_ADMIN/tnsnames.ora is read. Make sure the web daemon has read access to the file.
-
character_set -
Determines the character set used by the Oracle Client libraries. The character set does not need to match the character set used by the database. If it doesn't match, Oracle will do its best to convert data to and from the database character set. Depending on the character sets this may not give usable results. Conversion also adds some time overhead.
If not specified, the Oracle Client libraries determine a character set from the
NLS_LANGenvironment variable.Passing this parameter can reduce connection time.
-
session_mode -
This parameter is available since version PHP 5 (PECL OCI8 1.1) and accepts the following values:
OCI_DEFAULT,OCI_SYSOPERandOCI_SYSDBA. If eitherOCI_SYSOPERorOCI_SYSDBAwere specified, this function will try to establish privileged connection using external credentials. Privileged connections are disabled by default. To enable them you need to set oci8.privileged_connect to On.PHP 5.3 (PECL OCI8 1.3.4) introduced the
OCI_CRED_EXTmode value. This tells Oracle to use External or OS authentication, which must be configured in the database. TheOCI_CRED_EXTflag can only be used with username of "/" and a empty password. oci8.privileged_connect may be On or Off.OCI_CRED_EXTmay be combined with theOCI_SYSOPERorOCI_SYSDBAmodes.OCI_CRED_EXTis not supported on Windows for security reasons.
Zwracane wartości
Returns a connection identifier or FALSE on error.
Notatki
Informacja: Starting with PHP 5.1.2 and PECL oci8 1.1, the lifetime and maximum number of persistent Oracle connections can be tuned by setting the following configuration values: oci8.persistent_timeout, oci8.ping_interval and oci8.max_persistent.
Informacja:
In PHP versions before 5.0.0 you must use ociplogon() instead. The old function name can still be used in current versions, however it is deprecated and not recommended.
Zobacz też:
- oci_connect() - Connect to an Oracle database
- oci_new_connect() - Connect to the Oracle server using a unique connection
oci_result
(PHP 5, PECL OCI8 >= 1.1.0)
oci_result — Returns field's value from the fetched row
Opis
Returns the data from field in the current row,
fetched by oci_fetch().
For details on the data type mapping performed by the OCI8 extension, see the datatypes supported by the driver
Parametry
-
statement -
-
field -
Can be either use the column number (1-based) or the column name (in uppercase).
Zwracane wartości
Returns everything as strings except for abstract types (ROWIDs, LOBs and
FILEs). Returns FALSE on error.
Notatki
Informacja:
In PHP versions before 5.0.0 you must use ociresult() instead. This name still can be used, it was left as alias of oci_result() for downwards compatability. This, however, is deprecated and not recommended.
Zobacz też:
- oci_fetch_array() - Returns the next row from a query as an associative or numeric array
- oci_fetch_assoc() - Returns the next row from a query as an associative array
- oci_fetch_object() - Returns the next row from a query as an object
- oci_fetch_row() - Returns the next row from a query as a numeric array
- oci_fetch_all() - Fetches multiple rows from a query into a two-dimensional array
oci_rollback
(PHP 5, PECL OCI8 >= 1.1.0)
oci_rollback — Rolls back the outstanding database transaction
Opis
$connection
)
Reverts all uncommitted changes for the Oracle
connection and ends the transaction. It
releases all locks held. All Oracle SAVEPOINTS
are erased.
A transaction begins when the first SQL statement that changes data
is executed with oci_execute() using
the OCI_NO_AUTO_COMMIT flag. Further data
changes made by other statements become part of the same
transaction. Data changes made in a transaction are temporary
until the transaction is committed or rolled back. Other users of
the database will not see the changes until they are committed.
When inserting or updating data, using transactions is recommended for relational data consistency and for performance reasons.
Parametry
-
connection -
An Oracle connection identifier, returned by oci_connect(), oci_pconnect() or oci_new_connect().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 oci_rollback() example
<?php
// Insert into several tables, rolling back the changes if an error occurs
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
$stid = oci_parse($conn, "INSERT INTO mysalary (id, name) VALUES (1, 'Chris')");
// The OCI_NO_AUTO_COMMIT flag tells Oracle not to commit the INSERT immediately
// Use OCI_DEFAULT as the flag for PHP <= 5.3.1. The two flags are equivalent
$r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
if (!$r) {
$e = oci_error($stid);
trigger_error(htmlentities($e['message']), E_USER_ERROR);
}
$stid = oci_parse($conn, 'INSERT INTO myschedule (startday) VALUES (12)');
$r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
if (!$r) {
$e = oci_error($stid);
oci_rollback($conn); // rollback changes to both tables
trigger_error(htmlentities($e['message']), E_USER_ERROR);
}
// Commit the changes to both tables
$r = oci_commit($conn);
if (!r) {
$e = oci_error($conn);
trigger_error(htmlentities($e['message']), E_USER_ERROR);
}
?>
Przykład #2 Rolling back to a SAVEPOINT example
<?php
$stid = oci_parse($conn, 'UPDATE mytab SET id = 1111');
oci_execute($stid, OCI_NO_AUTO_COMMIT);
// Create the savepoint
$stid = oci_parse($conn, 'SAVEPOINT mysavepoint');
oci_execute($stid, OCI_NO_AUTO_COMMIT);
$stid = oci_parse($conn, 'UPDATE mytab SET id = 2222');
oci_execute($stid, OCI_NO_AUTO_COMMIT);
// Use an explicit SQL statement to rollback to the savepoint
$stid = oci_parse($conn, 'ROLLBACK TO SAVEPOINT mysavepoint');
oci_execute($stid, OCI_NO_AUTO_COMMIT);
oci_commit($conn); // mytab now has id of 1111
?>
Notatki
Informacja:
Transactions are automatically rolled back when you close the connection, or when the script ends, whichever is soonest. You need to explicitly call oci_commit() to commit the transaction.
Any call to oci_execute() that uses
OCI_COMMIT_ON_SUCCESSmode explicitly or by default will commit any previous uncommitted transaction.Any Oracle DDL statement such as CREATE or DROP will automatically commit any uncommitted transaction.
Informacja:
In PHP versions before 5.0.0 you must use ocirollback() instead. The old function name can still be used in current versions, however it is deprecated and not recommended.
Zobacz też:
- oci_commit() - Commits the outstanding database transaction
- oci_execute() - Executes a statement
oci_server_version
(PHP 5, PECL OCI8 >= 1.1.0)
oci_server_version — Returns the Oracle Database version
Opis
$connection
)Returns a string with the Oracle Database version and available options
Parametry
-
connection -
Zwracane wartości
Returns the version information as a string or FALSE on error.
Przykłady
Przykład #1 oci_server_version() example
<?php
$conn = oci_connect("scott", "tiger");
echo "Server Version: " . oci_server_version($conn);
// Displays:
// Server Version: Oracle Database 11g Enterprise Edition Release 11.2.0.1.0 - 64bit Production
// With the Partitioning, OLAP, Data Mining and Real Application Testing option
oci_close($conn);
?>
Notatki
Informacja:
In PHP versions before 5.0.0 you must use ociserverversion() instead. This old name still can be used. However it is deprecated and not recommended.
oci_set_action
(PHP 5.3.2, PECL OCI8 >= 1.4.0)
oci_set_action — Sets the action name
Opis
$connection
, string $action_name
)Sets the action name for Oracle tracing.
The action name is registered with the database when the next 'roundtrip' from PHP to the database occurs, typically when an SQL statement is executed.
The action name can subsequently be queried from database administration views such as V$SESSION. It can be used for tracing and monitoring such as with V$SQLAREA and DBMS_MONITOR.SERV_MOD_ACT_STAT_ENABLE.
The value may be retained across persistent connections.
Parametry
-
connection -
An Oracle connection identifier, returned by oci_connect(), oci_pconnect(), or oci_new_connect().
-
action_name -
User chosen string up to 32 bytes long.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Setting the action
<?php
$c = oci_connect('hr', 'welcome', 'localhost/XE');
// Record the action
oci_set_action($c, 'Friend Lookup');
// Code that causes a roundtrip, for example a query:
$s = oci_parse($c, 'select * from dual');
oci_execute($s);
oci_fetch_all($s, $res);
sleep(30);
?>
// While the script is running, the administrator can see the actions // being performed: sqlplus system/welcome SQL> select action from v$session;
Notatki
Informacja: Oracle version requirement
This function is available when PHP is linked with Oracle Database libraries from version 10g onwards.
Performance
With older versions of OCI8 or the Oracle Database, the client information can be set using the Oracle DBMS_APPLICATION_INFO package. This is less efficient than using oci_set_client_info().
Roundtrip Gotcha
Some but not all OCI8 functions cause roundtrips. Roundtrips to the database may not occur with queries when result caching is enabled.
Zobacz też:
- oci_set_module_name() - Sets the module name
- oci_set_client_info() - Sets the client information
- oci_set_client_identifier() - Sets the client identifier
oci_set_client_identifier
(PHP 5.3.2, PECL OCI8 >= 1.4.0)
oci_set_client_identifier — Sets the client identifier
Opis
$connection
, string $client_identifier
)Sets the client identifier used by various database components to identify lightweight application users who authenticate as the same database user.
The client identifier is registered with the database when the next 'roundtrip' from PHP to the database occurs, typically when an SQL statement is executed.
The identifier can subsequently be queried from database administration views such as V$SESSION. It can be used with DBMS_MONITOR.CLIENT_ID_TRACE_ENABLE for tracing. It can be used for auditing.
The value may be retained across persistent connections.
Parametry
-
connection -
An Oracle connection identifier, returned by oci_connect(), oci_pconnect(), or oci_new_connect().
-
client_identifier -
User chosen string up to 64 bytes long.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Setting the client identifier to the application user
<?php
// Find the application user's login name
session_start();
$un = my_validate_session($_SESSION['username']);
$c = oci_connect('myschema', 'welcome', 'localhost/XE');
// Tell Oracle who that user is
oci_set_client_identifier($c, $un);
// The next roundtrip to the database will piggyback the identifier
$s = oci_parse($c, 'select mydata from mytable');
oci_execute($s);
// ...
?>
Notatki
Roundtrip Gotcha
Some but not all OCI8 functions cause roundtrips. Roundtrips to the database may not occur with queries when result caching is enabled.
Zobacz też:
- oci_set_module_name() - Sets the module name
- oci_set_action() - Sets the action name
- oci_set_client_info() - Sets the client information
oci_set_client_info
(PHP 5.3.2, PECL OCI8 >= 1.4.0)
oci_set_client_info — Sets the client information
Opis
$connection
, string $client_info
)Sets the client information for Oracle tracing.
The client information is registered with the database when the next 'roundtrip' from PHP to the database occurs, typically when an SQL statement is executed.
The client information can subsequently be queried from database administration views such as V$SESSION.
The value may be retained across persistent connections.
Parametry
-
An Oracle connection identifier, returned by oci_connect(), oci_pconnect(), or oci_new_connect().
-
User chosen string up to 64 bytes long.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Setting the client information
<?php
$c = oci_connect('hr', 'welcome', 'localhost/XE');
// Record the client information
oci_set_client_info($c, 'My Application Version 2');
// Code that causes a roundtrip, for example a query:
$s = oci_parse($c, 'select * from dual');
oci_execute($s);
oci_fetch_all($s, $res);
sleep(30);
?>
// While the script is running, the administrator can see the client // information: sqlplus system/welcome SQL> select client_info from v$session;
Notatki
Informacja: Oracle version requirement
This function is available when PHP is linked with Oracle Database libraries from version 10g onwards.
Performance
With older versions of OCI8 or the Oracle Database, the client information can be set using the Oracle DBMS_APPLICATION_INFO package. This is less efficient than using oci_set_client_info().
Roundtrip Gotcha
Some but not all OCI8 functions cause roundtrips. Roundtrips to the database may not occur with queries when result caching is enabled.
Zobacz też:
- oci_set_module_name() - Sets the module name
- oci_set_action() - Sets the action name
- oci_set_client_identifier() - Sets the client identifier
oci_set_edition
(PHP 5.3.2, PECL OCI8 >= 1.4.0)
oci_set_edition — Sets the database edition
Opis
$edition
)Sets the database "edition" of objects to be used by a subsequent connections.
Oracle Editions allow concurrent versions of applications to run using the same schema and object names. This is useful for upgrading live systems.
Call oci_set_edition() before calling oci_connect(), oci_pconnect() or oci_new_connect().
If an edition is set that is not valid in the database, connection will fail even if oci_set_edition() returns success.
When using persistent connections, if a connection with the requested edition setting already exists, it is reused. Otherwise, a different persistent connection is created
Parametry
-
edition -
Oracle Database edition name previously created with the SQL "CREATE EDITION" command.
Notatki
Informacja: Oracle version requirement
This function is available from Oracle 11gR2 onwards.
Persistent connections
To avoid inconsistencies and unexpected errors, do not use ALTER SESSION SET EDITION to change the edition on persistent connections.
DRCP Connection Pooling
To avoid inconsistencies and unexpected errors when using editions and DRCP with Oracle 11.2.0.1, keep a one-to-one correspondence between the oci8.connection_class and the edition name used by applications. Each pooled server of a given connection class should only be used with one edition. This restriction has been removed with Oracle 11.2.0.2.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Two scripts can use different versions of myfunc() at the same time
<?php
// File 1
echo "Version 1 of application\n";
oci_set_edition('ORA$BASE');
$c = oci_connect('hr', 'welcome', 'localhost/XE');
$s = oci_parse($c, "begin :r := myfunc(); end;");
oci_bind_by_name($s, ":r", $r, 20);
oci_execute($s);
echo "The result is $r\n";
?>
<?php
// File 2
echo "Version 2 of application\n";
oci_set_edition('E1');
$c = oci_connect('hr', 'welcome', 'localhost/XE');
$s = oci_parse($c, "begin :r := myfunc(); end;");
oci_bind_by_name($s, ":r", $r, 20);
oci_execute($s);
echo "The result is $r\n";
?>
oci_set_module_name
(PHP 5.3.2, PECL OCI8 >= 1.4.0)
oci_set_module_name — Sets the module name
Opis
$connection
, string $module_name
)Sets the module name for Oracle tracing.
The module name is registered with the database when the next 'roundtrip' from PHP to the database occurs, typically when an SQL statement is executed.
The name can subsequently be queried from database administration views such as V$SESSION. It can be used for tracing and monitoring such as with V$SQLAREA and DBMS_MONITOR.SERV_MOD_ACT_STAT_ENABLE.
The value may be retained across persistent connections.
Parametry
-
connection -
An Oracle connection identifier, returned by oci_connect(), oci_pconnect(), or oci_new_connect().
-
module_name -
User chosen string up to 48 bytes long.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Notatki
Informacja: Oracle version requirement
This function is available when PHP is linked with Oracle Database libraries from version 10g onwards.
Performance
With older versions of OCI8 or the Oracle Database, the client information can be set using the Oracle DBMS_APPLICATION_INFO package. This is less efficient than using oci_set_client_info().
Roundtrip Gotcha
Some but not all OCI8 functions cause roundtrips. Roundtrips to the database may not occur with queries when result caching is enabled.
Przykłady
Przykład #1 Setting the module name
<?php
$c = oci_connect('hr', 'welcome', 'localhost/XE');
// Record the module
oci_set_module_name($c, 'Home Page');
// Code that causes a roundtrip, for example a query:
$s = oci_parse($c, 'select * from dual');
oci_execute($s);
oci_fetch_all($s, $res);
sleep(30);
?>
// While the script is running, the administrator can see the // modules in use: sqlplus system/welcome SQL> select module from v$session;
Zobacz też:
- oci_set_action() - Sets the action name
- oci_set_client_info() - Sets the client information
- oci_set_client_identifier() - Sets the client identifier
oci_set_prefetch
(PHP 5, PECL OCI8 >= 1.1.0)
oci_set_prefetch — Sets number of rows to be prefetched by queries
Opis
$statement
, int $rows
)Sets the number of rows to be buffered by the Oracle Client libraries after a successful query call to oci_execute() and for each subsequent internal fetch request to the database. For queries returning a large number of rows, performance can be significantly improved by increasing the prefetch count above the default oci8.default_prefetch value.
Prefetching is Oracle's efficient way of returning more than one data row from the database in each network request. This can result in better network and CPU utilization. The buffering of rows is internal to OCI8 and the behavior of OCI8 fetching functions is unchanged regardless of the prefetch count. For example, oci_fetch_row() will always return one row. The prefetch buffer is per-statement and is not used by re-executed statements or by other connections.
Call oci_set_prefetch() before calling oci_execute().
A tuning goal is to set the prefetch value to a reasonable size for the network and database to handle. For queries returning a very large number of rows, overall system efficiency might be better if rows are retrieved from the database in several chunks (i.e set the prefetch value smaller than the number of rows). This allows the database to handle other users' statements while the PHP script is processing the current set of rows.
Query prefetching was introduced in Oracle 8i. REF CURSOR prefetching was introduced in Oracle 11gR2 and occurs when PHP is linked with Oracle 11gR2 Client libraries and connected to 11gR2 or previous versions of the database. Nested cursor prefetching was introduced in Oracle 11gR2 and requires both the Oracle Client libraries and the database to be version 11gR2.
Prefetching is not supported when queries contain LONG or LOB columns. The prefetch value is ignored and single-row fetches will be used in all the situations when prefetching is not supported.
Parametry
-
statement -
A valid OCI8 statement identifier created by oci_parse() and executed by oci_execute(), or a REF CURSOR statement identifier.
-
rows -
The number of rows to be prefetched, >= 0
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Rejestr zmian
| Wersja | Opis |
|---|---|
| PHP 5.3.2 (PECL OCI8 1.4) |
Before this release, rows must be >= 1.
|
| PHP 5.3 (PECL OCI8 1.3.4) |
Before this release, prefetching was limited to the lesser
of rows rows and 1024
* rows bytes. The byte size
restriction has now been removed.
|
Przykłady
Przykład #1 Changing the default prefetch value for a query
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
$stid = oci_parse($conn, 'SELECT * FROM myverybigtable');
oci_set_prefetch($stid, 300); // Set before calling oci_execute()
oci_execute($stid);
echo "<table border='1'>\n";
while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
echo "<tr>\n";
foreach ($row as $item) {
echo " <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : " ")."</td>\n";
}
echo "</tr>\n";
}
echo "</table>\n";
oci_free_statement($stid);
oci_close($conn);
?>
Przykład #2 Changing the default prefetch for a REF CURSOR fetch
<?php
/*
Create the PL/SQL stored procedure as:
CREATE OR REPLACE PROCEDURE myproc(p1 OUT SYS_REFCURSOR) AS
BEGIN
OPEN p1 FOR SELECT * FROM all_objects WHERE ROWNUM < 5000;
END;
*/
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
$stid = oci_parse($conn, 'BEGIN myproc(:rc); END;');
$refcur = oci_new_cursor($conn);
oci_bind_by_name($stid, ':rc', $refcur, -1, OCI_B_CURSOR);
oci_execute($stid);
// Change the prefetch before executing the cursor.
// REF CURSOR prefetching works when PHP is linked with Oracle 11gR2 Client libraries
oci_set_prefetch($refcur, 200);
oci_execute($refcur);
echo "<table border='1'>\n";
while ($row = oci_fetch_array($refcur, OCI_ASSOC+OCI_RETURN_NULLS)) {
echo "<tr>\n";
foreach ($row as $item) {
echo " <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : " ")."</td>\n";
}
echo "</tr>\n";
}
echo "</table>\n";
oci_free_statement($refcur);
oci_free_statement($stid);
oci_close($conn);
?>
If PHP OCI8 fetches from a REF CURSOR and then passes the REF
CURSOR back to a second PL/SQL procedure for further processing,
then set the REF CURSOR prefetch count to 0 to
avoid rows being "lost" from the result set. The prefetch value is
the number of extra rows fetched in each OCI8 internal request to
the database, so setting it to 0 means only
fetch one row at a time.
Przykład #3 Setting the prefetch value when passing a REF CURSOR back to Oracle
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/orcl');
// get the REF CURSOR
$stid = oci_parse($conn, 'BEGIN myproc(:rc_out); END;');
$refcur = oci_new_cursor($conn);
oci_bind_by_name($stid, ':rc_out', $refcur, -1, OCI_B_CURSOR);
oci_execute($stid);
// Display two rows, but don't prefetch any extra rows otherwise
// those extra rows would not be passed back to myproc_use_rc().
// A prefetch value of 0 is allowed in PHP 5.3.2 and PECL OCI8 1.4
oci_set_prefetch($refcur, 0);
oci_execute($refcur);
$row = oci_fetch_array($refcur);
var_dump($row);
$row = oci_fetch_array($refcur);
var_dump($row);
// pass the REF CURSOR to myproc_use_rc() to do more data processing
// with the result set
$stid = oci_parse($conn, 'begin myproc_use_rc(:rc_in); end;');
oci_bind_by_name($stid, ':rc_in', $refcur, -1, OCI_B_CURSOR);
oci_execute($stid);
?>
Notatki
Informacja:
In PHP versions before 5.0.0 use ocisetprefetch() instead. The old function name can still be used in current versions, however it is deprecated and not recommended.
oci_statement_type
(PHP 5, PECL OCI8 >= 1.1.0)
oci_statement_type — Returns the type of a statement
Opis
$statement
)
Returns a keyword identifying the type of the
OCI8 statement.
Zwracane wartości
Returns the type of statement as one of the
following strings.
| Return String | Notes |
|---|---|
| ALTER | |
| BEGIN | |
| CALL | Introduced in PHP 5.2.1 (PECL OCI8 1.2.3) |
| CREATE | |
| DECLARE | |
| DELETE | |
| DROP | |
| INSERT | |
| SELECT | |
| UPDATE | |
| UNKNOWN |
Returns FALSE on error.
Przykłady
Przykład #1 oci_statement_type() example
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
$stid = oci_parse($conn, 'DELETE FROM departments WHERE department_id = 130;');
if (oci_statement_type($stid) == "DELETE") {
trigger_error('You are not allowed to delete from this table', E_USER_ERROR);
}
else {
oci_execute($stid); // delete the row
}
oci_free_statement($stid);
oci_close($conn);
?>
Notatki
Informacja:
In PHP versions before 5.0.0 you must use ocistatementtype() instead. The old function name can still be used in current versions, however it is deprecated and not recommended.
Spis treści
- OCI-Collection::append — Appends element to the collection
- OCI-Collection::assign — Assigns a value to the collection from another existing collection
- OCI-Collection::assignElem — Assigns a value to the element of the collection
- OCI-Collection::free — Frees the resources associated with the collection object
- OCI-Collection::getElem — Returns value of the element
- OCI-Collection::max — Returns the maximum number of elements in the collection
- OCI-Collection::size — Returns size of the collection
- OCI-Collection::trim — Trims elements from the end of the collection
- OCI-Lob::append — Appends data from the large object to another large object
- OCI-Lob::close — Closes LOB descriptor
- OCI-Lob::eof — Tests for end-of-file on a large object's descriptor
- OCI-Lob::erase — Erases a specified portion of the internal LOB data
- OCI-Lob::export — Exports LOB's contents to a file
- OCI-Lob::flush — Flushes/writes buffer of the LOB to the server
- OCI-Lob::free — Frees resources associated with the LOB descriptor
- OCI-Lob::getBuffering — Returns current state of buffering for the large object
- OCI-Lob::import — Imports file data to the LOB
- OCI-Lob::load — Returns large object's contents
- OCI-Lob::read — Reads part of the large object
- OCI-Lob::rewind — Moves the internal pointer to the beginning of the large object
- OCI-Lob::save — Saves data to the large object
- OCI-Lob::saveFile — Alias dla OCI-Lob::import
- OCI-Lob::seek — Sets the internal pointer of the large object
- OCI-Lob::setBuffering — Changes current state of buffering for the large object
- OCI-Lob::size — Returns size of large object
- OCI-Lob::tell — Returns the current position of internal pointer of large object
- OCI-Lob::truncate — Truncates large object
- OCI-Lob::write — Writes data to the large object
- OCI-Lob::writeTemporary — Writes a temporary large object
- OCI-Lob::writeToFile — Alias dla OCI-Lob::export
- oci_bind_array_by_name — Binds a PHP array to an Oracle PL/SQL array parameter
- oci_bind_by_name — Binds a PHP variable to an Oracle placeholder
- oci_cancel — Anuluje odczytywanie z kursora
- oci_client_version — Returns the Oracle client library version
- oci_close — Closes an Oracle connection
- oci_commit — Commits the outstanding database transaction
- oci_connect — Connect to an Oracle database
- oci_define_by_name — Associates a PHP variable with a column for query fetches
- oci_error — Returns the last error found
- oci_execute — Executes a statement
- oci_fetch_all — Fetches multiple rows from a query into a two-dimensional array
- oci_fetch_array — Returns the next row from a query as an associative or numeric array
- oci_fetch_assoc — Returns the next row from a query as an associative array
- oci_fetch_object — Returns the next row from a query as an object
- oci_fetch_row — Returns the next row from a query as a numeric array
- oci_fetch — Fetches the next row from a query into internal buffers
- oci_field_is_null — Checks if the field is NULL
- oci_field_name — Returns the name of a field from the statement
- oci_field_precision — Tell the precision of a field
- oci_field_scale — Tell the scale of the field
- oci_field_size — Returns field's size
- oci_field_type_raw — Tell the raw Oracle data type of the field
- oci_field_type — Returns field's data type
- oci_free_statement — Frees all resources associated with statement or cursor
- oci_internal_debug — Enables or disables internal debug output
- oci_lob_copy — Copies large object
- oci_lob_is_equal — Compares two LOB/FILE locators for equality
- oci_new_collection — Allocates new collection object
- oci_new_connect — Connect to the Oracle server using a unique connection
- oci_new_cursor — Allocates and returns a new cursor (statement handle)
- oci_new_descriptor — Initializes a new empty LOB or FILE descriptor
- oci_num_fields — Returns the number of result columns in a statement
- oci_num_rows — Returns number of rows affected during statement execution
- oci_parse — Prepares an Oracle statement for execution
- oci_password_change — Changes password of Oracle's user
- oci_pconnect — Connect to an Oracle database using a persistent connection
- oci_result — Returns field's value from the fetched row
- oci_rollback — Rolls back the outstanding database transaction
- oci_server_version — Returns the Oracle Database version
- oci_set_action — Sets the action name
- oci_set_client_identifier — Sets the client identifier
- oci_set_client_info — Sets the client information
- oci_set_edition — Sets the database edition
- oci_set_module_name — Sets the module name
- oci_set_prefetch — Sets number of rows to be prefetched by queries
- oci_statement_type — Returns the type of a statement
OCI8 Obsolete Aliases and Functions
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
ocicollappend
(PHP 4 >= 4.0.6, PHP 5, PECL OCI8 >= 1.0.0)
ocicollappend — Alias dla OCI-Collection::append()
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
ocicollassignelem
(PHP 4 >= 4.0.6, PHP 5, PECL OCI8 >= 1.0.0)
ocicollassignelem — Alias dla OCI-Collection::assignElem()
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
ocicollgetelem
(PHP 4 >= 4.0.6, PHP 5, PECL OCI8 >= 1.0.0)
ocicollgetelem — Alias dla OCI-Collection::getElem()
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
ocicollsize
(PHP 4 >= 4.0.6, PHP 5, PECL OCI8 >= 1.0.0)
ocicollsize — Alias dla OCI-Collection::size()
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
ocicolltrim
(PHP 4 >= 4.0.6, PHP 5, PECL OCI8 >= 1.0.0)
ocicolltrim — Alias dla OCI-Collection::trim()
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
ocicolumnprecision
(PHP 4, PHP 5, PECL OCI8 >= 1.0.0)
ocicolumnprecision — Alias dla oci_field_precision()
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
ocicolumntyperaw
(PHP 4, PHP 5, PECL OCI8 >= 1.0.0)
ocicolumntyperaw — Alias dla oci_field_type_raw()
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
ocifetchinto
(PHP 4, PHP 5, PECL OCI8 >= 1.0.0)
ocifetchinto — Fetches the next row into an array (deprecated)
Opis
$statement
, array &$result
[, int $mode = OCI_ASSOC + OCI_NUM
] )This function is deprecated. Recommended alternatives: oci_fetch_array(), oci_fetch_object(), oci_fetch_assoc() and oci_fetch_row().
This function has been DEPRECATED as of PHP 5.4.0. Relying on this function is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
ocifreecollection
(PHP 4 >= 4.0.7, PHP 5, PECL OCI8 >= 1.0.0)
ocifreecollection — Alias dla OCI-Collection::free()
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
ocifreestatement
(PHP 4, PHP 5, PECL OCI8 >= 1.0.0)
ocifreestatement — Alias dla oci_free_statement()
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
ociinternaldebug
(PHP 4, PHP 5, PECL OCI8 >= 1.0.0)
ociinternaldebug — Alias dla oci_internal_debug()
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
ocinewcollection
(PHP 4 >= 4.0.6, PHP 5, PECL OCI8 >= 1.0.0)
ocinewcollection — Alias dla oci_new_collection()
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
ocinewdescriptor
(PHP 4, PHP 5, PECL OCI8 >= 1.0.0)
ocinewdescriptor — Alias dla oci_new_descriptor()
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
ociserverversion
(PHP 4, PHP 5, PECL OCI8 >= 1.0.0)
ociserverversion — Alias dla oci_server_version()
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
ocistatementtype
(PHP 4, PHP 5, PECL OCI8 >= 1.0.0)
ocistatementtype — Alias dla oci_statement_type()
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
ociwritetemporarylob
(PHP 4 >= 4.0.6, PECL OCI8 1.0)
ociwritetemporarylob — Alias dla OCI-Lob::writeTemporary()
Opis
This alias has been DEPRECATED as of PHP 5.4.0. Relying on this alias is highly discouraged.
Spis treści
- ocibindbyname — Alias dla oci_bind_by_name
- ocicancel — Alias dla oci_cancel
- ocicloselob — Alias dla OCI-Lob::close
- ocicollappend — Alias dla OCI-Collection::append
- ocicollassign — Alias dla OCI-Collection::assign
- ocicollassignelem — Alias dla OCI-Collection::assignElem
- ocicollgetelem — Alias dla OCI-Collection::getElem
- ocicollmax — Alias dla OCI-Collection::max
- ocicollsize — Alias dla OCI-Collection::size
- ocicolltrim — Alias dla OCI-Collection::trim
- ocicolumnisnull — Alias dla oci_field_is_null
- ocicolumnname — Alias dla oci_field_name
- ocicolumnprecision — Alias dla oci_field_precision
- ocicolumnscale — Alias dla oci_field_scale
- ocicolumnsize — Alias dla oci_field_size
- ocicolumntype — Alias dla oci_field_type
- ocicolumntyperaw — Alias dla oci_field_type_raw
- ocicommit — Alias dla oci_commit
- ocidefinebyname — Alias dla oci_define_by_name
- ocierror — Alias dla oci_error
- ociexecute — Alias dla oci_execute
- ocifetch — Alias dla oci_fetch
- ocifetchinto — Fetches the next row into an array (deprecated)
- ocifetchstatement — Alias dla oci_fetch_all
- ocifreecollection — Alias dla OCI-Collection::free
- ocifreecursor — Alias dla oci_free_statement
- ocifreedesc — Alias dla OCI-Lob::free
- ocifreestatement — Alias dla oci_free_statement
- ociinternaldebug — Alias dla oci_internal_debug
- ociloadlob — Alias dla OCI-Lob::load
- ocilogoff — Alias dla oci_close
- ocilogon — Alias dla oci_connect
- ocinewcollection — Alias dla oci_new_collection
- ocinewcursor — Alias dla oci_new_cursor
- ocinewdescriptor — Alias dla oci_new_descriptor
- ocinlogon — Alias dla oci_new_connect
- ocinumcols — Alias dla oci_num_fields
- ociparse — Alias dla oci_parse
- ociplogon — Alias dla oci_pconnect
- ociresult — Alias dla oci_result
- ocirollback — Alias dla oci_rollback
- ocirowcount — Alias dla oci_num_rows
- ocisavelob — Alias dla OCI-Lob::save
- ocisavelobfile — Alias dla OCI-Lob::import
- ociserverversion — Alias dla oci_server_version
- ocisetprefetch — Alias dla oci_set_prefetch
- ocistatementtype — Alias dla oci_statement_type
- ociwritelobtofile — Alias dla OCI-Lob::export
- ociwritetemporarylob — Alias dla OCI-Lob::writeTemporary
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Przykłady
- Connection Handling
- Supported Datatypes
- OCI8 Funkcje
- OCI-Collection::append — Appends element to the collection
- OCI-Collection::assign — Assigns a value to the collection from another existing collection
- OCI-Collection::assignElem — Assigns a value to the element of the collection
- OCI-Collection::free — Frees the resources associated with the collection object
- OCI-Collection::getElem — Returns value of the element
- OCI-Collection::max — Returns the maximum number of elements in the collection
- OCI-Collection::size — Returns size of the collection
- OCI-Collection::trim — Trims elements from the end of the collection
- OCI-Lob::append — Appends data from the large object to another large object
- OCI-Lob::close — Closes LOB descriptor
- OCI-Lob::eof — Tests for end-of-file on a large object's descriptor
- OCI-Lob::erase — Erases a specified portion of the internal LOB data
- OCI-Lob::export — Exports LOB's contents to a file
- OCI-Lob::flush — Flushes/writes buffer of the LOB to the server
- OCI-Lob::free — Frees resources associated with the LOB descriptor
- OCI-Lob::getBuffering — Returns current state of buffering for the large object
- OCI-Lob::import — Imports file data to the LOB
- OCI-Lob::load — Returns large object's contents
- OCI-Lob::read — Reads part of the large object
- OCI-Lob::rewind — Moves the internal pointer to the beginning of the large object
- OCI-Lob::save — Saves data to the large object
- OCI-Lob::saveFile — Alias dla OCI-Lob::import
- OCI-Lob::seek — Sets the internal pointer of the large object
- OCI-Lob::setBuffering — Changes current state of buffering for the large object
- OCI-Lob::size — Returns size of large object
- OCI-Lob::tell — Returns the current position of internal pointer of large object
- OCI-Lob::truncate — Truncates large object
- OCI-Lob::write — Writes data to the large object
- OCI-Lob::writeTemporary — Writes a temporary large object
- OCI-Lob::writeToFile — Alias dla OCI-Lob::export
- oci_bind_array_by_name — Binds a PHP array to an Oracle PL/SQL array parameter
- oci_bind_by_name — Binds a PHP variable to an Oracle placeholder
- oci_cancel — Anuluje odczytywanie z kursora
- oci_client_version — Returns the Oracle client library version
- oci_close — Closes an Oracle connection
- oci_commit — Commits the outstanding database transaction
- oci_connect — Connect to an Oracle database
- oci_define_by_name — Associates a PHP variable with a column for query fetches
- oci_error — Returns the last error found
- oci_execute — Executes a statement
- oci_fetch_all — Fetches multiple rows from a query into a two-dimensional array
- oci_fetch_array — Returns the next row from a query as an associative or numeric array
- oci_fetch_assoc — Returns the next row from a query as an associative array
- oci_fetch_object — Returns the next row from a query as an object
- oci_fetch_row — Returns the next row from a query as a numeric array
- oci_fetch — Fetches the next row from a query into internal buffers
- oci_field_is_null — Checks if the field is NULL
- oci_field_name — Returns the name of a field from the statement
- oci_field_precision — Tell the precision of a field
- oci_field_scale — Tell the scale of the field
- oci_field_size — Returns field's size
- oci_field_type_raw — Tell the raw Oracle data type of the field
- oci_field_type — Returns field's data type
- oci_free_statement — Frees all resources associated with statement or cursor
- oci_internal_debug — Enables or disables internal debug output
- oci_lob_copy — Copies large object
- oci_lob_is_equal — Compares two LOB/FILE locators for equality
- oci_new_collection — Allocates new collection object
- oci_new_connect — Connect to the Oracle server using a unique connection
- oci_new_cursor — Allocates and returns a new cursor (statement handle)
- oci_new_descriptor — Initializes a new empty LOB or FILE descriptor
- oci_num_fields — Returns the number of result columns in a statement
- oci_num_rows — Returns number of rows affected during statement execution
- oci_parse — Prepares an Oracle statement for execution
- oci_password_change — Changes password of Oracle's user
- oci_pconnect — Connect to an Oracle database using a persistent connection
- oci_result — Returns field's value from the fetched row
- oci_rollback — Rolls back the outstanding database transaction
- oci_server_version — Returns the Oracle Database version
- oci_set_action — Sets the action name
- oci_set_client_identifier — Sets the client identifier
- oci_set_client_info — Sets the client information
- oci_set_edition — Sets the database edition
- oci_set_module_name — Sets the module name
- oci_set_prefetch — Sets number of rows to be prefetched by queries
- oci_statement_type — Returns the type of a statement
- OCI8 Obsolete Aliases and Functions
- ocibindbyname — Alias dla oci_bind_by_name
- ocicancel — Alias dla oci_cancel
- ocicloselob — Alias dla OCI-Lob::close
- ocicollappend — Alias dla OCI-Collection::append
- ocicollassign — Alias dla OCI-Collection::assign
- ocicollassignelem — Alias dla OCI-Collection::assignElem
- ocicollgetelem — Alias dla OCI-Collection::getElem
- ocicollmax — Alias dla OCI-Collection::max
- ocicollsize — Alias dla OCI-Collection::size
- ocicolltrim — Alias dla OCI-Collection::trim
- ocicolumnisnull — Alias dla oci_field_is_null
- ocicolumnname — Alias dla oci_field_name
- ocicolumnprecision — Alias dla oci_field_precision
- ocicolumnscale — Alias dla oci_field_scale
- ocicolumnsize — Alias dla oci_field_size
- ocicolumntype — Alias dla oci_field_type
- ocicolumntyperaw — Alias dla oci_field_type_raw
- ocicommit — Alias dla oci_commit
- ocidefinebyname — Alias dla oci_define_by_name
- ocierror — Alias dla oci_error
- ociexecute — Alias dla oci_execute
- ocifetch — Alias dla oci_fetch
- ocifetchinto — Fetches the next row into an array (deprecated)
- ocifetchstatement — Alias dla oci_fetch_all
- ocifreecollection — Alias dla OCI-Collection::free
- ocifreecursor — Alias dla oci_free_statement
- ocifreedesc — Alias dla OCI-Lob::free
- ocifreestatement — Alias dla oci_free_statement
- ociinternaldebug — Alias dla oci_internal_debug
- ociloadlob — Alias dla OCI-Lob::load
- ocilogoff — Alias dla oci_close
- ocilogon — Alias dla oci_connect
- ocinewcollection — Alias dla oci_new_collection
- ocinewcursor — Alias dla oci_new_cursor
- ocinewdescriptor — Alias dla oci_new_descriptor
- ocinlogon — Alias dla oci_new_connect
- ocinumcols — Alias dla oci_num_fields
- ociparse — Alias dla oci_parse
- ociplogon — Alias dla oci_pconnect
- ociresult — Alias dla oci_result
- ocirollback — Alias dla oci_rollback
- ocirowcount — Alias dla oci_num_rows
- ocisavelob — Alias dla OCI-Lob::save
- ocisavelobfile — Alias dla OCI-Lob::import
- ociserverversion — Alias dla oci_server_version
- ocisetprefetch — Alias dla oci_set_prefetch
- ocistatementtype — Alias dla oci_statement_type
- ociwritelobtofile — Alias dla OCI-Lob::export
- ociwritetemporarylob — Alias dla OCI-Lob::writeTemporary
Ovrimos SQL
Wstęp
Ovrimos SQL Server to klient/serwer, system zarządzania relacyjnymi bazami danych łączący możliwości sieci i szybkie transakcje.
Informacja:
To rozszerzenie zostało przeniesione do repozytorium » PECL i nie jest rozprowadzane z PHP od wersji 4.4.5 i PHP 5.1.0.
Informacja: To rozszerzenie nie jest dostępne na platformie Windows.
Instalacja/Konfiguracja
Spis treści
Wymagania
Należy zainstalować bibliotekę sqlcli znajdującą się w dystrybucji Ovrimos SQL Server.
Instalacja
Aby włączyć obsługę Ovrimos w PHP, należy skompilować PHP z parametrem --with-ovrimos[=DIR] , gdzie DIR jest katalogiem instalacji biblioteki libsqlcli.
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
To rozszerzenie nie posiada żadnych stałych.
Przykłady
Spis treści
Podstawowe użycie
Przykład #1 Połączenie do Ovrimos SQL Server i pobranie danych z tabeli systemowej
<?php
$conn = ovrimos_connect("server.domain.com", "8001", "admin", "password");
if ($conn != 0) {
echo "Połączenie zostało nawiązane.";
$res = ovrimos_exec($conn, "select table_id, table_name from sys.tables");
if ($res != 0) {
echo "Instrukcja została wykonana prawidłowo.";
ovrimos_result_all($res);
ovrimos_free_result($res);
}
ovrimos_close($conn);
}
?>
Funkcje Ovrimos SQL
ovrimos_close
(PHP 4 >= 4.0.3, PHP 5 <= 5.0.5)
ovrimos_close — Zamyka połączenie z serwerem Ovrimos
Opis
$identyfikator_połączenia
)
Zamyka połączenie z serwerem Ovrimos, określone parametrem
connection. W efekcie wszystkie niezatwierdzone
transakcje w danej sesji zostaną wycofane.
Parametry
-
identyfikator_połączenia -
Identyfikator połączenia z serwerem Ovrimos, zwrócony przez ovrimos_connect().
Zwracane wartości
Nie jest zwracana żadna wartość.
ovrimos_commit
(PHP 4 >= 4.0.3, PHP 5 <= 5.0.5)
ovrimos_commit — Potwierdza transakcję
Opis
$identyfikator_połączenia
)Potwierdza transakcję.
Parametry
-
identyfikator_połączenia -
Identyfikator połączenia z serwerem Ovrimos, zwrócony przez ovrimos_connect().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
ovrimos_connect
(PHP 4 >= 4.0.3, PHP 5 <= 5.0.5)
ovrimos_connect — Otwiera połączenie z określoną bazą danych
Opis
$host
, string $nazwabazy_lub_port
, string $użytkownik
, string $hasło
)Otwiera połączenie do określonej bazy danych.
Parametry
-
host -
Nazwa hosta lub adres IP.
-
nazwabazy_lub_port -
Nazwa bazy danych lub numer portu.
-
użytkownik -
Nazwa użytkownika.
-
hasło -
Hasło
użytkownika.
Zwracane wartości
Zwraca identyfikator połączenia (wartość większa od 0) w przypadku powodzenia, lub 0 w przypadku błędu.
Przykłady
Przykład #1 Przykład ovrimos_connect()
<?php
$conn = ovrimos_connect("server.example.com", "8001", "admin", "password");
if ($conn != 0) {
echo "Połączenie zostało nawiązane.";
$res = ovrimos_exec($conn, "select table_id, table_name from sys.tables");
if ($res != 0) {
echo "Instrukcja została wykonana prawidłowo.";
ovrimos_result_all($res);
ovrimos_free_result($res);
}
ovrimos_close($conn);
}
?>
ovrimos_cursor
(PHP 4 >= 4.0.3, PHP 5 <= 5.0.5)
ovrimos_cursor — Zwraca nazwę kursora
Opis
$identyfikator_wyniku
)Pobiera nazwę kursora. Przydatne podczas wykonywania określanych zapytań aktualizacji lub usuwania.
Parametry
-
identyfikator_wyniku -
Indetyfikator wyniku zwrócony przez ovrimos_execute() lub ovrimos_exec().
Zwracane wartości
Zwraca nazwę jako string, lub FALSE w przypadku błędu.
ovrimos_exec
(PHP 4 >= 4.0.3, PHP 5 <= 5.0.5)
ovrimos_exec — Wykonuje instrukcję SQL
Opis
$identyfikator_połączenia
, string $zapytanie
)Wykonuje instrukcję SQL i zwraca identyfikator wyniku.
Parametry
-
identyfikator_połączenia -
Identyfikator połączenia z serwerem Ovrimos, zwrócony przez ovrimos_connect().
-
zapytanie -
Instrukcja SQL. Oczywiście nie może zawierać parametrów. Do przygotowania instrukcji SQL należy używać ovrimos_prepare().
Zwracane wartości
Zwraca indentyfikator wyniku jako integer, lub FALSE w przypadku błędu.
Zobacz też:
- ovrimos_execute() - Wykonuje przygotowaną instrukcję SQL
- ovrimos_prepare() - Przygotowuje instrukcję SQL
ovrimos_execute
(PHP 4 >= 4.0.3, PHP 5 <= 5.0.5)
ovrimos_execute — Wykonuje przygotowaną instrukcję SQL
Opis
$identyfikator_wyniku
[, array $tablica_parametrów
] )Wykonuje przygotowaną instrukcję SQL.
Parametry
-
identyfikator_wyniku -
Identyfikator wyniku Ovrimos, przygotowany za pomocą ovrimos_prepare().
-
tablica_parametrów -
Jeśli przygotowana instrukcja zawiera parametry (znaki zapytania), to powinna zostać do funkcji przekazana tablica zawierająca odpowiednią liczbę wartości dla nich.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
ovrimos_fetch_into
(PHP 4 >= 4.0.3, PHP 5 <= 5.0.5)
ovrimos_fetch_into — Pobiera wiersz ze zbioru wyniku
Opis
$identyfikator_wyniku
, array &$tablica_wyniku
[, string $sposób
[, int $numer_wiersza
]] )
Pobiera wiersz z podanego zbioru wyniku do
tablicy_wyniku.
Parametry
-
identyfikator_wyniku -
Indetyfikator wyniku zwrócony przez ovrimos_execute() lub ovrimos_exec().
-
tablica_wyniku -
Należy dostarczyć tablicę przez referencję. Zostanie ona wypełniona pobranymi wartościami.
-
sposób -
Określa w jaki sposób będą pobierane wiersze. Może przyjmować jedną z następujących wartości (wielkość liter nie ma znaczenia):
Opcja Informacja Next Następny z bieżącej pozycji. To jest wartość domyślna. Prev Poprzedni z bieżącej pozycji. First Pierwszy. Last Ostatni. Absolute Wskazany numer, liczony od początku zbioru. Wymaga podania numer_wiersza. -
numer_wiersza -
Numer wiersza liczony od 0. Wymagany tylko, gdy
sposóbma wartość Absolute.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Przykład ovrimos_fetch_into
<?php
$conn=ovrimos_connect("neptune", "8001", "admin", "password");
if ($conn!=0) {
echo "Połączenie zostało nawiązane.";
$res=ovrimos_exec($conn, "select table_id, table_name from sys.tables");
if ($res != 0) {
echo "Instrukcja została wykonana prawidłowo.";
if (ovrimos_fetch_into($res, $row)) {
list($table_id, $table_name) = $row;
echo "table_id=" . $table_id . ", table_name=" . $table_name . "\n";
if (ovrimos_fetch_into($res, $row)) {
list($table_id, $table_name) = $row;
echo "table_id=" . $table_id . ", table_name=" . $table_name . "\n";
} else {
echo "Następny: błąd\n";
}
} else {
echo "Pierwszy: błąd\n";
}
ovrimos_free_result($res);
}
ovrimos_close($conn);
}
?>
ovrimos_fetch_row
(PHP 4 >= 4.0.3, PHP 5 <= 5.0.5)
ovrimos_fetch_row — Pobiera wiersz ze zbioru wyniku
Opis
$identyfikator_wyniku
[, int $sposób
[, int $numer_wiersza
]] )Pobiera wiersz ze zbioru wyniku. Wartości kolumn powinny być odczytywane przez wywołania innej funkcji.
Parametry
-
identyfikator_wyniku -
Indetyfikator wyniku zwrócony przez ovrimos_execute() lub ovrimos_exec().
-
sposób -
Określa w jaki sposób będą pobierane wiersze. Może przyjmować jedną z następujących wartości (wielkość liter nie ma znaczenia):
Opcja Informacja Next Następny z bieżącej pozycji. To jest wartość domyślna. Prev Poprzedni z bieżącej pozycji. First Pierwszy. Last Ostatni. Absolute Wskazany numer, liczony od początku zbioru. Wymaga podania numer_wiersza. -
numer_wiersza -
Numer wiersza liczony od 0. Wymagany tylko, gdy
sposóbma wartość Absolute.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Przykład ovrimos_fetch_row
<?php
$conn = ovrimos_connect("remote.host", "8001", "admin", "password");
if ($conn != 0) {
echo "Połączenie zostało nawiązane.";
$res=ovrimos_exec($conn, "select table_id, table_name from sys.tables");
if ($res != 0) {
echo "Instrukcja została wykonana prawidłowo.";
if (ovrimos_fetch_row($res, "First")) {
$table_id = ovrimos_result($res, 1);
$table_name = ovrimos_result($res, 2);
echo "table_id=" . $table_id . ", table_name=" . $table_name . "\n";
if (ovrimos_fetch_row($res, "Next")) {
$table_id = ovrimos_result($res, "table_id");
$table_name = ovrimos_result($res, "table_name");
echo "table_id=" . $table_id . ", table_name=" . $table_name . "\n";
} else {
echo "Następny: błąd\n";
}
} else {
echo "Pierwszy: błąd\n";
}
ovrimos_free_result($res);
}
ovrimos_close($conn);
}
?>
ovrimos_field_len
(PHP 4 >= 4.0.3, PHP 5 <= 5.0.5)
ovrimos_field_len — Zwraca długość kolumny
Opis
$identyfikator_wyniku
, int $numer_pola
)Zwraca długość określonej kolumny.
Parametry
-
identyfikator_wyniku -
Indetyfikator wyniku zwrócony przez ovrimos_execute() lub ovrimos_exec().
-
numer_pola -
Numer pola. Numeracja zaczyna się od 1.
Zwracane wartości
Zwraca długość jako integer, lub FALSE w przypadku błędu.
Zobacz też:
- ovrimos_field_name() - Zwraca nazwę kolumny
- ovrimos_field_num() - Zwraca numer kolumny
- ovrimos_field_type() - Zwraca typ kolumny
ovrimos_field_name
(PHP 4 >= 4.0.3, PHP 5 <= 5.0.5)
ovrimos_field_name — Zwraca nazwę kolumny
Opis
$identyfikator_wyniku
, int $numer_pola
)Zwraca nazwę kolumny dla określonego numeru pola.
Parametry
-
identyfikator_wyniku -
Indetyfikator wyniku zwrócony przez ovrimos_execute() lub ovrimos_exec().
-
numer_pola -
Numer pola. Numeracja zaczyna się od 1.
Zwracane wartości
Zwraca nazwę pola jako string, lub FALSE w przypadku błędu.
Zobacz też:
- ovrimos_field_len() - Zwraca długość kolumny
- ovrimos_field_num() - Zwraca numer kolumny
- ovrimos_field_type() - Zwraca typ kolumny
ovrimos_field_num
(PHP 4 >= 4.0.3, PHP 5 <= 5.0.5)
ovrimos_field_num — Zwraca numer kolumny
Opis
$identyfikator_wyniku
, string $nazwa_pola
)Zwraca numer określonej kolumny. Numeracja zaczyna się od 1.
Parametry
-
identyfikator_wyniku -
Indetyfikator wyniku zwrócony przez ovrimos_execute() lub ovrimos_exec().
-
nazwa_pola -
Nazwa pola.
Zwracane wartości
Zwraca indeks rozpoczynający się od 1, lub FALSE w przypadku błędu.
Zobacz też:
- ovrimos_field_len() - Zwraca długość kolumny
- ovrimos_field_name() - Zwraca nazwę kolumny
- ovrimos_field_type() - Zwraca typ kolumny
ovrimos_field_type
(PHP 4 >= 4.0.3, PHP 5 <= 5.0.5)
ovrimos_field_type — Zwraca typ kolumny
Opis
$identyfikator_wyniku
, int $numer_pola
)Zwraca typ kolumny.
Parametry
-
identyfikator_wyniku -
Indetyfikator wyniku zwrócony przez ovrimos_execute() lub ovrimos_exec().
-
numer_pola -
Indeks zaczynający się od 1.
Zwracane wartości
Zwraca typ pola jako integer, lub FALSE w przypadku błędu.
Zobacz też:
- ovrimos_field_len() - Zwraca długość kolumny
- ovrimos_field_name() - Zwraca nazwę kolumny
- ovrimos_field_num() - Zwraca numer kolumny
ovrimos_free_result
(PHP 4 >= 4.0.3, PHP 5 <= 5.0.5)
ovrimos_free_result — Zwalnia pamięć zajmowaną przez określony wynik
Opis
$identyfikator_wyniku
)Zwalnia pamięć zajmowaną przez określony wynik.
Parametry
-
identyfikator_wyniku -
Indetyfikator wyniku zwrócony przez ovrimos_execute() lub ovrimos_exec().
Zwracane wartości
Zwraca TRUE.
ovrimos_longreadlen
(PHP 4 >= 4.0.3, PHP 5 <= 5.0.5)
ovrimos_longreadlen — Określa ile bajtów zostanie odczytanych z dużych typów danych
Opis
$identyfikator_wyniku
, int $długość
)Określa ile bajtów zostanie odczytanych z dużych typów danych (long varchar i long varbinary).
Parametry
-
identyfikator_wyniku -
Indetyfikator wyniku zwrócony przez ovrimos_execute() lub ovrimos_exec().
-
długość -
Liczba bajtów do odczytu. Domyślnie zero.
Zwracane wartości
Zwraca TRUE.
ovrimos_num_fields
(PHP 4 >= 4.0.3, PHP 5 <= 5.0.5)
ovrimos_num_fields — Zwraca liczbę kolumn
Opis
$identyfikator_wyniku
)Zwraca liczbę kolumn w określonym zbiorze wyniku.
Parametry
-
identyfikator_wyniku -
Indetyfikator wyniku zwrócony przez ovrimos_execute() lub ovrimos_exec().
Zwracane wartości
Zwraca liczbę kolumn jako integer, lub FALSE w przypadku błędu.
ovrimos_num_rows
(PHP 4 >= 4.0.3, PHP 5 <= 5.0.5)
ovrimos_num_rows — Pobiera liczbę wierszy użytych przez operacje aktualizacji
Opis
$identyfikator_wyniku
)Pobiera liczbę zaktualizowanych wierszy.
Parametry
-
identyfikator_wyniku -
Indetyfikator wyniku zwrócony przez ovrimos_execute() lub ovrimos_exec().
Zwracane wartości
Zwraca liczbę wierszy jako integer, lub FALSE w przypadku błędu.
ovrimos_prepare
(PHP 4 >= 4.0.3, PHP 5 <= 5.0.5)
ovrimos_prepare — Przygotowuje instrukcję SQL
Opis
$identyfikator_połączenia
, string $zapytanie
)Przygotowuje instrukcję SQL.
Parametry
-
identyfikator_połączenia -
Identyfikator połączenia z serwerem Ovrimos, zwrócony przez ovrimos_connect().
-
zapytanie -
Instrukcja SQL.
Zwracane wartości
Zwraca identyfikator wyniku, lub FALSE w przypadku błędu.
Przykłady
Przykład #1 Przykład ovrimos_prepare()
<?php
$conn=ovrimos_connect("db_host", "8001", "admin", "password");
if ($conn!=0) {
echo "Połączenie zostało nawiązane.";
// Przygotowanie instrukcji
$res=ovrimos_prepare($conn, "select table_id, table_name
from sys.tables where table_id=1");
if ($res != 0) {
echo "Przygotowanie instrukcji powiodło się";
// Wykonanie przygotowanej instrukcji
if (ovrimos_execute($res)) {
echo "Wykonanie instrukcji powiodło się\n";
ovrimos_result_all($res);
} else {
echo "Wykonanie instrukcji nie powiodło się";
}
ovrimos_free_result($res);
} else {
echo "Przygotowanie instrukcji nie powiodło się\n";
}
ovrimos_close($conn);
}
?>
ovrimos_result_all
(PHP 4 >= 4.0.3, PHP 5 <= 5.0.5)
ovrimos_result_all — Wyświetla cały zbiór wyniku w postaci tabeli HTML
Opis
$identyfikator_wyniku
[, string $format
] )Wyświetla cały zbiór wyniku w postaci tabeli HTML.
Parametry
-
identyfikator_wyniku -
Indetyfikator wyniku zwrócony przez ovrimos_execute() lub ovrimos_exec().
-
format -
Opcjonalne atrybuty HTML używane podczas generowania tabeli.
Zwracane wartości
Zwraca liczbę wierszy w wygenerowanej tabeli.
Przykłady
Wykonanie instrukcji SQL i wyświetlenie wyniku w postaci tabeli HTML.
Przykład #1 Przygotowanie instrukcji, wykonanie, i wyświetlenie wyniku
<?php
$conn = ovrimos_connect("db_host", "8001", "admin", "password");
if ($conn != 0) {
echo "Połączenie zostało nawiązane.";
$res = ovrimos_prepare($conn, "select table_id, table_name
from sys.tables where table_id = 7");
if ($res != 0) {
echo "Instrukcja została przygotowana prawidłowo";
if (ovrimos_execute($res, array(3))) {
echo "Wykonanie instrukcji powiodło się\n";
ovrimos_result_all($res);
} else {
echo "Wykonanie instrukcji nie powiodło się";
}
ovrimos_free_result($res);
} else {
echo "Przygotowanie instrukcji nie powiodło się\n";
}
ovrimos_close($conn);
}
?>
Przykład #2 Przykład ovrimos_result_all() z metadanymi
<?php
$conn = ovrimos_connect("db_host", "8001", "admin", "password");
if ($conn != 0) {
echo "Połączenie zostało nawiązane.";
$res = ovrimos_exec($conn, "select table_id, table_name
from sys.tables where table_id = 1");
if ($res != 0) {
echo "Instrukcja została wykonana prawidłowo; cursor=" . ovrimos_cursor($res) . "\n";
$colnb = ovrimos_num_fields($res);
echo "Liczba kolumn=" . $colnb . "\n";
for ($i=1; $i <= $colnb; $i++) {
$name = ovrimos_field_name($res, $i);
$type = ovrimos_field_type($res, $i);
$len = ovrimos_field_len($res, $i);
echo "Kolumna " . $i . " nazwa=" . $name . " typ=" . $type . " długość=" . $len . "\n";
}
ovrimos_result_all($res);
ovrimos_free_result($res);
}
ovrimos_close($conn);
}
?>
ovrimos_result
(PHP 4 >= 4.0.3, PHP 5 <= 5.0.5)
ovrimos_result — Odczytuje wartość kolumny
Opis
Odczytuje wartość kolumny określoną przez pole.
Parametry
-
identyfikator_wyniku -
Indetyfikator wyniku zwrócony przez ovrimos_execute() lub ovrimos_exec().
-
pole -
Nazwa kolumny jako string lub indeks zaczynający się od 1.
Zwracane wartości
Zwraca kolumnę jako string, lub FALSE w przypadku błędu.
ovrimos_rollback
(PHP 4 >= 4.0.3, PHP 5 <= 5.0.5)
ovrimos_rollback — Wycofuje transakcję
Opis
$identyfikator_połączenia
)Wycofuje transakcję.
Parametry
-
identyfikator_połączenia -
Identyfikator połączenia z serwerem Ovrimos, zwrócony przez ovrimos_connect().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Spis treści
- ovrimos_close — Zamyka połączenie z serwerem Ovrimos
- ovrimos_commit — Potwierdza transakcję
- ovrimos_connect — Otwiera połączenie z określoną bazą danych
- ovrimos_cursor — Zwraca nazwę kursora
- ovrimos_exec — Wykonuje instrukcję SQL
- ovrimos_execute — Wykonuje przygotowaną instrukcję SQL
- ovrimos_fetch_into — Pobiera wiersz ze zbioru wyniku
- ovrimos_fetch_row — Pobiera wiersz ze zbioru wyniku
- ovrimos_field_len — Zwraca długość kolumny
- ovrimos_field_name — Zwraca nazwę kolumny
- ovrimos_field_num — Zwraca numer kolumny
- ovrimos_field_type — Zwraca typ kolumny
- ovrimos_free_result — Zwalnia pamięć zajmowaną przez określony wynik
- ovrimos_longreadlen — Określa ile bajtów zostanie odczytanych z dużych typów danych
- ovrimos_num_fields — Zwraca liczbę kolumn
- ovrimos_num_rows — Pobiera liczbę wierszy użytych przez operacje aktualizacji
- ovrimos_prepare — Przygotowuje instrukcję SQL
- ovrimos_result_all — Wyświetla cały zbiór wyniku w postaci tabeli HTML
- ovrimos_result — Odczytuje wartość kolumny
- ovrimos_rollback — Wycofuje transakcję
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Przykłady
- Funkcje Ovrimos SQL
- ovrimos_close — Zamyka połączenie z serwerem Ovrimos
- ovrimos_commit — Potwierdza transakcję
- ovrimos_connect — Otwiera połączenie z określoną bazą danych
- ovrimos_cursor — Zwraca nazwę kursora
- ovrimos_exec — Wykonuje instrukcję SQL
- ovrimos_execute — Wykonuje przygotowaną instrukcję SQL
- ovrimos_fetch_into — Pobiera wiersz ze zbioru wyniku
- ovrimos_fetch_row — Pobiera wiersz ze zbioru wyniku
- ovrimos_field_len — Zwraca długość kolumny
- ovrimos_field_name — Zwraca nazwę kolumny
- ovrimos_field_num — Zwraca numer kolumny
- ovrimos_field_type — Zwraca typ kolumny
- ovrimos_free_result — Zwalnia pamięć zajmowaną przez określony wynik
- ovrimos_longreadlen — Określa ile bajtów zostanie odczytanych z dużych typów danych
- ovrimos_num_fields — Zwraca liczbę kolumn
- ovrimos_num_rows — Pobiera liczbę wierszy użytych przez operacje aktualizacji
- ovrimos_prepare — Przygotowuje instrukcję SQL
- ovrimos_result_all — Wyświetla cały zbiór wyniku w postaci tabeli HTML
- ovrimos_result — Odczytuje wartość kolumny
- ovrimos_rollback — Wycofuje transakcję
Paradox File Access
Wstęp
This module allows to read and write Paradox databases, primary index files and blob files. Write support has been proven to be quite reliable, though due to lack of documentation the produced files may not in any case be readable by other applications. Encrypted databases can be read without specifying a password if pxlib >= 0.5.0 is used.
Informacja:
This module is also in development and may change, though major changes to the API are not expected.
Ten moduł jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie tych funkcji, ich nazw, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tego modułu na własne ryzyko.
Instalacja/Konfiguracja
Spis treści
Wymagania
You need at least PHP 5.0.0 and pxlib >= 0.4.4 for the basic set of functions. Some newer functions are only available with pxlib >= 0.6.0. Reading and writing of encrypted databases requires at least pxlib >= 0.5.0. The paradox library (pxlib) is available at » http://pxlib.sourceforge.net.
Instalacja
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/paradox
Make sure you have pxlib installed before. If you install pxlib from an rpm or debian package, do not forget to install the development package as well.
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
The following two tables lists all constants defined by the paradox extension.
| Name | Meaning |
|---|---|
| PX_FIELD_ALPHA | Character data with fixed length |
| PX_FIELD_DATE | Date, number of days since 1.1.0000 |
| PX_FIELD_SHORT | Short integer (2 Bytes) |
| PX_FIELD_LONG | Long integer (4 Bytes) |
| PX_FIELD_CURRENCY | same as PX_FIELD_NUMBER |
| PX_FIELD_NUMBER | Double |
| PX_FIELD_LOGICAL | Boolean |
| PX_FIELD_MEMOBLOB | Binary large object |
| PX_FIELD_BLOB | Binary large object (not supported) |
| PX_FIELD_FMTMEMOBLOB | Binary large object |
| PX_FIELD_OLE | OLE object (basically a blob, not supported) |
| PX_FIELD_GRAPHIC | Graphic (basically a blob, not supported) |
| PX_FIELD_TIME | time, number of milli seconds since midnight |
| PX_FIELD_TIMESTAMP | timestamp, number of milli seconds since 1.1.0000 |
| PX_FIELD_AUTOINC | Auto incrementing interger (like PX_FIELD_LONG) |
| PX_FIELD_BCD | Decimal number stored in bcd format (not supported) |
| PX_FIELD_BYTES | Array of Bytes with not more than 255 bytes (not supported) |
| PX_KEYTOLOWER | Turn all field names into lower case |
| PX_KEYTOUPPER | Turn all field names into upper case |
| Name | Meaning |
|---|---|
| PX_FILE_INDEX_DB | Indexed database |
| PX_FILE_PRIM_INDEX | Primary index |
| PX_FILE_NON_INDEX_DB | None indexed database |
| PX_FILE_NON_INC_SEC_INDEX | None incremental secondary index |
| PX_FILE_SEC_INDEX | Secondary index |
| PX_FILE_INC_SEC_INDEX | Incremental secondary index |
| PX_FILE_NON_INC_SEC_INDEX_G | Non incremental secondary index |
| PX_FILE_SEC_INDEX_G | Secondary index |
| PX_FILE_INC_SEC_INDEX_G | Non incremental secondary index |
Paradox Funkcje
Object oriented API
The paradox extension provides also an object oriented API. It consists of only one class called paradox_db. Its methods only differ from the functions in its name and of course the missing first parameter. The following table will list all methods and its equivalent functions.
| Name of method | Equivalent function |
|---|---|
| Constructor | px_new() |
| Destructor | px_delete() |
| open_fp() | px_open_fp() |
| create_fp() | px_create_fp() |
| close() | px_close() |
| numrecords() | px_numrecords() |
| numfields() | px_numfields() |
| get_record() | px_get_record() |
| put_record() | px_put_record() |
| retrieve_record() | px_retrieve_record() |
| delete_record() | px_delete_record() |
| insert_record() | px_insert_record() |
| update_record() | px_update_record() |
| get_field() | px_get_field() |
| get_schema() | px_get_schema() |
| get_info() | px_get_info() |
| set_parameter() | px_set_parameter() |
| get_parameter() | px_get_parameter() |
| set_value() | px_set_value() |
| get_value() | px_get_value() |
| get_info() | px_get_info() |
| set_targetencoding() | px_set_targetencoding() |
| set_tablename() | px_set_tablename() |
| set_blob_file() | px_set_blob_file() |
| date2string() | px_date2string() |
| timestamp2string() | px_timestamp2string() |
px_close
(PECL paradox >= 1.0.0)
px_close — Closes a paradox database
Opis
$pxdoc
)Closes the paradox database. This function will not close the file. You will have to call fclose() afterwards.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- px_open_fp() - Open paradox database
- The example at px_new() - Create a new paradox object
px_create_fp
(PECL paradox >= 1.0.0)
px_create_fp — Create a new paradox database
Opis
$pxdoc
, resource $file
, array $fielddesc
)Create a new paradox database file. The actual file has to be opened before with fopen(). Make sure the file is writable.
Informacja:
Calling this functions issues a warning about an empty tablename which can be safely ignored. Just set the tablename afterwards with px_set_parameter().
Informacja:
This function is highly experimental, due to insufficient documentation of the paradox file format. Database files created with this function can be opened by px_open_fp() and has been successfully opened by the Paradox software, but your milage may vary.
Parametry
-
pxdoc -
Resource identifier of the paradox database as returned by px_new().
-
file -
File handle as returned by fopen().
-
fielddesc -
fielddesc is an array containing one element for each field specification. A field specification is an array itself with either two or three elements.The first element is always a string value used as the name of the field. It may not be larger than ten characters. The second element contains the field type which is one of the constants listed in the table Constants for field types. In the case of a character field or bcd field, you will have to provide a third element specifying the length respectively the precesion of the field. If your field specification contains blob fields, you will have to make sure to either make the field large enough for all field values to fit or specify a blob file with px_set_blob_file() for storing the blobs. If this is not done the field data is truncated.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Creating a Paradox database with two fields
<?php
if(!$pxdoc = px_new()) {
/* Error handling */
}
$fp = fopen("test.db", "w+");
$fields = array(array("col1", "S"), array("col2", "I"));
if(!px_create_fp($pxdoc, $fp, $fields)) {
/* Error handling */
}
px_set_parameter($pxdoc, "tablename", "testtable");
for($i=-50; $i<50; $i++) {
$rec = array($i, -$i);
px_put_record($pxdoc, $rec);
}
px_close($pxdoc);
px_delete($pxdoc);
fclose($fp);
?>
Zobacz też:
- px_new() - Create a new paradox object
- px_put_record() - Stores record into paradox database
- fopen() - Otwiera plik lub URL
px_date2string
(PECL paradox >= 1.4.0)
px_date2string — Converts a date into a string.
Opis
$pxdoc
, int $value
, string $format
)Turns a date as it stored in the paradox file into human readable format. Paradox dates are the number of days since 1.1.0000. This function is just for convenience. It can be easily replaced by some math and the calendar functions as demonstrated in the example below.
Parametry
-
pxdoc -
Resource identifier of the paradox database as returned by px_new().
-
value -
Value as stored in paradox database field of type PX_FIELD_DATE.
-
format -
String format similar to the format used by date(). The placeholders support by this function is a subset of those supported by date() (Y, y, m, n, d, j, L).
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Turn a paradox date into a human readable form
<?php
$px = px_new();
/* make up a date as it could be stored in */
/* a date field of a paradox db. */
/* 700000 days since 1.1.0000. */
$days = 700000;
/* Use the calendar functions to print a */
/* human readable format of the date */
echo jdtogregorian($days+1721425)."\n";
/* px_date2string() outputs the same */
echo px_date2string($px, $days, "n/d/Y")."\n";
px_delete($px);
?>
Powyższy przykład wyświetli:
7/15/1917 7/15/1917
Zobacz też:
- px_timestamp2string() - Converts the timestamp into a string.
- jdtogregorian() - Converts Julian Day Count to Gregorian date
px_delete_record
(PECL paradox >= 1.4.0)
px_delete_record — Deletes record from paradox database
Opis
$pxdoc
, int $num
)This function deletes a record from the database. It does not free the space in the database file but just marks it as deleted. Inserting a new record afterwards will reuse the space.
Informacja:
This function is only available if pxlib >= 0.6.0 is used.
Parametry
-
pxdoc -
Resource identifier of the paradox database as returned by px_new().
-
num -
The record number is an artificial number counting records in the order as they are stored in the database. The first record has number 0.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
px_delete
(PECL paradox >= 1.0.0)
px_delete — Deletes resource of paradox database
Opis
$pxdoc
)Deletes the resource of the paradox file and frees all memory.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
px_get_field
(PECL paradox >= 1.0.0)
px_get_field — Returns the specification of a single field
Opis
$pxdoc
, int $fieldno
)Parametry
-
pxdoc -
Resource identifier of the paradox database as returned by px_new().
-
fieldno -
Number of the field. The first field has number 0. Specifying a field number less than 0 and greater or equal the number of fields will trigger an error.
Zwracane wartości
Returns the specification of the fieldno 'th database field as an associated array. The array contains three fields named name, type, and size.
px_get_info
(PECL paradox >= 1.0.0)
px_get_info — Return lots of information about a paradox file
Opis
$pxdoc
)Zwracane wartości
Returns an associated array with lots of information about a paradox file. This array is likely to be extended in the future.
- fileversion
-
Version of file multiplied by 10, e.g. 70.
- tablename
-
Name of table as stored in the file. If the database was created by pxlib, then this will be the name of the file without the extension.
- numrecords
-
Number of records in this table.
- numfields
-
Number of fields in this table.
- headersize
-
Number of bytes used for the header. This is usually 0x800.
- recordsize
-
Number of bytes used for each record. This is the sum of all field sizes (available since version 1.4.2).
- maxtablesize
-
This value multiplied by 0x400 is the size of a data block in bytes. The maximum number of records in a datablock is the integer part of (maxtablesize * 0x400 - 8) / recordsize.
- numdatablocks
-
The number of data blocks in the file. Each data block contains a certain number of records which depends on the record size and the data block size (maxtablesize). Data blocks may not necessarily be completely filled.
- numindexfields
-
Number of fields used for the primary index. The fields do always start with field number 1.
- codepage
-
The DOS codepage which was used for encoding fields with character data. If the target encoding is not set with px_set_targetencoding() this will be the encoding for character fields when records are being accessed with px_get_record() or px_retrieve_record().
Zobacz też:
- px_numfields() - Returns number of fields in a database
- px_numrecords() - Returns number of records in a database
px_get_parameter
(PECL paradox >= 1.1.0)
px_get_parameter — Gets a parameter
Opis
$pxdoc
, string $name
)Gets various parameters.
Parametry
-
pxdoc -
Resource identifier of the paradox database as returned by px_new().
-
name -
The
namecan be one of the following:- tablename
-
The name of the table as it will be stored in the database header.
- targetencoding
-
The encoding for the output. Data which is being read from character fields with px_get_record() or px_retrieve_record() is recoded into the targetencoding. If it is not set, then the data will be delivered as stored in the database file.
- inputencoding
-
The encoding of the input data which is to be stored into the database. When storing data of character fields in the database, the data is expected to be delivered in this encoding.
Zwracane wartości
Returns the value of the parameter lub FALSE w przypadku niepowodzenia.
px_get_record
(PECL paradox >= 1.0.0)
px_get_record — Returns record of paradox database
Opis
$pxdoc
, int $num
[, int $mode = 0
] )Parametry
-
pxdoc -
Resource identifier of the paradox database as returned by px_new().
-
num -
The record number is an artificial number counting records in the order as they are stored in the database. The first record has number 0.
-
mode -
The optional
modecan bePX_KEYTOLOWERorPX_KEYTOUPPERin order to convert the keys of the returned array into lower or upper case. Ifmodeis not passed or is 0, then the key will be exactly like the field name. The element values will contain the field values. NULL values will be retained and are different from 0.0, 0 or the empty string. Fields of typePX_FIELD_TIMEwill be returned as an integer counting the number of milliseconds starting at midnight. A timestamp (PX_FIELD_TIMESTAMP) and date (PX_FIELD_DATE) are floating point respectively int values counting milliseconds respectively days starting at the beginning of julian calendar. Use the functions px-timestamp2string() and px-date2string() to convert them into a character representation.
Zwracane wartości
Returns the num'th record from the paradox
database. The record is returned as an associated array with its keys
being the field names.
px_get_schema
(PECL paradox >= 1.0.0)
px_get_schema — Returns the database schema
Opis
$pxdoc
[, int $mode = 0
] )px_get_schema() returns the database schema.
Parametry
-
pxdoc -
Resource identifier of the paradox database as returned by px_new().
-
mode -
If the optional
modeisPX_KEYTOLOWERorPX_KEYTOUPPERthe keys of the returned array will be converted to lower or upper case. Ifmodeis 0 or not passed at all, then the key name will be identical to the field name.
Zwracane wartości
Returns the schema of a database file as an associated array. The key name is equal to the field name. Each array element is itself an associated array containing the two fields type and size. type is one of the constants in table Constants for field types. size is the number of bytes this field consumes in the record. The total of all field sizes is equal to the record size as it can be retrieved with px-get-info().
px_get_value
(PECL paradox >= 1.1.0)
px_get_value — Gets a value
Opis
$pxdoc
, string $name
)Gets various values.
Parametry
-
pxdoc -
Resource identifier of the paradox database as returned by px_new().
-
name -
namecan be one of the following.- numprimkeys
-
The number of primary keys. Paradox databases always use the first numprimkeys fields for the primary index.
Zwracane wartości
Returns the value of the parameter lub FALSE w przypadku niepowodzenia.
px_insert_record
(PECL paradox >= 1.4.0)
px_insert_record — Inserts record into paradox database
Opis
$pxdoc
, array $data
)Inserts a new record into the database. The record is not necessarily inserted at the end of the database, but may be inserted at any position depending on where the first free slot is found.
The record data is passed as an array of field values. The elements in the array must correspond to the fields in the database. If the array has less elements than fields in the database, the remaining fields will be set to null.
Most field values can be passed as its equivalent php type e.g. a long value is used for fields of type PX_FIELD_LONG, PX_FIELD_SHORT and PX_FIELD_AUTOINC, a double values is used for fields of type PX_FIELD_CURRENCY and PX_FIELD_NUMBER. Field values for blob and alpha fields are passed as strings.
Fields of type PX_FIELD_TIME and PX_FIELD_DATE both require a long value. In the first case this is the number of milliseconds since midnight. In the second case this is the number of days since 1.1.0000. Below there are two examples to convert the current date or timestamp into a value suitable for one of paradox's date/time fields.
Informacja:
This function is only available if pxlib >= 0.6.0 is used.
Parametry
-
pxdoc -
Resource identifier of the paradox database as returned by px_new().
-
data -
Associated or indexed array containing the field values as e.g. returned by px_retrieve_record().
Zwracane wartości
Returns FALSE on failure or the record number in case of success.
Przykłady
Przykład #1 Set the date/time fields in a paradox database to the current date/time
<?php
$px = px_new();
$fp = fopen("test.db", "w+");
px_create_fp($px, $fp, array(array("timestamp", "@"), array("time", "T"), array("date", "D")));
$curdate = getdate();
$jd = gregoriantojd($curdate["mon"], $curdate["mday"], $curdate["year"]);
$days = $jd - 1721425; /* Number of days between 1.1.4714 b.c. and 1.1.0000 */
$secs = $curdate["hours"]*3600 + $curdate["minutes"]*60 + $curdate["seconds"];
px_insert_record($px, array($days*86400000.0 + $secs*1000.0, $secs*1000.0, $days));
$curtimestamp = microtime(true);
$days = (int) ($curtimestamp/86400);
$secs = $curtimestamp - ($days * 86400.0);
$days += 2440588; /* Number of days between 1.1.4714 b.c. and 1.1.1970 */
$days -= 1721425; /* Number of days between 1.1.4714 b.c. and 1.1.0000 */
px_insert_record($px, array($days*86400000.0 + $secs*1000.0, $secs*1000.0, $days));
for($i=0; $i<2; $i++) {
$rec = px_retrieve_record($px, $i);
echo px_timestamp2string($px, $rec["timestamp"], "n/d/Y H:i:s")."\n";
echo px_date2string($px, $rec["date"], "n/d/Y")."\n";
}
px_close($px);
px_delete($px);
?>
Powyższy przykład wyświetli:
2/21/2006 21:42:30 2/21/2006 2/21/2006 20:42:30 2/21/2006
The Julian day count as passed to jdtogregorian() has a different base of 1.1.4714 b.c. and must therefore be calculated by adding 1721425 to the day count used in the paradox file. Turning the day count into a timestamp is easily done by multiplying with 86400000.0 to obtain milli seconds.
Zobacz też:
px_update_record() - Updates record in paradox database
px_new
(PECL paradox >= 1.0.0)
px_new — Create a new paradox object
Opis
Create a new paradox object. You will have to call this function before any further functions. px_new() does not create any file on the disk, it just creates an instance of a paradox object. This function must not be called if the object oriented interface is used. Use new paradox_db() instead.
Zwracane wartości
Returns FALSE on failure.
Przykłady
Przykład #1 Opening a Paradox database
<?php
if(!$pxdoc = px_new()) {
/* Error handling */
}
$fp = fopen("test.db", "r");
if(!px_open_fp($pxdoc, $fp)) {
/* Error handling */
}
// ...
px_close($pxdoc);
px_delete($pxdoc);
fclose($fp);
?>
If you prefer the object oriented API, then the above example will look like the following.
Przykład #2 Opening a Paradox database
<?php
$fp = fopen("test.db", "r");
$pxdoc = new paradox_db();
if(!$pxdoc->open_fp($fp)) {
/* Error handling */
}
// ...
$pxdoc->close();
fclose($fp);
?>
px_numfields
(PECL paradox >= 1.0.0)
px_numfields — Returns number of fields in a database
Opis
$pxdoc
)Get the number of fields in a database file.
Zwracane wartości
Returns the number of fields in a database file. The return value of this function is identical to the element numfields in the array returned by px_get_info().
px_numrecords
(PECL paradox >= 1.0.0)
px_numrecords — Returns number of records in a database
Opis
$pxdoc
)Get the number of records in a database file.
Zwracane wartości
Returns the number of records in a database file. The return value of this function is identical to the element numrecords in the array returned by px_get_info().
px_open_fp
(PECL paradox >= 1.0.0)
px_open_fp — Open paradox database
Opis
$pxdoc
, resource $file
)Open an existing paradox database file. The actual file has to be opened before with fopen(). This function can also be used to open primary index files and tread them like a paradox database. This is supported for those who would like to investigate a primary index. It cannot be used to accelerate access to a database file.
Parametry
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
px_put_record
(PECL paradox >= 1.0.0)
px_put_record — Stores record into paradox database
Opis
$pxdoc
, array $record
[, int $recpos = -1
] )Stores a record into a paradox database. The record is always added at the end of the database, regardless of any free slots. Use px_insert_record() to add a new record into the first free slot found in the database.
Parametry
-
pxdoc -
Resource identifier of the paradox database as returned by px_new().
-
record -
Associated or indexed array containing the field values as e.g. returned by px_retrieve_record().
-
recpos -
This optional parameter may be used to specify a record number greater than the current number of records in the database. The function will add as many empty records as needed. There is hardly any need for this parameter.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
px_retrieve_record
(PECL paradox >= 1.4.0)
px_retrieve_record — Returns record of paradox database
Opis
$pxdoc
, int $num
[, int $mode = 0
] )This function is very similar to px_get_record() but uses internally a different approach to retrieve the data. It relies on pxlib for reading each single field value, which usually results in support for more field types.
Informacja:
This function is only available if pxlib >= 0.6.0 is used.
Parametry
-
pxdoc -
Resource identifier of the paradox database as returned by px_new().
-
num -
The record number is an artificial number counting records in the order as they are stored in the database. The first record has number 0.
-
mode -
The optional
modecan bePX_KEYTOLOWERorPX_KEYTOUPPERin order to convert the keys into lower or upper case. Ifmodeis not passed or is 0, then the key will be exactly like the field name. The element values will contain the field values. NULL values will be retained and are different from 0.0, 0 or the empty string. Fields of typePX_FIELD_TIMEwill be returned as an integer counting the number of milliseconds starting at midnight. A timestamp is a floating point value also counting milliseconds starting at the beginning of julian calendar.
Zwracane wartości
Returns the num'th record from the paradox
database. The record is returned as an associated array with its keys
being the field names.
px_set_blob_file
(PECL paradox >= 1.3.0)
px_set_blob_file — Sets the file where blobs are read from
Opis
$pxdoc
, string $filename
)Sets the name of the file where blobs are going to be read from or written into. Without calling this function, px_get_record() or px_retrieve_record() will only return data in blob fields if the data is part of the record and not stored in the blob file. Blob data is stored in the record if it is small enough to fit in the size of the blob field.
Calling px_put_record(), px_insert_record(), or px_update_record() without calling px_set_blob_file() will result in truncated blob fields unless the data fits into the database file.
Calling this function twice will close the first blob file and open the new one.
Parametry
-
pxdoc -
Resource identifier of the paradox database as returned by px_new().
-
filename -
The name of the file. Its extension should be .MB.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
px_set_parameter
(PECL paradox >= 1.1.0)
px_set_parameter — Sets a parameter
Opis
$pxdoc
, string $name
, string $value
)Sets various parameters.
Parametry
-
pxdoc -
Resource identifier of the paradox database as returned by px_new().
-
name -
Depending on the parameter you want to set,
namecan be one of the following.- tablename
-
The name of the table as it will be stored in the database header.
- targetencoding
-
The encoding for the output. Data which is being read from character fields is recoded into the targetencoding.
- inputencoding
-
The encoding of the input data which is to be stored into the database.
-
value -
The value of parameter to set. For inputencoding and targetencoding this must be the name of the encoding as understood by iconv or recode, e.g. iso-8859-1, utf-8, cp850.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- px_get_info() - Return lots of information about a paradox file to determine the DOS code page.
px_set_tablename
(PECL paradox >= 1.0.0)
px_set_tablename — Sets the name of a table (deprecated)
Opis
$pxdoc
, string $name
)Sets the table name of a paradox database, which was created with px_create_fp(). This function is deprecated use px_set_parameter() instead.
Parametry
-
pxdoc -
Resource identifier of the paradox database as returned by px_new().
-
tablename -
The name of the table. If it is not set explicitly it will be set to the name of the database file.
Zwracane wartości
Returns NULL on success lub FALSE w przypadku niepowodzenia.
Zobacz też:
px_set_parameter() - Sets a parameter
px_set_targetencoding
(PECL paradox >= 1.0.0)
px_set_targetencoding — Sets the encoding for character fields (deprecated)
Opis
$pxdoc
, string $encoding
)
Set the encoding for data retrieved from a character field. All character
fields will be recoded to the encoding set by this function. If the
encoding is not set, the character data will be returned in the DOS code
page encoding as specified in the database file. The
encoding can be any string identifier known to
iconv or recode. On Unix systems run iconv -l for
a list of available encodings.
This function is deprecated and should be replaced by calling px_set_parameter().
See also px_get_info() to determine the DOS code page as stored in the database file.
Parametry
-
pxdoc -
Resource identifier of the paradox database as returned by px_new().
-
encoding -
The encoding for the output. Data which is being read from character fields is recoded into the targetencoding.
Zwracane wartości
Returns FALSE if the encoding could not be set, e.g. the encoding is
unknown, or pxlib does not support recoding at all. In the second case a
warning will be issued.
Zobacz też:
px_set_parameter() - Sets a parameter
px_set_value
(PECL paradox >= 1.1.0)
px_set_value — Sets a value
Opis
$pxdoc
, string $name
, float $value
)Sets various values.
Parametry
-
pxdoc -
Resource identifier of the paradox database as returned by px_new().
-
name -
namecan be one of the following.- numprimkeys
-
The number of primary keys. Paradox databases always use the first numprimkeys fields for the primary index.
-
value -
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
px_set_parameter() - Sets a parameter
px_timestamp2string
(PECL paradox >= 1.4.0)
px_timestamp2string — Converts the timestamp into a string.
Opis
$pxdoc
, float $value
, string $format
)Turns a timestamp as it stored in the paradox file into human readable format. Paradox timestamps are the number of miliseconds since 0001-01-02. This function is just for convenience. It can be easily replaced by some math and the calendar functions as demonstrated in the following example.
Parametry
-
pxdoc -
Resource identifier of the paradox database.
-
value -
Value as stored in paradox database field of type PX_FIELD_TIME, or PX_FIELD_TIMESTAMP.
-
format -
String format similar to the format used by date(). The placeholders support by this function is a subset of those supported by date() (Y, y, m, n, d, j, H, h, G, g, i, s, A, a, L).
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Turn a paradox timestamp into a human readable form
<?php
$px = px_new();
/* make up a date as it could be stored in */
/* a date field of a paradox db. */
/* 700000 days since 1.1.0000. */
$days = 700000;
/* Use the calendar functions to print a */
/* human readable format of the date */
echo jdtogregorian($days+1721425)."\n";
/* Turn it into a timestamp as it stored in a paradox database */
/* Timestamps are stored in miliseconds since 0001-01-02 */
$stamp = $days * 86400.0 * 1000.0;
/* Add one hour */
$stamp += 3600000.0;
/* The following will output '7/15/1917 01:00:00'. */
echo px_timestamp2string($px, $stamp, "n/d/Y H:i:s")."\n";
px_delete($px);
?>
Powyższy przykład wyświetli:
7/15/1917 7/15/1917 01:00:00
The Julian day count as passed to jdtogregorian() has a different base of 1.1.4714 b.c. and must therefore be calculated by adding 1721425 to the day count used in the paradox file. Turning the day count into a timestamp is easily done by multiplying with 86400000.0 to obtain miliseconds.
Zobacz też:
- px_date2string() - Converts a date into a string.
- jdtogregorian() - Converts Julian Day Count to Gregorian date
px_update_record
(PECL paradox >= 1.4.0)
px_update_record — Updates record in paradox database
Opis
$pxdoc
, array $data
, int $num
)Updates an exiting record in the database. The record starts at 0.
The record data is passed as an array of field values. The elements in the array must correspond to the fields in the database. If the array has less elements than fields in the database, the remaining fields will be set to null.
Informacja:
This function is only available if pxlib >= 0.6.0 is used.
Parametry
-
pxdoc -
Resource identifier of the paradox database as returned by px_new().
-
data -
Associated array containing the field values as returned by px_retrieve_record().
-
num -
The record number is an artificial number counting records in the order as they are stored in the database. The first record has number 0.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
px_insert_record() - Inserts record into paradox database
Spis treści
- px_close — Closes a paradox database
- px_create_fp — Create a new paradox database
- px_date2string — Converts a date into a string.
- px_delete_record — Deletes record from paradox database
- px_delete — Deletes resource of paradox database
- px_get_field — Returns the specification of a single field
- px_get_info — Return lots of information about a paradox file
- px_get_parameter — Gets a parameter
- px_get_record — Returns record of paradox database
- px_get_schema — Returns the database schema
- px_get_value — Gets a value
- px_insert_record — Inserts record into paradox database
- px_new — Create a new paradox object
- px_numfields — Returns number of fields in a database
- px_numrecords — Returns number of records in a database
- px_open_fp — Open paradox database
- px_put_record — Stores record into paradox database
- px_retrieve_record — Returns record of paradox database
- px_set_blob_file — Sets the file where blobs are read from
- px_set_parameter — Sets a parameter
- px_set_tablename — Sets the name of a table (deprecated)
- px_set_targetencoding — Sets the encoding for character fields (deprecated)
- px_set_value — Sets a value
- px_timestamp2string — Converts the timestamp into a string.
- px_update_record — Updates record in paradox database
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Paradox Funkcje
- px_close — Closes a paradox database
- px_create_fp — Create a new paradox database
- px_date2string — Converts a date into a string.
- px_delete_record — Deletes record from paradox database
- px_delete — Deletes resource of paradox database
- px_get_field — Returns the specification of a single field
- px_get_info — Return lots of information about a paradox file
- px_get_parameter — Gets a parameter
- px_get_record — Returns record of paradox database
- px_get_schema — Returns the database schema
- px_get_value — Gets a value
- px_insert_record — Inserts record into paradox database
- px_new — Create a new paradox object
- px_numfields — Returns number of fields in a database
- px_numrecords — Returns number of records in a database
- px_open_fp — Open paradox database
- px_put_record — Stores record into paradox database
- px_retrieve_record — Returns record of paradox database
- px_set_blob_file — Sets the file where blobs are read from
- px_set_parameter — Sets a parameter
- px_set_tablename — Sets the name of a table (deprecated)
- px_set_targetencoding — Sets the encoding for character fields (deprecated)
- px_set_value — Sets a value
- px_timestamp2string — Converts the timestamp into a string.
- px_update_record — Updates record in paradox database
PostgreSQL
Wstęp
Baza danych PostgreSQL jest otwartym oprogramowaniem, dostępnym bez ponoszenia opłat. Postgres, tworzony początkowo na Wydziale Nauk Komputerowych Uniwersytetu Berkeley, był pionierem wielu koncepcji obiektowo-relacyjnych, obecnie dostępnych w niektórych komercyjnych bazach danych. Jest zgodny ze standardami języków SQL92/SQL99, obsługuje transakcje, integralność referencji, procedury składowane, i pozwala definiować własne typy danych. PostgreSQL jest wolnodostępnym spadkobiercą oryginalnego kodu Berkeley.
Instalacja/Konfiguracja
Spis treści
Wymagania
PHP obsługuje PostgreSQL w wersji 6.5 lub nowszej. Aby używać wszystkich właściwości rozszerzenia wymagana jest baza danych PostgreSQL 8.0 lub nowsza. PostgreSQL obsługuje wiele kodowań znaków, włącznie z wielobajtowym. Bieżące wydanie, oraz więcej informacji na temat PostgreSQL jest dostępnych na witrynach: » http://www.postgresql.org/ i » Dokumentacja PostgreSQL.
Instalacja
W celu uruchomienia obsługi bazy danych PostgreSQL, należy w czasie kompilacji PHP użyć opcji konfiguracyjnej --with-pgsql[=DIR] , gdzie DIR jest katalogiem instalacji PostgreSQL, domyślnie /usr/local/pgsql. Jeśli jest dostępny moduł współdzielony, rozszerzenie PostgreSQL może być załadowane przez wpisanie dyrektywy extension w pliku php.ini lub za pomocą funkcji dl().
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Wartość domyślna | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| pgsql.allow_persistent | "1" | PHP_INI_SYSTEM | |
| pgsql.max_persistent | "-1" | PHP_INI_SYSTEM | |
| pgsql.max_links | "-1" | PHP_INI_SYSTEM | |
| pgsql.auto_reset_persistent | "0" | PHP_INI_SYSTEM | Dostępna od PHP 4.2.0. |
| pgsql.ignore_notice | "0" | PHP_INI_ALL | Dostępna od PHP 4.3.0. |
| pgsql.log_notice | "0" | PHP_INI_ALL | Dostępna od PHP 4.3.0. |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
pgsql.allow_persistentboolean -
Określa czy pozwolić bazie PostgreSQL na połączenia stałe.
-
pgsql.max_persistentinteger -
Definiuje maksymalną liczbę połączeń stałych PostgreSQL na proces serwera.
-
pgsql.max_linksinteger -
Definiuje maksymalną liczbę połączeń PostgreSQL na proces serwera, włączając w to połączenia stałe.
-
pgsql.auto_reset_persistentinteger -
Wykrywa błędne identyfikatory połączeń utworzone za pomocą pg_pconnect(). Potrzebuje niewielkiego kosztu obciążenia.
-
pgsql.ignore_noticeinteger -
Określa czy ignorować powiadomienia o uwagach zwracane przez PostgreSQL.
-
pgsql.log_noticeinteger -
Określa czy logować powiadomienia o uwagach zwracane przez PostgreSQL. Dyrektywa PHP pgsql.ignore_notice musi być wyłączona, żeby możliwe było logowanie powiadomień o uwagach.
Typy zasobów
Istnieją dwa typy zasobów używanych przez rozszerzenie PostgreSQL. Pierwszy to identyfikator połączenia z bazą danych. Natomiast drugi przechowuje wynik zapytania.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
-
PGSQL_ASSOC(integer) - Passed to pg_fetch_array(). Return an associative array of field names and values.
-
PGSQL_NUM(integer) - Passed to pg_fetch_array(). Return a numerically indexed array of field numbers and values.
-
PGSQL_BOTH(integer) - Passed to pg_fetch_array(). Return an array of field values that is both numerically indexed (by field number) and associated (by field name).
-
PGSQL_CONNECT_FORCE_NEW(integer) - Passed to pg_connect() to force the creation of a new connection, rather than re-using an existing identical connection.
-
PGSQL_CONNECTION_BAD(integer) - Returned by pg_connection_status() indicating that the database connection is in an invalid state.
-
PGSQL_CONNECTION_OK(integer) - Returned by pg_connection_status() indicating that the database connection is in a valid state.
-
PGSQL_SEEK_SET(integer) - Passed to pg_lo_seek(). Seek operation is to begin from the start of the object.
-
PGSQL_SEEK_CUR(integer) - Passed to pg_lo_seek(). Seek operation is to begin from the current position.
-
PGSQL_SEEK_END(integer) - Passed to pg_lo_seek(). Seek operation is to begin from the end of the object.
-
PGSQL_EMPTY_QUERY(integer) - Returned by pg_result_status(). The string sent to the server was empty.
-
PGSQL_COMMAND_OK(integer) - Returned by pg_result_status(). Successful completion of a command returning no data.
-
PGSQL_TUPLES_OK(integer) - Returned by pg_result_status(). Successful completion of a command returning data (such as a SELECT or SHOW).
-
PGSQL_COPY_OUT(integer) - Returned by pg_result_status(). Copy Out (from server) data transfer started.
-
PGSQL_COPY_IN(integer) - Returned by pg_result_status(). Copy In (to server) data transfer started.
-
PGSQL_BAD_RESPONSE(integer) - Returned by pg_result_status(). The server's response was not understood.
-
PGSQL_NONFATAL_ERROR(integer) - Returned by pg_result_status(). A nonfatal error (a notice or warning) occurred.
-
PGSQL_FATAL_ERROR(integer) - Returned by pg_result_status(). A fatal error occurred.
-
PGSQL_TRANSACTION_IDLE(integer) - Returned by pg_transaction_status(). Connection is currently idle, not in a transaction.
-
PGSQL_TRANSACTION_ACTIVE(integer) - Returned by pg_transaction_status(). A command is in progress on the connection. A query has been sent via the connection and not yet completed.
-
PGSQL_TRANSACTION_INTRANS(integer) - Returned by pg_transaction_status(). The connection is idle, in a transaction block.
-
PGSQL_TRANSACTION_INERROR(integer) - Returned by pg_transaction_status(). The connection is idle, in a failed transaction block.
-
PGSQL_TRANSACTION_UNKNOWN(integer) - Returned by pg_transaction_status(). The connection is bad.
-
PGSQL_DIAG_SEVERITY(integer) - Passed to pg_result_error_field(). The severity; the field contents are ERROR, FATAL, or PANIC (in an error message), or WARNING, NOTICE, DEBUG, INFO, or LOG (in a notice message), or a localized translation of one of these. Always present.
-
PGSQL_DIAG_SQLSTATE(integer) - Passed to pg_result_error_field(). The SQLSTATE code for the error. The SQLSTATE code identifies the type of error that has occurred; it can be used by front-end applications to perform specific operations (such as error handling) in response to a particular database error. This field is not localizable, and is always present.
-
PGSQL_DIAG_MESSAGE_PRIMARY(integer) - Passed to pg_result_error_field(). The primary human-readable error message (typically one line). Always present.
-
PGSQL_DIAG_MESSAGE_DETAIL(integer) - Passed to pg_result_error_field(). Detail: an optional secondary error message carrying more detail about the problem. May run to multiple lines.
-
PGSQL_DIAG_MESSAGE_HINT(integer) - Passed to pg_result_error_field(). Hint: an optional suggestion what to do about the problem. This is intended to differ from detail in that it offers advice (potentially inappropriate) rather than hard facts. May run to multiple lines.
-
PGSQL_DIAG_STATEMENT_POSITION(integer) - Passed to pg_result_error_field(). A string containing a decimal integer indicating an error cursor position as an index into the original statement string. The first character has index 1, and positions are measured in characters not bytes.
-
PGSQL_DIAG_INTERNAL_POSITION(integer) -
Passed to pg_result_error_field().
This is defined the same as the
PG_DIAG_STATEMENT_POSITIONfield, but it is used when the cursor position refers to an internally generated command rather than the one submitted by the client. ThePG_DIAG_INTERNAL_QUERYfield will always appear when this field appears. -
PGSQL_DIAG_INTERNAL_QUERY(integer) - Passed to pg_result_error_field(). The text of a failed internally-generated command. This could be, for example, a SQL query issued by a PL/pgSQL function.
-
PGSQL_DIAG_CONTEXT(integer) - Passed to pg_result_error_field(). An indication of the context in which the error occurred. Presently this includes a call stack traceback of active procedural language functions and internally-generated queries. The trace is one entry per line, most recent first.
-
PGSQL_DIAG_SOURCE_FILE(integer) - Passed to pg_result_error_field(). The file name of the PostgreSQL source-code location where the error was reported.
-
PGSQL_DIAG_SOURCE_LINE(integer) - Passed to pg_result_error_field(). The line number of the PostgreSQL source-code location where the error was reported.
-
PGSQL_DIAG_SOURCE_FUNCTION(integer) - Passed to pg_result_error_field(). The name of the PostgreSQL source-code function reporting the error.
-
PGSQL_ERRORS_TERSE(integer) - Passed to pg_set_error_verbosity(). Specified that returned messages include severity, primary text, and position only; this will normally fit on a single line.
-
PGSQL_ERRORS_DEFAULT(integer) - Passed to pg_set_error_verbosity(). The default mode produces messages that include the above plus any detail, hint, or context fields (these may span multiple lines).
-
PGSQL_ERRORS_VERBOSE(integer) - Passed to pg_set_error_verbosity(). The verbose mode includes all available fields.
-
PGSQL_STATUS_LONG(integer) - Passed to pg_result_status(). Indicates that numerical result code is desired.
-
PGSQL_STATUS_STRING(integer) - Passed to pg_result_status(). Indicates that textual result command tag is desired.
-
PGSQL_CONV_IGNORE_DEFAULT(integer) - Passed to pg_convert(). Ignore default values in the table during conversion.
-
PGSQL_CONV_FORCE_NULL(integer) - Passed to pg_convert(). Use SQL NULL in place of an empty string.
-
PGSQL_CONV_IGNORE_NOT_NULL(integer) -
Passed to pg_convert().
Ignore conversion of
NULLinto SQL NOT NULL columns.
Przykłady
Spis treści
Podstawowe użycie
Ten nieskomplikowany przykład pokazuje jak można nawiązać połączenie, wykonać zapytanie, wyświetlić wyniki i rozłączyć się z bazą danych PostgreSQL.
Przykład #1 Przykład działania rozszerzenia PostgreSQL
<?php
// Nawiązanie połączenia, wybór bazy danych
$dbconn = pg_connect("host=localhost dbname=publikacje user=www password=tajne")
or die('Nie można nawiązać połączenia: ' . pg_last_error());
// Wykonanie zapytania SQL
$query = 'SELECT * FROM authors';
$result = pg_query($query) or die('Nieprawidłowe zapytanie: ' . pg_last_error());
// Wyświetlenie wyników w postaci HTML
echo "<table>\n";
while ($line = pg_fetch_array($result, null, PGSQL_ASSOC)) {
echo "\t<tr>\n";
foreach ($line as $col_value) {
echo "\t\t<td>$col_value</td>\n";
}
echo "\t</tr>\n";
}
echo "</table>\n";
// Zwolnienie zasobów wyniku zapytania
pg_free_result($result);
// Zamknięcie połączenia
pg_close($dbconn);
?>
Funkcje PostgreSQL
Notatki
Informacja:
Nie wszystkie funkcje są obsługiwane w każdym wydaniu. To zależy od wersji libpq ( Interfejs C klienta PostgreSQL ) oraz sposobu w jaki został on skompilowany. Jeśli brakuje niektórych właściwości, to bardzo możliwe, że libpq ich nie obsługuje.
Informacja:
Większość funkcji PostgreSQL posiada
connectionjako pierwszy, opcjonalny parametr. Jeśli nie jest on podawany, to używane jest ostatnio otwarte połączenie. Jeśli ono nie istnieje, to funkcje zwracająFALSE.
Informacja:
Podczas tworzenia obiektów oraz wykonywania zapytań PostgreSQL zamienia automatycznie na małe litery wszystkie identyfikatory (np. nazwy tabel, kolumn). Aby wymusić używanie dużych i małych liter w nazwach identyfikatorów należy umieszczać je w znakach unikowych - podwójnych cudzysłowach ("").
Informacja:
PostgreSQL nie posiada specjalnych poleceń do pobierania informacji o schemacie bazy danych (np. wszystkich tabelach w bieżącej bazie danych). Zamiast tego istnieje niestandardowy schemat nazwany information_schema. W PostgreSQL 7.4 i nowszych można pobierać z niego za pomocą zapytań SQL widoki systemowe i inne niezbędne informacje. Szczegółowe informacje na ten temat znajdują się w » Dokumentacja PostgreSQL
pg_affected_rows
(PHP 4 >= 4.2.0, PHP 5)
pg_affected_rows — Zwraca liczbę zmodyfikowanych wierszy
Opis
$result
)pg_affected_rows() zwraca liczbę wierszy dodanych, zmodyfikowanych lub usuniętych przez zapytania INSERT, UPDATE i DELETE.
Informacja:
Ta funkcja była nazwana pg_cmdtuples().
Parametry
-
result -
Zasób, wynik zapytania PostgreSQL, zwrócony przez pg_query(), pg_query_params() lub pg_execute() (wśród innych).
Zwracane wartości
Liczba wierszy na które wpływ ma zapytanie. Jeśli nie wystąpił taki wiersz, zostanie zwrócone 0.
Przykłady
Przykład #1 pg_affected_rows() przykład
<?php
$result = pg_query($conn, "INSERT INTO authors VALUES ('Orwell', 2002, 'Animal Farm')");
$cmdtuples = pg_affected_rows ($result);
echo $cmdtuples . " wiersz(e), na które miało wpływ zapytanie.\n";
?>
Powyższy przykład wyświetli:
1 wiersz(e), na które miało wpływ zapytanie.
Zobacz też:
- pg_query() - Realizujezapytanie do bazy danych
- pg_query_params() - Submits a command to the server and waits for the result, with the ability to pass parameters separately from the SQL command text.
- pg_execute() - Sends a request to execute a prepared statement with given parameters, and waits for the result.
- pg_num_rows() - Zwraca liczbę wierszy
pg_cancel_query
(PHP 4 >= 4.2.0, PHP 5)
pg_cancel_query — Przerywa zapytanie asynchroniczne
Opis
$połączenie
)pg_cancel_query() przerywa zapytanie asynchroniczne wysłane przez pg_send_query(), pg_send_query_params() lub pg_send_execute(). Nie można przerwać zapytania uruchomionego przez pg_query().
Parametry
-
połączenie -
Zasób, połączenie do bazy PostgreSQL.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 pg_cancel_query() przykład
<?php
$dbconn = pg_connect("dbname=publisher") or die("Nie można połączyć się");
if (!pg_connection_busy($dbconn)) {
pg_send_query($dbconn, "select * from authors; select count(*) from authors;");
}
$res1 = pg_get_result($dbconn);
echo "Pierwsze wywołanie pg_get_result(): $res1\n";
$rows1 = pg_num_rows($res1);
echo "$res1 ma $rows1 rekordów\n\n";
// Anuluj obecnie działające zapytanie. Będzie to drugie zapytanie, jeśli się
// jeszcze wykonuje.
pg_cancel_query($dbconn);
?>
Powyższy przykład wyświetli:
Pierwsze wywołanie pg_get_result(): Resource id #3 Resource id #3 ma 3 rekordów
Zobacz też:
- pg_send_query() - Wysyła zapytanie asynchroniczne
- pg_connection_busy() - Sprawdza czy połączenie jest zajęte czy wolne
pg_client_encoding
(PHP 4 >= 4.0.3, PHP 5)
pg_client_encoding — Zwraca stronę kodową klienta
Opis
$połączenie
] )PostgreSQL wspiera automatyczną konwersję zestawu znaków pomiędzy serwerem, a klientem dla pewnych systemów kodowania. pg_client_encoding() zwraca stronę kodową klienta jako łańcuch. Zwracany łańcuch będzie jednym ze standardowych identyfikatorów kodowania PostgreSQL.
Informacja:
Ta funkcja wymaga PHP 4.0.3 lub nowszego i PostgreSQL 7.0 lub nowszego. Jeśli libpq jest skompilowane bez wsparcia dla kodowania wielobajtowego, pg_client_encoding() zawsze zwraca SQL_ASCII. Wspierane strony kodowe zależą od wersji PostgreSQL. Sprawdź dokumentację PostgreSQL o wspieranych kodowaniach.
Ta funkcja była poprzednio nazywana pg_clientencoding().
Parametry
-
połączenie -
Zasób, połączenie do bazy PostgreSQL. Kiedy parametr
połączenienie jest podany, użyte zostanie domyślne połączenie. Domyślne połączenie to ostatnie połączenie utworzone przez pg_connect() lub pg_pconnect().
Zwracane wartości
Kodowanie klienta, lub FALSE w przypadku błędu.
Przykłady
Przykład #1 pg_client_encoding() przykład
<?php
// Zakładamy, że $conn jest połączeniem do bazy w ISO-8859-1
$encoding = pg_client_encoding($conn);
echo "Kodowanie klienta to: ", $encoding, "\n";
?>
Powyższy przykład wyświetli:
Kodowanie klienta to: ISO-8859-1
pg_close
(PHP 4, PHP 5)
pg_close — Zamyka połączenie z PostgreSQL
Opis
$połączenie
] )
pg_close() zamyka tymczasowe połączenie z
serwerem PostgreSQL związane z podanym parametrem
połączenie.
Informacja:
Używanie pg_close() jest z reguły niepotrzebne, jako że połączenia tymczasowe są zamykane automatycznie po zakończeniu wykonywania skryptu.
Nie wolno zamykać połączenia jeśli jest otwarty wielki obiekt. W pierwszej kolejności należy zamknąć wszystkie wielkie obiekty.
Parametry
-
połączenie -
Zasób, połączenie do bazy PostgreSQL. Kiedy parametr
połączenienie jest podany, użyte zostanie domyślne połączenie. Domyślne połączenie to ostatnie połączenie utworzone przez pg_connect() lub pg_pconnect().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 pg_close() przykład
<?php
$dbconn = pg_connect("host=localhost port=5432 dbname=mary")
or die("Nie można się połączyć");
echo "Poprawnie połączono";
pg_close($dbconn);
?>
Powyższy przykład wyświetli:
Poprawnie połączono
pg_connect
(PHP 4, PHP 5)
pg_connect — Otwiera tymczasowe połączenie do PostgreSQL-a
Opis
$łąńcuch_połączenia
[, int $typ_połączenia
] )
pg_connect() Otwiera tymczasowe połączenie do serwera
PostgreSQL określonego przez łąńcuch_połączenia.
Jeśli funkcja pg_connect() zostanie wywołana drugi raz z
tym samym łąńcuchem_połączenia jak istniejące połączenie,
zostanie zwrócony identyfikator istniejącego połączenia chyba, że podasz
PGSQL_CONNECT_FORCE_NEW jako
typ_połączenia.
Stara składnia z wieloma parametrami $conn = pg_connect("host", "port", "opcje", "tty", "nazwa_bazy") jest przestarzała.
Parametry
-
łąńcuch_połączenia -
łąńcuch_połączeniamoże być pusty, użyte zostaą wszystkie domyślne parametry lub może zawierać jeden lub więcej parametrów ustawień oddzielonych przez biały znak. Każdy parametr ustawień jest w postaci słowo_kluczowe = wartość. Odstępy wokół znaku równości są opcjonalne. Aby zapisać pustą wartość lub wartość zawierającą spacje, należy otoczyć ją przez pojedynczy cudzysłów, np. słowo_kluczowe = 'ta wartość'. Pojedyncze cudzysłowy i lewe ukośniki w wartości musza być poprzedzone znakiem unikowym (lewym ukośnikiem) tj. \' i \\Obecnie rozpoznwane parametry słów kluczowych to:
host,hostaddr,port,dbname,user,password,connect_timeout,options,tty(ignorowany),sslmode,requiressl(przestarzały na rzeczsslmode) iservice. Które z tych parametrów istnieją zależy od Twojej wersji PostgreSQL. -
typ_połączenia -
Jeśli jest podany
PGSQL_CONNECT_FORCE_NEW, wtedy nowe połączenie jest tworzone, nawet jeśliłąńcuch_połączeniajest identyczny z istniejącym połączeniem.
Zwracane wartości
Zasób, połączenie do bazy PostgreSQL w przypadku powodzenia, lub FALSE gdy zawiedzie.
Przykłady
Przykład #1 Używanie pg_connect
<?php
$dbconn = pg_connect ("dbname=mary");
//Otwiera połączenie z bazą "mary"
$dbconn2 = pg_connect ("host=localhost port=5432 dbname=mary");
//Otwiera połączenie z bazą "mary" na komputerze "localhost" przez port "5432"
$dbconn3 = pg_connect ("host=sheep port=5432 dbname=mary user=lamb password=foo");
//Otwiera połączenie z bazą "mary" na komputerze "sheep" z użyciem nazwy użytkownika i hasła
$conn_string = "host=sheep port=5432 dbname=test user=lamb password=bar";
$dbconn4 = pg_connect ($conn_string);
//Otwiera połączenie z bazą "test" na komputerze "sheep" z użyciem nazwy użytkownika i hasła
?>
Zobacz też:
- pg_pconnect() - Otwiera trwałe połączenie z serwerem PostgreSQL
- pg_close() - Zamyka połączenie z PostgreSQL
- pg_host() - Zwraca nazwę komputera związanego z połączeniem
- pg_port() - Zwraca numer portu związany z połączeniem
- pg_tty() - Zwraca nazwę konsoli tty związanej z połączeniem
- pg_options() - Podaje opcje powiązane z połączenim
- pg_dbname() - Podaje nazwę bazy danych
pg_connection_busy
(PHP 4 >= 4.2.0, PHP 5)
pg_connection_busy — Sprawdza czy połączenie jest zajęte czy wolne
Opis
$połączenie
)pg_connection_busy() sprawdza czy połączenie jest zajęte. Jeśli jest zajęte, poprzednie zapytanie jest wciąż wykonywane. Jeśli pg_get_result() jest użyte na połączeniu, zostanie ono zablokowane.
Parametry
-
połączenie -
Zasób, połączenie do bazy PostgreSQL.
Zwracane wartości
Zwraca TRUE jeśli połączenie jest zajęte, FALSE w przeciwnym wypadku.
Przykłady
Przykład #1 pg_connection_busy() przykład
<?php
$dbconn = pg_connect("dbname=publisher") or die("Nie można się połączyć");
$bs = pg_connection_busy($dbconn);
if ($bs) {
echo 'połączenie jest zajęte';
} else {
echo 'połączenie jest wolne';
}
?>
Zobacz też:
- pg_connection_status() - Zwraca stan połączenia
- pg_get_result() - Pobiera wynik zapytania asynchroniczego
pg_connection_reset
(PHP 4 >= 4.2.0, PHP 5)
pg_connection_reset — Restartuje połączenie
Opis
$połączenie
)pg_connection_reset() restartuje połączenie. Jest użyteczne w sytuacja awaryjnych.
Parametry
-
połączenie -
Zasób, połączenie do bazy PostgreSQL.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 pg_connection_reset() przykład
<?php
$dbconn = pg_connect("dbname=publisher") or die("Nie można się połączyć");
$dbconn2 = pg_connection_reset($dbconn);
if ($dbconn2) {
echo "restart poprawny\n";
} else {
echo "restart nie powiódł się\n";
}
?>
Zobacz też:
- pg_connect() - Otwiera tymczasowe połączenie do PostgreSQL-a
- pg_pconnect() - Otwiera trwałe połączenie z serwerem PostgreSQL
- pg_connection_status() - Zwraca stan połączenia
pg_connection_status
(PHP 4 >= 4.2.0, PHP 5)
pg_connection_status — Zwraca stan połączenia
Opis
$połączenie
)
pg_connection_status() zwraca status
podanego połączenia.
Parametry
-
połączenie -
Zasób, połączenie do bazy PostgreSQL.
Zwracane wartości
PGSQL_CONNECTION_OK lub
PGSQL_CONNECTION_BAD.
Przykłady
Przykład #1 pg_connection_status() przykład
<?php
$dbconn = pg_connect("dbname=publisher") or die("Nie można się połączyć");
$stat = pg_connection_status($dbconn);
if ($stat === PGSQL_CONNECTION_OK) {
echo 'Status połączenia ok';
} else {
echo 'Status połączenia bad';
}
?>
pg_convert
(PHP 4 >= 4.3.0, PHP 5)
pg_convert — Konwertuje tablice asocjacyjne na postać użyteczną w zapytaniu SQL.
Opis
$połączenie
, string $nazwa_tabeli
, array $tablica_asocjacyjna
[, int $opcje
] )
pg_convert() sprawdza i konwertuje wartości w
tablica_asocjacyjna na postać użyteczną dla
zapytania SQL. Warunkiem koniecznym dla pg_convert() jest
istnienie tabeli nazwa_tabeli, ktora ma przynajmniej
tyle kolumn, ile tablica_asocjacyjna ma elementów. Nazwy
pól w nazwa_tabeli muszą pasować do indeksów w parametrze
tablica_asocjacyjna i odpowiednie typy danych muszą być
zgodne. Zwraca tabelę z przekonwertowanymi wartościami w razie sukcesu, FALSE
w przeciwnym wypadku.
Informacja:
Jeśli istnieją pola typu boolean w
nazwa_tabeli, nie używaj stałej wartościTRUEw parametrzetablica_asocjacyjna. Zostanie on przekonwertowany do łańcucha 'TRUE', który nie jest poprawnym wpisem dla pól typu boolean w PostgreSQL. W zamian użyj jednej z propozycji: t, true, 1, y, yes.
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Parametry
-
połączenie -
Źródło połączenia do bazy PostgreSQL.
-
nazwa_tabeli -
Nazwa tabeli, w stosunku do której będą konwertowane typy.
-
tablica_asocjacyjna -
Dane do konwersji.
-
options -
Kombinacja dowolnej ilości poniższych stałych:
PGSQL_CONV_IGNORE_DEFAULT,PGSQL_CONV_FORCE_NULLlubPGSQL_CONV_IGNORE_NOT_NULL.
Zwracane wartości
Typ tablicowy (ang. array) z przekonwertowanymi wartościami, lub FALSE w razie błędu.
Przykłady
Przykład #1 pg_convert() - przykład
<?php
$polaczenie = pg_connect('dbname=foo');
$tmp = array(
'autor' => 'Jan Hakreski',
'rok' => 2005,
'tytuł' => 'Życie Jana Hakerskiego'
);
$wartosci = pg_convert($polaczenie, 'autorzy', $tmp);
?>
pg_copy_from
(PHP 4 >= 4.2.0, PHP 5)
pg_copy_from — Wstawia wiersze do tabeli z tablicy
Opis
$połączenie
, string $nazwa_tabeli
, array $wiersze
[, string $delimiter
[, string $null_jako
]] )
pg_copy_from() wstawia wiersze do tabeli z tablicy
wiersze. Wywołuje wewnętrznie polecenie SQL COPY FROM
aby wstawić wiersze.
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Parametry
-
połączenie -
Zasób, połączenie do bazy danych PostgreSQL.
-
nazwa_tabeli -
Nazwa tabeli do której będą kopiowane
wiersze. -
wiersze -
Tablica danych, które będą skopiowane do
nazwa_tabeli. Każda wartość wwierszestanie się wierszem wnazwa_tabeli. Każda wartość wwierszepowinna być łańcuchem znaków rozdzielonych wartości do wstawienia w każde pole. Wartości powinny być zakończone przejściem do nowej linii. -
delimiter -
Symbol jaki rozdziela wartości dla każdego pola w każdym elemencie
wiersza. Domyślnie jest to TAB. -
null_jako -
Jak wartość SQL NULL jest reprezentowana w
wierszu. Domyślnie jest to \N ("\\N").
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 pg_copy_from() przykład
<?php
$db = pg_connect("dbname=publisher") or die("Nie można się połączyć");
$rows = pg_copy_to($db, $table_name);
pg_query($db, "DELETE FROM $table_name");
pg_copy_from($db, $table_name, $rows);
?>
pg_copy_to
(PHP 4 >= 4.2.0, PHP 5)
pg_copy_to — Kopiuje tabelę do tablicy
Opis
$polaczenie
, string $nazwa_tabeli
[, string $separator
[, string $null_jako
]] )pg_copy_to() kopiuje tabelę do tablicy. Wywołuje to wewnętrzne polecenie SQL COPY TO na wydobywane rekordy.
Parametry
-
polaczenie -
Identyfikator połączenia do serwera PostgreSQL.
-
nazwa_tabeli -
Nazwa tabeli, z której zostaną skopiowane dane do zmiennej
wiersze. -
separator -
Znak oddzielający wartości dla każdego pola każdego elementu zmiennej
wiersze. Domyślnie jest to TAB. -
null_jako -
Jak wartości NULL z SQL są przedstawiane w zmiennej
wiersze. Domyślnie jest to \N ("\\N").
Zwracane wartości
Tablica (ang. array) z jednym elementem dla każdej linii kopiowanych (COPY) danych.
Zwraca FALSE w przypadku błędu.
Przykłady
Przykład #1 pg_copy_to() - przykład
<?php
$baza = pg_connect("dbname=wydawca") or die("Nie można się połączyć");
$wiersze = pg_copy_to($baza, $nazwa_tabeli);
pg_query($baza, "DELETE FROM $nazwa_tabeli");
pg_copy_from($baza, $nazwa_tabeli, $wiersze);
?>
pg_dbname
(PHP 4, PHP 5)
pg_dbname — Podaje nazwę bazy danych
Opis
$polaczenie
] )
pg_dbname() zwraca nazwę bazy danych dla
podanego identyfikatora połączenia
(polaczenie).
Parametry
-
polaczenie -
Identyfikator połączenia do bazy PostgreSQL. Gdy nie podano parametru
polaczenie, domyślne połączenie jest użyte. Domyślnym połączeniem jest ostatnie połączenie stworzone przez pg_connect() lub pg_pconnect().
Zwracane wartości
Łańcuch (ang. string) zawierający nazwę bazy danych, do której
polaczenie jest nawiązane, lub FALSE w przypadku błędu.
Przykłady
Przykład #1 pg_dbname() - przykład
<?php
error_reporting(E_ALL);
pg_connect("host=localhost port=5432 dbname=mary");
echo pg_dbname(); // mary
?>
pg_delete
(PHP 4 >= 4.3.0, PHP 5)
pg_delete — Usuwa rekordy
Opis
$identyfikator_połączenia
, string $nazwa_tabeli
, array $tablica_asocjacyjna
[, int $opcje
] )
pg_delete() usuwa wiersze z tabeli określonej przez
klucze i wartości w parametrze tablica_asocjacyjna. Jeśli opcje zostały
określone, to funkcja pg_convert() stosuje
do parametru tablica_asocjacyjna podane opcje.
Parametry
-
identyfikator_połączenia -
Identyfikator połączenia do bazy PostgreSQL.
-
nazwa_tabeli -
Nazwa tabeli, z której będą usuwane wiersze.
-
tablica_asocjacyjna -
Tablica (ang. array), której klucze są nazwami pól w określonej parametrem
nazwa_tabelitabeli, oraz której wartościami, są wartości tych pól, które mają zostać usunięte. -
opcje -
Dowolna kombinacja, dowolnej ilości parametrów:
PGSQL_CONV_FORCE_NULL,PGSQL_DML_NO_CONV,PGSQL_DML_EXECorazPGSQL_DML_STRING. JeśliPGSQL_DML_STRINGjest jedną z podanych w parametrzeopcjeopcji, zostanie zwrócony łańcuch zapytania z URL (ang. query string).
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu. Zwraca łańcuch (ang. string) gdy podano PGSQL_DML_STRING
poprzez opcje.
Przykłady
Przykład #1 pg_delete() - przykład
<?php
$polaczenie_do_bazy = pg_connect ('dbname=foo');
// To jest bezpieczne, odkąd $_POST jest konwertowane automatycznie
$res = pg_delete($polaczenie_do_bazy, 'kopia_post', $_POST);
if ($res) {
echo "Dane określone przez POST zostały usunięte: $res\n";
} else {
echo "Użytkownik wprowadził błędne dane\n";
}
?>
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
pg_end_copy
(PHP 4 >= 4.0.3, PHP 5)
pg_end_copy — Synchronizuje klienta z serwerem PostgreSQL.
Opis
$polaczenie
] )pg_end_copy() synchronizuje klienta PostgreSQL z serwerem po wykonaniu operacji kopiowania przez funkcję pg_put_line(). Funkcja pg_end_copy() musi być wywołana, inaczej serwer PostgreSQL-a może być niezsychronizowany z klientem i może wystąpić błąd.
Parametry
-
polaczenie -
Identyfikator połączenia do bazy danych PostgreSQL. Gdy
polaczenienie zostało podane, domyślne połączenie jest użyte. Domyślnym połączeniem jest ostatnie połączenie stworzone przez pg_connect() lub pg_pconnect().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 pg_end_copy() - przykład
<?php
$polaczenie = pg_pconnect("dbname=foo");
pg_query($polaczenie, "create table bar (a int4, b char(16), d float8)");
pg_query($polaczenie, "copy bar from stdin");
pg_put_line($polaczenie, "3\twitaj świecie\t4.5\n");
pg_put_line($polaczenie, "4\tżegnaj świecie\t7.11\n");
pg_put_line($polaczenie, "\\.\n");
pg_end_copy($polaczenie);
?>
pg_escape_bytea
(PHP 4 >= 4.2.0, PHP 5)
pg_escape_bytea — Konwertuje łańcuch wstawiając sekwencje Escape dla typu bytea
Opis
$połączenie
], string $dane
)pg_escape_bytea() konwertuje łańcuch wstawiając sekwencje Escape dla typu bytea. Zwraca łańcuch z sekwencjami Escape.
Informacja:
Przy wywołaniu SELECT dla typu bytea, PostgrSQL zwraca łańcuchy zawierające wartości ósemkowe poprzedzone znakiem "\" (np. \032). Użytkownicy muszą samodzielnie odkodować te dane.
Ta funkcja wymaga PostgreSQL 7.2 lub nowszego. Dla PostgreSQL 7.2.0 i 7.2.1, wartości bytea muszą być wskazane jeśli uruchomisz wsparcie dla kodowania wielobajtowego np. INSERT INTO tabela_testowa (obraz) VALUES ('$image_escaped'::bytea); PostgreSQL 7.2.2 i nowszy nie potrzebuje wskazania typu. Wyjątkiem jest przypadek kiedy klient i serwer posługują się różnymi stronami kodowymi. W takim przypadku może wystąpić błąd (ang. multi-byte stream error). Użytkownik musi wtedy wskazać typ bytea, by uniknąć tego błędu.
Parametry
-
połączenie -
Identyfikator połączenia do bazy danych PostgreSQL. Kiedy
połączenienie został podany, domyślne połączenie zostaje użyte. Domyślnym połączeniem jest ostatnie połączenie stworzone przez pg_connect() lub pg_pconnect(). -
dane -
Łańcuch (ang. string) zawierający tekst lub binarne dane wstawiane do kolumny bytea.
Zwracane wartości
Łańcuch (ang. string) zawierający dane z sekwencjami Escape..
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.2.0 | Parametr połączenie został dodany |
Przykłady
Przykład #1 pg_escape_bytea() - przykład
<?php
// Połącz z bazą
$połączenie = pg_connect('dbname=foo');
// Przeczytaj z binarnego pliku
$dane = file_get_contents('obrazek1.jpg');
// Poprzedź sekwencjami Escape dane binarne
$escaped = pg_escape_bytea($dane);
// Wpisz to do bazy danych
pg_query("INSERT INTO galeria (nazwa, dane) VALUES ('Drzewa sosnowe', '{$escaped}')");
?>
Zobacz też:
- pg_unescape_bytea() - Unescape binary for bytea type
- pg_escape_string() - Konwertuje łańcuch wpisywany do pola tekstowego, wstawiając sekwencje Escape
pg_escape_identifier
(No version information available, might only be in SVN)
pg_escape_identifier — Escape a identifier for insertion into a text field
Opis
$connection
], string $data
)pg_escape_identifier() escapes a identifier (e.g. table, field names) for quering the database. It returns an escaped identifier string for PostgreSQL server. pg_escape_identifier() adds double quotes before and after data. Users should not add double quotes. Use of this function is recommended for identifier parameters in query. For SQL literals (i.e. parameters except bytea), pg_escape_literal() or pg_escape_string() muse be used. For bytea type fields, pg_escape_bytea() must be used instead.
Informacja:
This function has internal escape code and can also be used with PostgreSQL 8.4 or less.
Parametry
-
connection -
PostgreSQL database connection resource. When
connectionis not present, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect(). -
data -
A string containing text to be escaped.
Zwracane wartości
A string containing the escaped data.
Przykłady
Przykład #1 pg_escape_identifier() example
<?php
// Connect to the database
$dbconn = pg_connect('dbname=foo');
// Escape the table name data
$escaped = pg_escape_identifier($table_name);
// Select rows from $table_name
pg_query("SELECT * FROM {$escaped};");
?>
Zobacz też:
- pg_escape_literal() - Escape a literal for insertion into a text field
- pg_escape_bytea() - Konwertuje łańcuch wstawiając sekwencje Escape dla typu bytea
- pg_escape_string() - Konwertuje łańcuch wpisywany do pola tekstowego, wstawiając sekwencje Escape
pg_escape_literal
(No version information available, might only be in SVN)
pg_escape_literal — Escape a literal for insertion into a text field
Opis
$connection
], string $data
)pg_escape_literal() escapes a literal for querying the PostgreSQL database. It returns an escaped literal in the PostgreSQL format. pg_escape_literal() adds quotes before and after data. Users should not add quotes. Use of this function is recommended instead of pg_escape_string(). If the type of the column is bytea, pg_escape_bytea() must be used instead. For escaping identifiers (e.g. table, field names), pg_escape_identifier() must be used.
Informacja:
This function has internal escape code and can also be used with PostgreSQL 8.4 or less.
Parametry
-
connection -
PostgreSQL database connection resource. When
connectionis not present, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect(). -
data -
A string containing text to be escaped.
Zwracane wartości
A string containing the escaped data.
Przykłady
Przykład #1 pg_escape_literal() example
<?php
// Connect to the database
$dbconn = pg_connect('dbname=foo');
// Read in a text file (containing apostrophes and backslashes)
$data = file_get_contents('letter.txt');
// Escape the text data
$escaped = pg_escape_literal($data);
// Insert it into the database. Note that no quotes around {$escaped}
pg_query("INSERT INTO correspondence (name, data) VALUES ('My letter', {$escaped})");
?>
Zobacz też:
- pg_escape_identifier() - Escape a identifier for insertion into a text field
- pg_escape_bytea() - Konwertuje łańcuch wstawiając sekwencje Escape dla typu bytea
- pg_escape_string() - Konwertuje łańcuch wpisywany do pola tekstowego, wstawiając sekwencje Escape
pg_escape_string
(PHP 4 >= 4.2.0, PHP 5)
pg_escape_string — Konwertuje łańcuch wpisywany do pola tekstowego, wstawiając sekwencje Escape
Opis
$polaczenie
], string $dane
)pg_escape_string() konwertuje łańcuch wstawiając sekwencje Escape przy wpisywaniu do bazy danych. Zwraca łańcuch z sekwencjami Escape w formacie PostgreSQL-a. Zalecane jest używanie tej funkcji w miejsce addslashes(). Jeśli typem kolumny jest bytea, trzeba użyć funkcji pg_escape_bytea() zamiast tej.
Informacja:
Funkcja wymaga PostgreSQL 7.2 lub nowszego.
Parametry
-
polaczenie -
Identyfikator połączenia do bazy danych. Gdy
polaczenienie zostało podane, domyślne połączenie jest użyte. Domyślnym połączeniem jest ostatnie połączenie stworzone przez pg_connect() lub pg_pconnect(). -
dane -
Łańcuch (ang. string) zawierający tekst bez sekwencji Escape.
Zwracane wartości
Łańcuch (ang. string) zawierający dane z sekwencjami Escape.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.2.0 | Parametr polaczenie został dodany |
Przykłady
Przykład #1 pg_escape_string() - przykład
<?php
// Połączenie do bazy danych
$polaczenie = pg_connect('dbname=foo');
// Przeczytaj plik tekstowy (zawierający apostrofy i ukośniki wsteczne)
$dane = file_get_contents('list.txt');
// Dodaj sekwencje Escape do danych
$z_escape = pg_escape_string($dane);
// Wpisz to do bazy danych
pg_query("INSERT INTO korespondencja (nazwa, dane) VALUES ('Moj list', '{$z_escape}')");
?>
pg_execute
(PHP 5 >= 5.1.0)
pg_execute — Sends a request to execute a prepared statement with given parameters, and waits for the result.
Opis
$connection
], string $stmtname
, array $params
)Sends a request to execute a prepared statement with given parameters, and waits for the result.
pg_execute() is like pg_query_params(), but the command to be executed is specified by naming a previously-prepared statement, instead of giving a query string. This feature allows commands that will be used repeatedly to be parsed and planned just once, rather than each time they are executed. The statement must have been prepared previously in the current session. pg_execute() is supported only against PostgreSQL 7.4 or higher connections; it will fail when using earlier versions.
The parameters are identical to pg_query_params(), except that the name of a prepared statement is given instead of a query string.
Parametry
-
connection -
PostgreSQL database connection resource. When
connectionis not present, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect(). -
stmtname -
The name of the prepared statement to execute. if "" is specified, then the unnamed statement is executed. The name must have been previously prepared using pg_prepare(), pg_send_prepare() or a PREPARE SQL command.
-
params -
An array of parameter values to substitute for the $1, $2, etc. placeholders in the original prepared query string. The number of elements in the array must match the number of placeholders.
OstrzeżenieElements are converted to strings by calling this function.
Zwracane wartości
A query result resource on success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 Using pg_execute()
<?php
// Connect to a database named "mary"
$dbconn = pg_connect("dbname=mary");
// Prepare a query for execution
$result = pg_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name = $1');
// Execute the prepared query. Note that it is not necessary to escape
// the string "Joe's Widgets" in any way
$result = pg_execute($dbconn, "my_query", array("Joe's Widgets"));
// Execute the same prepared query, this time with a different parameter
$result = pg_execute($dbconn, "my_query", array("Clothes Clothes Clothes"));
?>
Zobacz też:
- pg_prepare() - Submits a request to create a prepared statement with the given parameters, and waits for completion.
- pg_send_prepare() - Sends a request to create a prepared statement with the given parameters, without waiting for completion.
- pg_query_params() - Submits a command to the server and waits for the result, with the ability to pass parameters separately from the SQL command text.
pg_fetch_all_columns
(PHP 5 >= 5.1.0)
pg_fetch_all_columns — Fetches all rows in a particular result column as an array
Opis
$result
[, int $column = 0
] )pg_fetch_all_columns() returns an array that contains all rows (records) in a particular column of the result resource.
Informacja: Ta funkcja ustala wartość pól NULL na
NULL.
Parametry
-
result -
PostgreSQL query result resource, returned by pg_query(), pg_query_params() or pg_execute() (among others).
-
column -
Column number, zero-based, to be retrieved from the result resource. Defaults to the first column if not specified.
Zwracane wartości
An array with all values in the result column.
FALSE is returned if column is larger than the number
of columns in the result, or on any other error.
Przykłady
Przykład #1 pg_fetch_all_columns() example
<?php
$conn = pg_pconnect("dbname=publisher");
if (!$conn) {
echo "An error occured.\n";
exit;
}
$result = pg_query($conn, "SELECT title, name, address FROM authors");
if (!$result) {
echo "An error occured.\n";
exit;
}
// Get an array of all author names
$arr = pg_fetch_all_columns($result, 1);
var_dump($arr);
?>
pg_fetch_all
(PHP 4 >= 4.3.0, PHP 5)
pg_fetch_all — Fetches all rows from a result as an array
Opis
$result
)pg_fetch_all() returns an array that contains all rows (records) in the result resource.
Informacja: Ta funkcja ustala wartość pól NULL na
NULL.
Parametry
-
result -
PostgreSQL query result resource, returned by pg_query(), pg_query_params() or pg_execute() (among others).
Zwracane wartości
An array with all rows in the result. Each row is an array of field values indexed by field name.
FALSE is returned if there are no rows in the result, or on any
other error.
Przykłady
Przykład #1 PostgreSQL fetch all
<?php
$conn = pg_pconnect("dbname=publisher");
if (!$conn) {
echo "An error occured.\n";
exit;
}
$result = pg_query($conn, "SELECT * FROM authors");
if (!$result) {
echo "An error occured.\n";
exit;
}
$arr = pg_fetch_all($result);
print_r($arr);
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[0] => Array
(
[id] => 1
[name] => Fred
)
[1] => Array
(
[id] => 2
[name] => Bob
)
)
Zobacz też:
- pg_fetch_row() - Pobiera wiersz jako tablicę z indeksami numerycznymi
- pg_fetch_array() - Pobiera wiersz jako tablicę
- pg_fetch_object() - Pobiera wiersz jako obiekt
- pg_fetch_result() - Pobiera dane z wyniku
pg_fetch_array
(PHP 4, PHP 5)
pg_fetch_array — Pobiera wiersz jako tablicę
Opis
$wynik
[, int $wiersz
[, int $typ_wyniku = PGSQL_BOTH
]] )pg_fetch_array() zwraca tablicę zawierającą dane z pobranego wiersza (rekordu).
pg_fetch_array() jest rozszerzeną wersją pg_fetch_row(). Oprócz zapisywania danych w tablicy wyników indeksowanej numerycznie, zapisuje je też używając indeksów przyporządkowujących (asocjacyjnych) tej tablicy, nazwy kolumn traktując jako klucze. Domyślnie zapisywane są oba rodzaje indeksów.
Informacja: Ta funkcja ustala wartość pól NULL na
NULL.
pg_fetch_array() NIE jest znacznie wolniejsze, niż używanie pg_fetch_row(), oraz jest zdecydowanie łatwiejsze do użycia.
Parametry
-
wynik -
Identyfikator wyniku zapytania PostgreSQL, zwrócony przez pg_query(), pg_query_params() lub pg_execute() (między innymi).
-
wiersz -
Numer wiersza w wyniku do pobrania. Wiersze są numerowane od zera w górę. Jeśli jest pominięty albo wynosi
NULL, pobrany zostanie kolejny wiersz. -
typ_wyniku -
Opcjonalny parametr kontrolujący w jaki sposób zwrócona tablica (ang. array) jest indeksowana.
typ_wynikujest stałą i może przyjąć następujące wartości:PGSQL_ASSOC,PGSQL_NUMorazPGSQL_BOTH. UżywającPGSQL_NUM, pg_fetch_array() zwróci tablicę z indeksami numerycznymi, użyciePGSQL_ASSOCzwróci wyłącznie indeksy asocjacyjne podczas, gdyPGSQL_BOTH, wartość domyślna, zwróci oba rodzaje indeksów - numeryczne i asocjacyjne.
Zwracane wartości
Tablica (ang. array) indeksowana numerycznie (zaczynając od zera) lub
asocjacyjnie (indeksowana przez nazwy kolumn), lub tak i tak.
Każda wartość w tablicy (ang. array) jest przedstawiona jako łańcuch
(ang. string). Wartości NULL z bazy danych
są zwracane jako NULL.
FALSE zostanie zwrócone jeśli wiersz przekracza ilość
wierszy w całym zbiorze, nie ma więcej wierszy, lub dowolnym innym błędzie.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.1.0 |
Parametr wiersz stał się opcjonalnym.
|
Przykłady
Przykład #1 pg_fetch_array() - przykład
<?php
$polaczenie_z_baza = pg_pconnect("dbname=wydawca");
if (!$polaczenie_z_baza) {
echo "Wystąpił błąd.\n";
exit;
}
$wynik = pg_query($polaczenie_z_baza, "SELECT autor, email FROM autorzy");
if (!$wynik) {
echo "Wystąpił błąd.\n";
exit;
}
$tab = pg_fetch_array($wynik, 0, PGSQL_NUM);
echo $tab[0] . " <- Wiersz 1 Autor\n";
echo $tab[1] . " <- Wiersz 1 E-mail\n";
// Jako, że w PHP 4.1.0, parametr wiersz jest opcjonalny; można podać w zamian NULL,
// by podać typ_wyniku. Kolejne wywołanie funkcji pg_fetch_array zwróci
// następny wiersz.
$tab = pg_fetch_array ($wynik, 1, PGSQL_ASSOC);
echo $tab["autor"] . " <- Wiersz 2 Autor\n";
echo $tab["email"] . " <- Wiersz 2 E-mail\n";
$tab = pg_fetch_array($wynik);
echo $tab["autor"] . " <- Wiersz 3 Autor\n";
echo $tab[1] . " <- Wiersz 3 E-mail\n";
?>
Zobacz też:
- pg_fetch_row() - Pobiera wiersz jako tablicę z indeksami numerycznymi
- pg_fetch_object() - Pobiera wiersz jako obiekt
- pg_fetch_result() - Pobiera dane z wyniku
pg_fetch_assoc
(PHP 4 >= 4.3.0, PHP 5)
pg_fetch_assoc — Fetch a row as an associative array
Opis
$result
[, int $row
] )pg_fetch_assoc() returns an associative array that corresponds to the fetched row (records).
pg_fetch_assoc() is equivalent to calling
pg_fetch_array() with PGSQL_ASSOC as the
optional third parameter. It only returns an associative array.
If you need the numeric indices, use
pg_fetch_row().
Informacja: Ta funkcja ustala wartość pól NULL na
NULL.
pg_fetch_assoc() is NOT significantly slower than using pg_fetch_row(), and is significantly easier to use.
Parametry
-
result -
PostgreSQL query result resource, returned by pg_query(), pg_query_params() or pg_execute() (among others).
-
row -
Row number in result to fetch. Rows are numbered from 0 upwards. If omitted or
NULL, the next row is fetched.
Zwracane wartości
An array indexed associatively (by field name).
Each value in the array is represented as a
string. Database NULL
values are returned as NULL.
FALSE is returned if row exceeds the number
of rows in the set, there are no more rows, or on any other error.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.1.0 |
The parameter row became optional.
|
Przykłady
Przykład #1 pg_fetch_assoc() example
<?php
$conn = pg_connect("dbname=publisher");
if (!$conn) {
echo "An error occured.\n";
exit;
}
$result = pg_query($conn, "SELECT id, author, email FROM authors");
if (!$result) {
echo "An error occured.\n";
exit;
}
while ($row = pg_fetch_assoc($result)) {
echo $row['id'];
echo $row['author'];
echo $row['email'];
}
?>
Zobacz też:
- pg_fetch_row() - Pobiera wiersz jako tablicę z indeksami numerycznymi
- pg_fetch_array() - Pobiera wiersz jako tablicę
- pg_fetch_object() - Pobiera wiersz jako obiekt
- pg_fetch_result() - Pobiera dane z wyniku
pg_fetch_object
(PHP 4, PHP 5)
pg_fetch_object — Pobiera wiersz jako obiekt
Opis
$wynik
[, int $wiersz
[, int $typ_wyniku = PGSQL_ASSOC
]] )$wynik
[, int $wiersz
[, string $nazwa_klasy
[, array $parametry
]]] )pg_fetch_object() zwraca obiekt którego atrybutami są nazwy pól pobranego wiersza. Może dodatkowo tworzyć pewien obiekt określonej klasy, oraz wstawić parametry do konstruktora tej klasy.
Informacja: Ta funkcja ustala wartość pól NULL na
NULL.
Pod względem szybkości funkcja ta jest identyczna jak pg_fetch_array(), i prawie tak szybka jak pg_fetch_row() (różnica jest znikoma).
Parametry
-
wynik -
Identyfikator wyniku zapytania PostgreSQL, zwrócony przez pg_query(), pg_query_params() lub pg_execute() (między innymi).
-
wiersz -
Numer wiersza w wyniku do pobrania. Wiersze są numerowane od zera w górę. Jeśli jest pominięty albo wynosi
NULL, pobrany zostanie kolejny wiersz. -
typ_wyniku -
Pomijany i przestarzały.
-
nazwa_klasy -
Nazwa klasy do wytworzenia, określenie zwracanych parametrów. Jeśli nie podano, zwrócony zostanie obiekt stdClass.
-
parametry -
Opcjonalna tablica (ang. array) parametrów podawanych do konstruktora obiektów klasy
nazwa_klasy.
Zwracane wartości
Obiekt (ang. object) z atrybutem dla każdej nazwy
kolumny w wyniku. Wartości NULL z bazy danych
są zwracane jako NULL.
FALSE jest zwracne, gdy parametr wiersz przekracza całkowitą
liczbę wierszy, gdy kolejny wiersz nie istnieje, lub w przypadku każdego innego błędu.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.0.0 |
Parametry nazwa_klasy oraz parametry
zostały dodane. Stara wersja z typ_wyniku
wciąż istnieje, w celu zachowania wstecznej kompatybilności.
|
| 4.3.0 |
Domyślną wartość parametru typ_wyniku zmieniono z
PGSQL_BOTH na PGSQL_ASSOC,
gdyż indeks numeryczny był niepoprawny.
|
| 4.1.0 |
Parametr wiersz stał się opcjonalnym.
|
Przykłady
Przykład #1 pg_fetch_object() - przykład
<?php
$baza = "magazyn";
$polaczenie = pg_connect("host=localhost port=5432 dbname=$baza");
if (!$polaczenie) {
echo "Błąd połączenia do bazy PostgreSQL $baza\n";
exit;
}
$zap = pg_query($polaczenie, "SELECT * FROM ksiazki ORDER BY autor");
while ($dane = pg_fetch_object($zap)) {
echo $dane->autor . " (";
echo $dane->rok . "): ";
echo $dane->tytul . "<br />";
}
pg_free_result($zap);
pg_close($polaczenie);
?>
Zobacz też:
- pg_query() - Realizujezapytanie do bazy danych
- pg_fetch_array() - Pobiera wiersz jako tablicę
- pg_fetch_assoc() - Fetch a row as an associative array
- pg_fetch_row() - Pobiera wiersz jako tablicę z indeksami numerycznymi
- pg_fetch_result() - Pobiera dane z wyniku
pg_fetch_result
(PHP 4 >= 4.2.0, PHP 5)
pg_fetch_result — Pobiera dane z wyniku
Opis
pg_fetch_result() zwraca wartość określonego wiersza i pola (kolumny) w identyfikatorze wyniku PostgreSQL.
Informacja:
Funkcja ta nazywana była wcześniej pg_result().
Parametry
-
wynik -
Identyfikator wyniku zapytania, zwrócony przez pg_query(), pg_query_params() lub pg_execute() (między innymi).
-
wiersz -
Numer wiersza wyniku do zwrócenia. Wiersze są numerowane od zera w górę. Jeśli nie podano, zwracany jest kolejny wiersz.
-
kolumna -
Łańcuch (ang. string) reprezentujący nazwę pola (kolumny) do pobrania, w innym wypadku, kolumnę do pobrania reprezentuje jej numer (int). Pola są numerowane od zera w górę.
Zwracane wartości
Typ boolean jest zwracany jako "t" lub "f" (true lub false z j. ang.). Wszystkie
inne typy, włączając tablice są zwracane jako łańcuchy sformatowane
domyślnie, do takiego samego typu PostgreSQL, jaki powinieneś zobaczyć w programie
psql. Wartości NULL z bazy danych
są zwracane jako NULL.
FALSE jest zwracane jeśli wiersz przekracza liczbę
wszystkich dostępnych wierszy, lub w przypadku każdego innego błędu.
Przykłady
Przykład #1 pg_fetch_result() - przykład
<?php
$baza_danych = pg_connect("dbname=uzytkownicy uzytkownik=ja") || die();
$id = pg_query($baza_danych, "SELECT 1 UNION ALL SELECT 2");
$war = pg_fetch_result($id, 1, 0);
echo "Pierwsze pole w drugim wierszu to: ", $war, "\n";
?>
Powyższy przykład wyświetli:
Pierwsze pole w drugim wierszu to: 2
Zobacz też:
- pg_query() - Realizujezapytanie do bazy danych
- pg_fetch_array() - Pobiera wiersz jako tablicę
pg_fetch_row
(PHP 4, PHP 5)
pg_fetch_row — Pobiera wiersz jako tablicę z indeksami numerycznymi
Opis
$wynik
, int $wiersz
)
pg_fetch_row() pobiera jeden wiersz
z wyniku wskazanego przez określony identyfikator wyniku
wynik.
Informacja: Ta funkcja ustala wartość pól NULL na
NULL.
Parametry
-
wynik -
Identyfikator wyniku zapytania bazy PostgreSQL, zwrócony przez jedną z funkcji pg_query(), pg_query_params() lub pg_execute() (między innymi).
-
wiersz -
Numer wiersza w wyniku do pobrania. Wiersze numerowane są od zera w górę. Jeśli jest pominięty albo wynosi
NULL, pobrany zostanie kolejny wiersz.
Zwracane wartości
Tablica (ang. array), indeksowana od zera w górę, z reprezentowaną
każdą wartością jako łańcuch (ang. string). Wartości NULL z bazy danych
są zwracane jako NULL.
FALSE jest zwracane, jeśli wiersz przekracza liczbę
wszystkich wierszy, nie ma więcej wierszy, lub w przypadku każdego innego błędu.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.1.0 |
Parametr wiersz stał się opcjonalny.
|
Przykłady
Przykład #1 pg_fetch_row() - przykład
<?php
$polaczenie = pg_pconnect("dbname=wydawca");
if (!$polaczenie) {
echo "Wystąpił błąd.\n";
exit;
}
$wynik = pg_query($polaczenie, "SELECT autor, email FROM autorzy");
if (!$wynik) {
echo "Wystąpił błąd.\n";
exit;
}
while ($wiersz = pg_fetch_row($wynik)) {
echo "Autor: $wiersz[0] E-mail: $wiersz[1]";
echo "<br />\n";
}
?>
Zobacz też:
- pg_query() - Realizujezapytanie do bazy danych
- pg_fetch_array() - Pobiera wiersz jako tablicę
- pg_fetch_object() - Pobiera wiersz jako obiekt
- pg_fetch_result() - Pobiera dane z wyniku
pg_field_is_null
(PHP 4 >= 4.2.0, PHP 5)
pg_field_is_null — Sprawdza czy pole SQL zawiera NULL
Opis
pg_field_is_null() sprawdza, czy pole identyfikatora wyniku PostgreSQL jest wartością NULL SQL-a czy nie.
Informacja:
Ta funkcja była poprzednio nazwana pg_fieldisnull().
Parametry
-
wynik -
Identyfikator wyniku PostgreSQL-q, zwrócony przez pg_query(), pg_query_params() lub pg_execute() (między innymi).
-
wiersz -
Numer wiersza w wyniku do pobrania. Wiersze są numerowane od zera, w górę. Jeśli nie podano, aktualny wiersz jest pobierany.
-
pole -
Numer pola (zaczynając od zera) jako typ całkowity (ang. integer) lub nazwa pola jako łańcuch (ang. string).
Zwracane wartości
Zwraca 1 jeśli pole w zadanym wierszu w bazie SQL jest wartością NULL, 0
jeśli nią nie jest. FALSE jest zwracane, gdy podany wiersz jest poza przedziałem, lub przez każdy inny błąd.
Przykłady
Przykład #1 pg_field_is_null() - przykład
<?php
$polaczenie = pg_connect("dbname=wydawca") or die ("Nie można się połączyć");
$wyn = pg_query($polaczenie, "select * from autorzy where autor = 'Orwell'"
if ($wyn) {
if (pg_field_is_null($wyn, 0, "rok") == 1) {
echo "Wartość pola roku jest null.\n";
}
if (pg_field_is_null($wyn, 0, "rok") == 0) {
echo "Wartość pola roku nie jest null.\n";
}
}
?>
pg_field_name
(PHP 4 >= 4.2.0, PHP 5)
pg_field_name — Zwraca nazwę kolumny
Opis
$wynik
, int $numer_pola
)
pg_field_name() zwraca nazwę kolumny znajdującej
się na pozycji numer_pola w identyfikatorze wyniku
wynik PostgreSQL-a. Kolumny są
numerowane od zera.
Informacja:
Ta funkcja była poprzednio nazwana pg_fieldname().
Parametry
-
wynik -
Identyfikator wyniku zapytania PostgreSQL-a, zwrócony przez pg_query(), pg_query_params() lub pg_execute() (między innymi).
-
numer_pola -
Numer kolumny, rozpoczynając od zera.
Zwracane wartości
Nazwa kolumny, lub FALSE w razie błędu.
Przykłady
Przykład #1 Pobieranie informacji o kolumnach
<?php
$polaczenie = pg_connect("dbname=wydawca") or die("Nie można się połączyć");
$wyn = pg_query($polaczenie, "select * from autorzy where autor = 'Orwell'");
$i = pg_num_fields($wyn);
for ($j = 0; $j < $i; $j++) {
echo "kolumna $j\n";
$nazwa_pola = pg_field_name($wyn, $j);
echo "nazwa pola: $nazwa_pola\n";
echo "drukowalna długość: " . pg_field_prtlen($wyn, $nazwa_pola) . " znak(ów)\n";
echo "rzeczywista długość: " . pg_field_size($wyn, $j) . " bajt(ów)\n";
echo "typ pola: " . pg_field_type($wyn, $j) . " \n\n";
}
?>
Powyższy przykład wyświetli:
kolumna 0 nazwa pola: autor drukowalna długość: 6 znak(ów) rzeczywista długość: -1 bajt(ów) typ pola: varchar kolumna 1 nazwa pola: rok drukowalna długość: 4 znak(ów) rzeczywista długość: 2 bajt(ów) typ pola: int2 kolumna 2 nazwa pola: tytul drukowalna długość: 24 znak(ów) rzeczywista długość: -1 bajt(ów) typ pola: varchar
pg_field_num
(PHP 4 >= 4.2.0, PHP 5)
pg_field_num — Zwraza numer kolumny o podanej nazwie
Opis
$wynik
, string $nazwa_pola
)
pg_field_num() zwraca indeks
numeru pola o podanej nazwie
nazwa_pola w podanym identyfikatorze wyniku
wynik.
Informacja:
Ta funkcja była poprzednio nazwana pg_fieldnum().
Parametry
-
wynik -
Identyfikator wyniku zapytania PostgreSQL-a, zwrócony przez pg_query(), pg_query_params() lub pg_execute() (między innymi).
-
nazwa_pola -
Nazwa kolumny.
Zwracane wartości
Numer pola (numerowanie od zera), lub -1 w razie błędu.
Przykłady
Przykład #1 Pobieranie informacji o polach
<?php
$polaczenie = pg_connect("dbname=wydawca") or die("Nie można się połączyć");
$wyn = pg_query($polaczenie, "select autor, rok, tytul from autorzy where autor = 'Orwell'");
echo "Kolumna 'tytul' to pole numer: ", pg_field_num($wyn, 'tytul');
?>
Powyższy przykład wyświetli:
Kolumna 'tytul' to pole numer: 2
pg_field_prtlen
(PHP 4 >= 4.2.0, PHP 5)
pg_field_prtlen — Zwraca drukowalną długość
Opis
$wynik
, int $numer_wiersza
, string $nazwa_pola_lub_numer
)
pg_field_prtlen() zwraca aktualną drukowalną
długość (liczbę znaków) wskazanej danej wyniku parametru
wynik PostgreSQL-a. Wiersze są numerowane od zera. Funkcja
zwraca -1 w razie błędu.
Parametr nazwa_pola_lub_numer przyjmie wartości zarówno liczbowe
(integer), jak również łańcuchowe (ang. string). Jeśli podano liczbę całkowitą
(integer), PHP rozpozna to jako numer pola, w przeciwnym wypadku jako
nazwę pola.
Proszę spojrzeć na przykład zawarty na stronie opisującej funkcję pg_field_name().
Informacja:
Ta funkcja była poprzednio nazwana pg_fieldprtlen().
Parametry
-
wynik -
Identyfikator wyniku zapytania do PostgreSQL, zwrócony przez pg_guery(), pg_query_params() lub pg_execute() (między innymi).
-
wiersz -
Numer wiersza w wyniku. Wiersze są numerowane od zera w górę. Jeśli pominięto, pobierany jest aktualny wiersz.
Zwracane wartości
Długość drukowailna pola, lub FALSE w przypadku błędu.
Przykłady
Przykład #1 Pobieranie informacji na temat pól
<?php
$polaczenie_z_baza = pg_connect("dbname=wydawca") or die("Nie można się połączyć.");
$wyn = pg_query($polaczenie_z_baza, "select * from autorzy where autor = 'Orwell'");
$i = pg_num_fields($wyn);
for ($j = 0; $j < $i; $j++) {
echo "kolumna $j\n";
$nazwa_pola = pg_field_name($wyn, $j);
echo "nazwa pola: $nazwa_pola\n";
echo "długość drukowalna: " . pg_field_prtlen($wyn, $nazwa_pola) . " znaki(ów)\n";
echo "realna długość: " . pg_field_size($wyn, $j) . " bajty(ów)\n";
echo "typ pola: " . pg_field_type($wyn, $j) . " \n\n";
}
?>
Powyższy przykład wyświetli:
kolumna 0 nazwa pola: autor długość drukowalna: 6 znaki(ów) realna długość: -1 bajt(ów) typ pola: varchar kolumna 1 nazwa pola: rok długość drukowalna: 4 znaki(ów) realna długość: 2 bajt(ów) typ pola: int2 kolumna 2 nazwa pola: tytuł długość drukowalna: 24 znaki(ów) realna długość: -1 bajt(ów) typ pola: varchar
pg_field_size
(PHP 4 >= 4.2.0, PHP 5)
pg_field_size — Zwraca wewnętrzny rozmiar kolumny
Opis
$wynik
, int $numer_pola
)
pg_field_size() zwraca wewnętrzny rozmiar
(w bajtach) wskazanej numerem kolumny w podanym wyniku
wynik PostgreSQL-a.
Informacja:
Ta funkcja była poprzednio nazwana pg_fieldsize().
Parametry
-
wynik -
Identyfikator wyniku zapytania PostgreSQL, zwrócony przez pg_query(), pg_query_params() lub pg_execute() (między innymi).
-
numer_pola -
Numer pola, zaczynając od zera.
Zwracane wartości
Wewnętrzny rozmiar danego pola (w bajtach). -1 oznacza niestałą
wielkość pola. FALSE zwracane jest w przypadku błędu.
Przykłady
Przykład #1 Pobieranie informacji o polach
<?php
$polaczenie = pg_connect("dbname=wydawca") or die("Nie można się połączyć");
$wyn = pg_query($polaczenie, "select * from autorzy where autor = 'Orwell'");
$i = pg_num_fields($wyn);
for ($j = 0; $j < $i; $j++) {
echo "kolumna $j\n";
$nazwa_pola = pg_field_name($wyn, $j);
echo "nazwa pola: $nazwa_pola\n";
echo "drukowalna długość: " . pg_field_prtlen($wyn, $nazwa_pola) . " znak(ów)\n";
echo "rzeczywista długość: " . pg_field_size($wyn, $j) . " bajt(ów)\n";
echo "typ pola: " . pg_field_type($wyn, $j) . " \n\n";
}
?>
Powyższy przykład wyświetli:
kolumna 0 nazwa pola: autor drukowalna długość: 6 znak(ów) rzeczywista długość: -1 bajt(ów) typ pola: varchar kolumna 1 nazwa pola: rok drukowalna długość: 4 znak(ów) rzeczywista długość: 2 bajt(ów) typ pola: int2 kolumna 2 nazwa pola: tytul drukowalna długość: 24 znak(ów) rzeczywista długość: -1 bajt(ów) typ pola: varchar
Zobacz też:
- pg_field_prtlen() - Zwraca drukowalną długość
- pg_field_type() - Zwraca typ wskazanej kolumny
pg_field_table
(PHP 5 >= 5.2.0)
pg_field_table — Returns the name or oid of the tables field
Opis
pg_field_table() returns the name of the table that field
belongs to, or the table's oid if oid_only is TRUE.
Parametry
-
result -
PostgreSQL query result resource, returned by pg_query(), pg_query_params() or pg_execute() (among others).
-
field_number -
Field number, starting from 0.
-
oid_only -
By default the tables name that field belongs to is returned but if
oid_onlyis set toTRUE, then the oid will instead be returned.
Zwracane wartości
On success either the fields table name or oid. Or, FALSE on failure.
Przykłady
Przykład #1 Getting table information about a field
<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");
$res = pg_query($dbconn, "SELECT bar FROM foo");
echo pg_field_table($res, 0);
echo pg_field_table($res, 0, true);
$res = pg_query($dbconn, "SELECT version()");
var_dump(pg_field_table($res, 0));
?>
Powyższy przykład wyświetli coś podobnego do:
foo 14379580 bool(false)
Notatki
Informacja:
Returning the oid is much faster than returning the table name because fetching the table name requires a query to the database system table.
pg_field_type_oid
(PHP 5 >= 5.1.0)
pg_field_type_oid — Returns the type ID (OID) for the corresponding field number
Opis
$result
, int $field_number
)
pg_field_type_oid() returns an integer containing the
OID of the base type of the given field_number in the
given PostgreSQL result resource.
You can get more information about the field type by querying PostgreSQL's pg_type system table using the OID obtained with this function. The PostgreSQL format_type() function will convert a type OID into an SQL standard type name.
Informacja:
If the field uses a PostgreSQL domain (rather than a basic type), it is the OID of the domain's underlying type that is returned, rather than the OID of the domain itself.
Parametry
-
result -
PostgreSQL query result resource, returned by pg_query(), pg_query_params() or pg_execute() (among others).
-
field_number -
Field number, starting from 0.
Zwracane wartości
The OID of the field's base type. FALSE is returned on error.
Przykłady
Przykład #1 Getting information about fields
<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");
// Assume 'title' is a varchar type
$res = pg_query($dbconn, "select title from authors where author = 'Orwell'");
echo "Title field type OID: ", pg_field_type_oid($res, 0);
?>
Powyższy przykład wyświetli:
Title field type OID: 1043
Zobacz też:
- pg_field_type() - Zwraca typ wskazanej kolumny
- pg_field_prtlen() - Zwraca drukowalną długość
- pg_field_name() - Zwraca nazwę kolumny
pg_field_type
(PHP 4 >= 4.2.0, PHP 5)
pg_field_type — Zwraca typ wskazanej kolumny
Opis
$wynik
, int $numer_kolumny
)
pg_field_type() zwraca łańcuch zawierający typ
podstawowy kolumny wskazanej przez numer_kolumny w wyniku
wynik PostgreSQL-a.
Informacja:
Jeśli kolumna używa domeny PostgreSQL (zamiast typu podstawowego), jest to nazwa podstawowego typu domeny, który jest zwrócony, zamiast nazwy samej domeny.
Informacja:
Ta funkcja dawniej nazywała się pg_fieldtype().
Parametry
-
wynik -
Identyfikator wyniku zapytania do bazy PostgreSQL, zwrócony przez funkcję pg_query(), pg_query_params() lub pg_execute() (między innymi).
-
numer_pola -
Numer pola, zaczynając od zera.
Zwracane wartości
Łańcuch (ang. string) zawierający podstawową nazwę typu pola, lub FALSE
w przypadku błędu.
Przykłady
Przykład #1 Pobieranie informacji o kolumnach
<?php
$polaczenie_do_bazy = pg_connect("dbname=publisher") or die("Nie można się połączyć");
// Załóżmy, że 'tytul' jest typu varchar
$res = pg_query($polaczenie_do_bazy, "select tytul from autorzy where autor = 'Orwell'");
echo "Typ pola tytułu: ", pg_field_type($res, 0);
?>
Powyższy przykład wyświetli:
Typ pola tytułu: varchar
Zobacz też:
- pg_field_prtlen() - Zwraca drukowalną długość
- pg_field_name() - Zwraca nazwę kolumny
- pg_field_type_oid() - Returns the type ID (OID) for the corresponding field number
pg_free_result
(PHP 4 >= 4.2.0, PHP 5)
pg_free_result — Zwalnia pamięć wyniku
Opis
$wynik
)pg_free_result() zwalnia pamięć i danych związanych z określonym identyfikatorem wyniku PostgreSQL (ang. typ resource).
Tę funkcję trzeba wywołać jeśli zużywanie pamięci podczas wykonywania skryptu stanowi problem. W przeciwnym wypadku, cała pamięć przeznaczona dla wyniku zostanie automatycznie zwolniona, gdy skrypt zakończy się.
Informacja:
Ta funkcja była poprzednio nazwana pg_freeresult().
Parametry
-
wynik -
Identyfikator wyniku PostgreSQL, zwrócony przez pg_query(), pg_query_params() lub pg_execute() (między innymi).
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 pg_free_result() - przykład
<?php
$baza_danych = pg_connect("dbname=uzytkownicy uzytkownik=ja") || die();
$wyn = pg_query($baza_danych, "SELECT 1 UNION ALL SELECT 2");
$wartosc = pg_fetch_result($wyn, 1, 0);
echo "Pierwsze pole w drugim wierszu to: ", $wartosc, "\n";
pg_free_result($wyn);
?>
Powyższy przykład wyświetli:
Pierwsze pole w drugim wierszu to: 2
Zobacz też:
- pg_query() - Realizujezapytanie do bazy danych
- pg_query_params() - Submits a command to the server and waits for the result, with the ability to pass parameters separately from the SQL command text.
- pg_execute() - Sends a request to execute a prepared statement with given parameters, and waits for the result.
pg_get_notify
(PHP 4 >= 4.3.0, PHP 5)
pg_get_notify — Gets SQL NOTIFY message
Opis
$connection
[, int $result_type
] )pg_get_notify() gets notifications generated by a NOTIFY SQL command. To receive notifications, the LISTEN SQL command must be issued.
Parametry
-
connection -
PostgreSQL database connection resource.
-
result_type -
An optional parameter that controls how the returned array is indexed.
result_typeis a constant and can take the following values:PGSQL_ASSOC,PGSQL_NUMandPGSQL_BOTH. UsingPGSQL_NUM, pg_get_notify() will return an array with numerical indices, usingPGSQL_ASSOCit will return only associative indices whilePGSQL_BOTH, the default, will return both numerical and associative indices.
Zwracane wartości
An array containing the NOTIFY message name and backend PID.
Otherwise if no NOTIFY is waiting, then FALSE is returned.
Przykłady
Przykład #1 PostgreSQL NOTIFY message
<?php
$conn = pg_pconnect("dbname=publisher");
if (!$conn) {
echo "An error occured.\n";
exit;
}
// Listen 'author_updated' message from other processes
pg_query($conn, 'LISTEN author_updated;');
$notify = pg_get_notify($conn);
if (!$notify) {
echo "No messages\n";
} else {
print_r($notify);
}
?>
pg_get_pid
(PHP 4 >= 4.3.0, PHP 5)
pg_get_pid — Gets the backend's process ID
Opis
$connection
)pg_get_pid() gets the backend's (database server process) PID. The PID is useful to determine whether or not a NOTIFY message received via pg_get_notify() is sent from another process or not.
Parametry
-
connection -
PostgreSQL database connection resource.
Zwracane wartości
The backend database process ID.
Przykłady
Przykład #1 PostgreSQL backend PID
<?php
$conn = pg_pconnect("dbname=publisher");
if (!$conn) {
echo "An error occured.\n";
exit;
}
// Backend process PID. Use PID with pg_get_notify()
$pid = pg_get_pid($conn);
?>
pg_get_result
(PHP 4 >= 4.2.0, PHP 5)
pg_get_result — Pobiera wynik zapytania asynchroniczego
Opis
$polaczenie
] )pg_get_result() zwraca wynik zapytania asynchronicznego uruchomionego przez pg_send_query(), pg_send_query_params() lub pg_send_execute().
pg_send_query() oraz inne funkcje zapytań asynchronicznych może wysyłać wiele zapytań do serwera PostgreSQL, natomiast pg_get_result() jest używana do pobierania wyników każdego zapytania po kolei.
Parametry
-
polaczenie -
Identyfikator połączenia z bazą PostgreSQL.
Zwracane wartości
Identyfikator wyniku (ang. resource), lub FALSE gdy brak więcej dostępnych wyników.
Przykłady
Przykład #1 pg_get_result() - przykład
<?php
$polaczenie = pg_connect("dbname=wydawca") or die("Nie można się połączyć");
if (!pg_connection_busy($polaczenie)) {
pg_send_query($polaczenie, "select * from autorzy; select count(*) from autorzy;");
}
$wyn1 = pg_get_result($polaczenie);
echo "Pierwsze wywołanie pg_get_result(): $wyn1\n";
$wiersze1 = pg_num_rows($wyn1);
echo "$wyn1 ma $wiersze1 rekordy(ów)\n\n";
$wyn2 = pg_get_result($polaczenie);
echo "Drugie wywołanie pg_get_result(): $wyn2\n";
$wiersze2 = pg_num_rows($wyn2);
echo "$wyn2 ma $wiersze2 rekordy(ów)\n";
?>
Powyższy przykład wyświetli:
Pierwsze wywołanie pg_get_result(): Resource id #3 Resource id #3 ma 3 rekordy(ów) Drugie wywołanie pg_get_result(): Resource id #4 Resource id #4 ma 1 rekordy(ów)
pg_host
(PHP 4, PHP 5)
pg_host — Zwraca nazwę komputera związanego z połączeniem
Opis
$polaczenie
] )
pg_host() zwraca nazwę komputera,
dla danego identyfikatora polaczenie,
z którym połączony jest PostgreSQL.
Parametry
-
polaczenie -
Identyfikator połączenia do bazy PostgreSQL. Gdy parametr
polaczenienie został podany, domyślne połączenie jest używane. Domyślnym połączeniem jest ostatnie połączenie stworzone przez pg_connect() lub pg_pconnect().
Zwracane wartości
Łańcuch (ang. string) zawierający nazwę komputera, do którego
polaczenie jest nawiązane, lub FALSE w razie błędu.
Przykłady
Przykład #1 pg_host() - przykład
<?php
$pgsql_polacz = pg_connect("dbname=marek host=localhost");
if ($pgsql_polacz) {
print "Nawiązano połączenie do: " . pg_host($pgsql_polacz) . "<br/>\n";
} else {
print pg_last_error($pgsql_polacz);
exit;
}
?>
Zobacz też:
- pg_connect() - Otwiera tymczasowe połączenie do PostgreSQL-a
- pg_pconnect() - Otwiera trwałe połączenie z serwerem PostgreSQL
pg_insert
(PHP 4 >= 4.3.0, PHP 5)
pg_insert — Wstawia tablicę do tabeli
Opis
$identyfikator_połączenia
, string $nazwa_tabeli
, array $tablica_asocjacyjna
[, int $opcje
] )
pg_insert() wstawia wartości parametru tablica_asocjacyjna
do tabeli określonej przez parametr nazwa_tabeli.
Jeśli określono jakieś opcje,
funkcja pg_convert() stosuje
do parametru tablica_asocjacyjna określone opcje.
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Parametry
-
identyfikator_połączenia -
Identyfikator połączenia do bazy PostgreSQL.
-
nazwa_tabeli -
Nazwa tabeli, do której mają zostać dodane wiersze. Tabela
nazwa_tabelimusi mieć przynajmniej tyle kolumn, ile elementów matablica_asocjacyjna. -
tablica_asocjacyjna -
Tablica (ang. array), której klucze to nazwy pól w tabeli
nazwa_tabeli, oraz której wartościami są wartości tych pól, które mają zostać wpisane. -
opcje -
Dowolna kombinacja dowolnej ilości parametrów:
PGSQL_CONV_OPTS,PGSQL_DML_NO_CONV,PGSQL_DML_EXEC,PGSQL_DML_ASYNCorazPGSQL_DML_STRING. GdyPGSQL_DML_STRINGjest zawarty w parametrzeopcje, zwrócony zostanie łańcuch zapytania z URL (ang. query string).
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu. Zwraca łańcuch (ang. string) jeśli PGSQL_DML_STRING zostało wprowadzone
poprzez parametr opcje.
Przykłady
Przykład #1 pg_insert() - przykład
<?php
$polaczenie_do_bazy = pg_connect ('dbname=foo');
// To wywołanie jest bezpieczne, odkąd $_POST jest konwertowane automatycznie
$res = pg_insert($polaczenie_do_bazy, 'kopia_post', $_POST);
if ($res) {
echo "Dane z tablicy POST zapisane pomyślnie\n";
} else {
echo "Użytkownik musiał wysłać złe dane\n";
}
?>
pg_last_error
(PHP 4 >= 4.2.0, PHP 5)
pg_last_error — Zwraca łańcuch ostatniego komunikatu błędu dla połączenia
Opis
$polaczenie
] )
pg_last_error() zwraca ostatni komunikat błędu
dla połączenia danego parametrem polaczenie.
Komunikaty błędów mogą być zamazane przez wewnętrzne wywołania funkcji PostgreSQL(libpq). Funkcja może nie zwrócić właściwego komunikatu, jeśli wewnątrz modułu PostgreSQL wystąpiło wiele błędów.
Stosuj pg_result_error(), pg_result_error_field(), pg_result_status() i pg_connection_status() dla lepszej obsługi błędów.
Informacja:
Ta funkcja była poprzednio nazwana pg_errormessage().
Parametry
-
polaczenie -
Identyfikator połączenia do bazy danych PostgreSQL. Gdy
polaczenienie został podany, domyślne połączenie jest użyte. Domyślnym połączeniem jest ostatnie, stworzone przez pg_connect() lub pg_pconnect().
Zwracane wartości
Łańcuch (ang. string) zawierający ostatni komunikat błędu dla
danego poprzez parametr polaczenie połączenia, lub FALSE w razie niepowodzenia.
Przykłady
Przykład #1 pg_last_error() - przykład
<?php
$polaczenie = pg_connect("dbname=wydawca") or die("Nie można się połączyć");
// Zapytanie, które nie zostało wykonane
$wyn = pg_query($polaczenie, "select * from nie_istniejaca_tabela");
echo pg_last_error($polaczenie);
?>
Zobacz też:
- pg_result_error() - Zwraca błąd związany z identyfikatorem wyniku
- pg_result_error_field() - Returns an individual field of an error report.
pg_last_notice
(PHP 4 >= 4.0.6, PHP 5)
pg_last_notice — Zwraca komunikaty informacyjne serwera PostgreSQL
Opis
$connection
)
pg_last_notice() zwraca ostatni komunikat informacyjny
serwera PostgreSQL związanego z połączeniem connection.
Serwer PostgreSQL wysyła komunikaty informacyjne w pewnych przypadkach,
np. gdy trasakcja nie może być kontynuowana. Przy użyciu
pg_last_notice(), możesz uniknąć wywoływania bezużytecznych
zapytań, sprawdzając czy komunikat jest związany z transakcją czy nie.
Ta funkcja jest EKSPERYMENTALNA i nie jest jeszcze w pełni zaimplementowana. pg_last_notice() została dodana w PHP 4.0.6. Niestety PHP 4.0.6 ma błąd w obsłudze tych komunikatów. Używanie modułu PostgreSQL z PHP 4.0.6 nie jest zalecane, nawet jeśli nie używasz funkcji pg_last_notice().
Ta funkcja jest w pełni zaimplementowana w PHP 4.3.0. Wcześniejsze niż 4.3.0
wersje PHP ignorują parametr connection.
Śledzenie komunikatów informacyjnych może być ustawtione jako opcjonalne przez ustawienie parametru ini pgsql.ignore_notice na 1 od wersji PHP 4.3.0.
Logowanie komunikatów informacyjnych może być ustawtione jako opcjonalne przez ustawienie parametru ini pgsql.log_notice na 0 od wersji PHP 4.3.0. Dopuki pgsql.ignore_notice jest ustawione na 0, komunikaty informacyjne nie mogą być logowane.
Zobacz także pg_query() i pg_last_error().
pg_last_oid
(PHP 4 >= 4.2.0, PHP 5)
pg_last_oid — Zwraca identyfikator OID ostatniego wiersza
Opis
$wynik
)pg_last_oid() służy do pobrania OID przypisanego do dopisanego wiersza.
OID jest polem opcjonalnym od wersji PostgreSQL 7.2 i nie pojawi się domyślnie w PostgreSQL 8.1. Gdy pole OID nie pojawia się w tabeli, programista musi użyć pg_result_status() aby sprawdzić czy rekord został dopisany czy nie.
Aby pobrać wartość pola SERIAL we wstawionym wierszu, niezbędnym jest użycie funkcji PostgreSQL CURRVAL, przekazując sekwencję, której wymagana jest ostatnia wartość. Jeśli nazwa sekwencji nie jest znana, konieczne jest użycie funkcji pg_get_serial_sequence PostgreSQL-a 8.0.
PostgreSQL 8.1 ma funkcję LASTVAL, która zwraca wartość ostatnio użytej sekwencji w sesji. To uchyla potrzebę powoływania razem sekwencji, tabeli lub kolumny.
Informacja:
Ta funkcja była poprzednio nazwana pg_getlastoid().
Parametry
-
wynik -
Identyfikator wyniku zapytania PostgreSQL-a, zwrócony przez pg_query(), pg_query_params() lub pg_execute() (między innymi).
Zwracane wartości
Łańcuch (ang. string) zawierający OID przydzielony do ostatnio wstawionego
wiersza w określonym parametrem polaczenie połączeniem, lub FALSE w przypadku błędu lub
gdy OID nie jest dostępny.
Przykłady
Przykład #1 pg_last_oid() - przykład
<?php
$pgsql_polaczenie = pg_connect("dbname=ocena host=localhost");
$wyn1 = pg_query("CREATE TABLE test (a INTEGER) WITH OIDS");
$wyn2 = pg_query("INSERT INTO test VALUES (1)");
$oid = pg_last_oid($wyn2);
?>
Zobacz też:
- pg_query() - Realizujezapytanie do bazy danych
- pg_result_status() - Zwraca stan wyniku zapytania
pg_lo_close
(PHP 4 >= 4.2.0, PHP 5)
pg_lo_close — Zamyka wielki obiekt (LO)
Opis
$uchwyt
)
pg_lo_close() zamyka wielki obiekt
(z ang. Large Object - LO). uchwyt jest identyfikatorem
wielkiego obiektu (LO) wywołanego funkcją pg_lo_open().
Użycie interfejsu wielkich obiektów (LO) wymaga zamknięcia wszystkich operacji z nim związanych wewnątrz transakcji.
Informacja:
Ta funkcja była poprzednio nazwana pg_loclose().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 pg_lo_close() - przykład
<?php
$baza_danych = pg_connect("dbname=jacarta");
pg_query($baza_danych, "begin");
$oid = pg_lo_create($baza_danych);
echo "$oid\n";
$uchwyt = pg_lo_open($baza_danych, $oid, "w");
echo "$uchwyt\n";
pg_lo_write($uchwyt, "large object data");
pg_lo_close($uchwyt);
pg_query($baza_danych, "commit");
?>
Zobacz też:
- pg_lo_open() - Otwiera wielki obiekt (Large Object - LO)
- pg_lo_create() - Tworzy wielki obiekt (Large Object - LO)
- pg_lo_import() - Importuje wielki obiekt (Large Object - LO) z pliku
pg_lo_create
(PHP 4 >= 4.2.0, PHP 5)
pg_lo_create — Tworzy wielki obiekt (Large Object - LO)
Opis
$connection
)
pg_lo_create() tworzy wielki obiekt (LO) i zwraca jego
oid. Parametr connection wskazuje istniejące
połączenie do bazy. Tryby dostępu PostgreSQL-a: INV_READ, INV_WRITE i INV_ARCHIVE
nie są wspierane, obiekt jest tworzony zawsze z dostępem do odczytu i zapisu.
Tryb INV_ARCHIVE został usunięty z PostgreSQL-a (wersja 6.3 i nowsze). Funkcja
zwraca oid lub FALSE jeśli wystąpił błąd.
Użycie interfejsu wielkich obiektów (LO) wymaga zamknięcia wszystkich operacji z nim związanych wewnątrz transakcji.
Informacja:
Ta funkcja była poprzednio nazwana pg_locreate().
pg_lo_export
(PHP 4 >= 4.2.0, PHP 5)
pg_lo_export — Eksportuje wielki obiekt (Large Object - LO) do pliku
Opis
$polaczenie
, int $oid
, string $sciezka
)$oid
, string $sciezka
)pg_lo_export() pobiera wielki obiekt w bazie PostgreSQL i zapisuje jego zawartość do lokalnego systemu plików.
Użycie interfejsu wielkich obiektów (LO) wymaga zamknięcia wszystkich operacji z nim związanych wewnątrz transakcji.
Informacja:
Ta funkcja była poprzednio nazwana pg_loexport().
Parametry
-
polaczenie -
Identyfikator połączenia do bazy PostgreSQL. Gdy
polaczenienie zostało podane, domyślne połączenie zostaje użyte. Domyślnym połączeniem jest ostatnie stworzone przez pg_connect() lub pg_pconnect(). -
oid -
OID wielkiego obiektu w bazie danych.
-
sciezka -
Pełna ścieżka i nazwa pliku, do którego zostanie zapisana zawartość wielkiego obiektu w systemie plików klienta.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 pg_lo_export() - przykład
<?php
$baza_danych = pg_connect("dbname=jacarta");
pg_query($baza_danych, "begin");
$oid = pg_lo_create($baza_danych);
$uchwyt = pg_lo_open($baza_danych, $oid, "w");
pg_lo_write($uchwyt, "large object data");
pg_lo_close($uchwyt);
pg_lo_export($baza_danych, $oid, '/tmp/lob.dat');
pg_query($baza_danych, "commit");
?>
pg_lo_import
(PHP 4 >= 4.2.0, PHP 5)
pg_lo_import — Importuje wielki obiekt (Large Object - LO) z pliku
Opis
pg_lo_import() kreuje nowy Wielki Obiekt (LO) w bazie danych, używając pliku w systemie plików jako jego danych źródłowych.
Użycie interfejsu wielkich obiektów (LO) wymaga zamknięcia wszystkich operacji z nim związanych wewnątrz transakcji.
Informacja: Gdy włączony jest tryb bezpieczny, PHP sprawdza, czy pliki lub katalogi, na których zostaną wykonane operacje mają takie same UID (owner) jak skrypt, który jest aktualnie wykonywany.
Informacja:
Ta funkcja była poprzednio nazwana pg_loimport().
Parametry
-
polaczenie -
Identyfikator połączenia do bazy PostgreSQL. Gdy parametr
polaczenienie został podany, zostanie użyte domyślne połączenie. Domyślnym połączeniem jest ostatnie połączenie stworzone przez pg_connect() lub pg_pconnect(). -
sciezka -
Pełna ścieżka z nazwą pliku znajdującego się w systemie plików klienta, z którego zostanie przeczytany LO.
-
id_obiektu -
Jeśli
id_obiektuzostał podany, funkcja spróbuje stworzyć wielki obiekt o podanym unikalnym identyfikatorze, w przeciwnym razie serwer przydzieli dowolne id. Parametr został dodany w PHP 5.3 i jest uzależniony od mechanizmów działania, które jako pierwsze pojawiły się w PostgreSQL 8.1.
Zwracane wartości
Identyfikator OID nowo stworzonego LO, lub
FALSE w przypadku błędów.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.2.0 | Składnia tej funkcji uległa zmianie. Wcześniej wyglądała tak:
int pg_lo_import
( string
$sciezka
[, resource $polaczenie
] ) |
Przykłady
Przykład #1 pg_lo_import() - przykład
<?php
$baza_danych = pg_connect("dbname=warszawa");
pg_query($baza_danych, "begin");
$oid = pg_lo_import($baza_danych, '/tmp/lob.dat');
pg_query($baza_danych, "commit");
?>
Zobacz też:
- pg_lo_export() - Eksportuje wielki obiekt (Large Object - LO) do pliku
- pg_lo_open() - Otwiera wielki obiekt (Large Object - LO)
pg_lo_open
(PHP 4 >= 4.2.0, PHP 5)
pg_lo_open — Otwiera wielki obiekt (Large Object - LO)
Opis
$connection
, int $oid
, string $mode
)
pg_lo_open() otwiera wielki obiekt (LO) i zwraca identyfikator
połączenia do niego. oid wskazuje poprawny identyfikator
wielkiego obiektu (LO), mode może przyjmować wartości "r" - odczyt,
"w" - zapis, lub "rw" odczyt/zapis. Funkcja zwraca FALSE w razie błędu.
Nie wolno zamykać połączenia z serwerem przed zamknięciem wszystkich wielkich obiektów.
Użycie interfejsu wielkich obiektów (LO) wymaga zamknięcia wszystkich operacji z nim związanych wewnątrz transakcji.
Informacja:
Ta funkcja była poprzednio nazwana pg_loopen().
Zobacz także pg_lo_close() i pg_lo_create().
pg_lo_read_all
(PHP 4 >= 4.2.0, PHP 5)
pg_lo_read_all — Odczytuje wielki obiekt (Large Object - LO) i wysła go do przeglądarki
Opis
$large_object
)
pg_lo_read_all() odczytuje wielki obiekt (LO) i przekazuje go
wprost do przeglądarki, po wysłaniu wszystkich nagłówków. Przeznaczony głównie do
wysyłania danych binarnych, jak obrazy i dźwięk. Zwraca ilość odczytanych danych.
Funkcja zwraca FALSE w razie błędu.
Użycie interfejsu wielkich obiektów (LO) wymaga zamknięcia wszystkich operacji z nim związanych wewnątrz transakcji.
Informacja:
Ta funkcja była poprzednio nazwana pg_loreadall().
Zobacz także pg_lo_read().
pg_lo_read
(PHP 4 >= 4.2.0, PHP 5)
pg_lo_read — Odczytuje wielki obiekt (Large Object - LO)
Opis
$large_object
, int $len
)
pg_lo_read() odczytuje co najwyżej len
bajtów z wielkiego obiektu (LO) i zwraca je jako łańcuch.
large_object wskazuje identyfikator połączenia z
pg_lo_open(), len wskazuje maksymalną
dopuszczalną wielkość segmentu wielkiego obiektu. Funkcja zwraca FALSE w razie błędu.
Użycie interfejsu wielkich obiektów (LO) wymaga zamknięcia wszystkich operacji z nim związanych wewnątrz transakcji.
Informacja:
Ta funkcja była poprzednio nazwana pg_loread().
Zobacz także pg_lo_read_all().
pg_lo_seek
(PHP 4 >= 4.2.0, PHP 5)
pg_lo_seek — Przemieszcza wskaźnik położenia w wielkim obiekcie (Large Object - LO)
Opis
$large_object
, int $offset
[, int $whence
] )
pg_lo_seek() przemieszcza wskaźnik położenia w wielkim obiekcie (LO).
Parametr whence może przyjmować wartości PGSQL_SEEK_SET,
PGSQL_SEEK_CUR lub PGSQL_SEEK_END.
Zobacz także pg_lo_tell().
pg_lo_tell
(PHP 4 >= 4.2.0, PHP 5)
pg_lo_tell — Zwraca wskaźnik położenia w wielkim obiekcie (Large Object - LO)
Opis
$large_object
)pg_lo_tell() zwraca aktualną pozycję wskaźnika położenia w wielkim obiekcie (LO) liczoną od jego początku.
Zobacz także pg_lo_seek().
pg_lo_unlink
(PHP 4 >= 4.2.0, PHP 5)
pg_lo_unlink — Usuwa wielki obiekt (Large Object - LO)
Opis
$connection
, int $oid
)
pg_lo_unlink() usuwa wielki obiekt (LO) określony przez
oid. Zwraca TRUE jeśli operacja się powiedzie lub FALSE
jeśli wystąpi błąd.
Użycie interfejsu wielkich obiektów (LO) wymaga zamknięcia wszystkich operacji z nim związanych wewnątrz transakcji.
Informacja:
Ta funkcja była poprzednio nazwana pg_lounlink().
Zobacz także pg_lo_create() i pg_lo_import().
pg_lo_write
(PHP 4 >= 4.2.0, PHP 5)
pg_lo_write — Zapisuje do wielkiego obiektu (Large Object - LO)
Opis
$large_object
, string $data
)
pg_lo_write() zapisuje jak najwięcej do wielkiego obiektu
ze zmiennej data i zwraca liczbę bajtów zapisanych, lub FALSE
jeśli wystąpił błąd. Paramter large_object jest identyfikatorem
polączenia z pg_lo_open().
Użycie interfejsu wielkich obiektów (LO) wymaga zamknięcia wszystkich operacji z nim związanych wewnątrz transakcji.
Informacja:
Ta funkcja była poprzednio nazwana pg_lowrite().
Zobacz także pg_lo_create() i pg_lo_open().
pg_meta_data
(PHP 4 >= 4.3.0, PHP 5)
pg_meta_data — Pobiera informacje o tabeli
Opis
$connection
, string $table_name
)pg_meta_data() zwraca definicje tabeli dla argumentu table_name jako tablicę.
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Parametry
-
connection -
Identyfikator połączenia do bazy danych PostgreSQL.
-
table_name -
Nazwa tabeli.
Zwracane wartości
Tablica array z definicją tabeli, lub FALSE w przypadku błędu.
Przykłady
Przykład #1 Pobranie informacji o tabeli
<?php
$dbconn = pg_connect("dbname=publikacje") or die("Nie można się połączyć.");
$meta = pg_meta_data($dbconn, 'autorzy');
if (is_array($meta)) {
echo '<pre>';
var_dump($meta);
echo '</pre>';
}
?>
Powyższy przykład wyświetli:
array(3) {
["autor"]=>
array(5) {
["num"]=>
int(1)
["type"]=>
string(7) "varchar"
["len"]=>
int(-1)
["not null"]=>
bool(false)
["has default"]=>
bool(false)
}
["rok"]=>
array(5) {
["num"]=>
int(2)
["type"]=>
string(4) "int2"
["len"]=>
int(2)
["not null"]=>
bool(false)
["has default"]=>
bool(false)
}
["tytul"]=>
array(5) {
["num"]=>
int(3)
["type"]=>
string(7) "varchar"
["len"]=>
int(-1)
["not null"]=>
bool(false)
["has default"]=>
bool(false)
}
}
pg_num_fields
(PHP 4 >= 4.2.0, PHP 5)
pg_num_fields — Zwraca liczbę kolumn
Opis
$result
)pg_num_fields() zwraca liczbę kolumn w wyniku PostgreSQL. Argumentem jest właściwy identyfikator wyniku zwrócony przez pg_query(). Funkcja zwraca -1 w razie błędu.
Informacja:
Ta funkcja była poprzednio nazwana pg_numfields().
Zobacz także pg_num_rows() i pg_affected_rows().
pg_num_rows
(PHP 4 >= 4.2.0, PHP 5)
pg_num_rows — Zwraca liczbę wierszy
Opis
$result
)
pg_num_rows() zwraca liczbę wierszy w wyniku
result zwróconym przez pg_query().
Funkcja zwraca -1 w razie błędu.
Informacja:
Użyj pg_affected_rows() aby otrzymać liczbę wierszy zmodyfikowanych przez INSERT, UPDATE lub DELETE.
Informacja:
Ta funkcja była poprzednio nazwana pg_numrows().
Zobacz także pg_num_fields() i pg_affected_rows().
pg_options
(PHP 4, PHP 5)
pg_options — Podaje opcje powiązane z połączenim
Opis
$connection
)
pg_options() zwraca łańcuch zawierający opcje związane połączeniem
wskazanym przez parametr connection.
pg_parameter_status
(PHP 5)
pg_parameter_status — Looks up a current parameter setting of the server.
Opis
$connection
], string $param_name
)Looks up a current parameter setting of the server.
Certain parameter values are reported by the server automatically at
connection startup or whenever their values change. pg_parameter_status() can be
used to interrogate these settings. It returns the current value of a
parameter if known, or FALSE if the parameter is not known.
Parameters reported as of PostgreSQL 8.0 include server_version, server_encoding, client_encoding, is_superuser, session_authorization, DateStyle, TimeZone, and integer_datetimes. (server_encoding, TimeZone, and integer_datetimes were not reported by releases before 8.0.) Note that server_version, server_encoding and integer_datetimes cannot change after PostgreSQL startup.
PostgreSQL 7.3 or lower servers do not report parameter settings, pg_parameter_status() includes logic to obtain values for server_version and client_encoding anyway. Applications are encouraged to use pg_parameter_status() rather than ad hoc code to determine these values.
On a pre-7.4 PostgreSQL server, changing client_encoding via SET after connection startup will not be reflected by pg_parameter_status().
Parametry
-
connection -
PostgreSQL database connection resource. When
connectionis not present, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect(). -
param_name -
Possible
param_namevalues include server_version, server_encoding, client_encoding, is_superuser, session_authorization, DateStyle, TimeZone, and integer_datetimes.
Zwracane wartości
A string containing the value of the parameter, FALSE on failure or invalid
param_name.
Przykłady
Przykład #1 pg_parameter_status() example
<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");
echo "Server encoding: ", pg_parameter_status($dbconn, "server_encoding");
?>
Powyższy przykład wyświetli:
Server encoding: SQL_ASCII
pg_pconnect
(PHP 4, PHP 5)
pg_pconnect — Otwiera trwałe połączenie z serwerem PostgreSQL
Opis
$łańcuch_połączenia
[, int $typ_połączenia
] )pg_pconnect() otwiera trwałe połączenie z serwerem PostgreSQL. Zwraca identyfikator połączenia używany przez inne funkcje PostgreSQL-a.
Ponowne wywołanie funkcji pg_pconnect()
z identycznym parametrem łańcuch_połączenia, jak w połączeniu już istniejącym,
zwróci identyfikator istniejącego połączenia, chyba, że podasz
PGSQL_CONNECT_FORCE_NEW jako parametr
typ_połączenia.
Aby zezwolić na używanie stałych połączeń, należy ustawić dyrektywę pgsql.allow_persistent w php.ini na "On" (jest to ustawienie domyślne). Maksymalna liczba jednoczesnych trwałych połączeń może być zdefiniowana przez dyrektywę pgsql.max_persistent w php.ini (domyślnia wartość to -1 oznacza brak ograniczeń). Maksymalna liczba wszystkich połączeń może być ustawiona przez dyrektywę pgsql.max_links w php.ini.
pg_close() nie zamyka trwałych połączeń otwartych przez pg_pconnect().
Parametry
-
connection_string -
Parametr
łańcuch_połączeniamoże zostać pusty w celu użycia domyślnych parametrów, lub może zawierać jedno, lub więcej ustawień oddzielonych spacją. Każde ustawienie ma format klucz = wartość. Spacje po obu stronach znaku równości są opcjonalne. Aby stworzyć wartość pustą, lub zawierającą spacje, otocz ją pojedynczymi znakami cudzysłowia, np. klucz = 'wartość'. Pojedyncze cudzysłowy, oraz backslashe wewnątrz wartości muszą być poprzedzone znakiem ucieczki "\", np., \' oraz \\.Aktualnie rozpoznawanymi parametrami są:
host,hostaddr,portdbname,user,password,connect_timeout,options,tty(ignorowany),sslmoderequiressl(zdeprecjonowany na korzyśćsslmode), orazservice. Niektóre z tych argumentów są zależne od używanej wersji PostgreSQL. -
connect_type -
Jeśli podano
PGSQL_CONNECT_FORCE_NEW, zostanie stworzone nowe połączenie, nawet gdyłańcuch_połączeniajest identyczny, jak w jakimś istniejącym połączeniu.
Zwracane wartości
Nawiązanie połączenie z serwerem PostgreSQL w przypadku powodzenia, FALSE w razie błędu.
Przykłady
Przykład #1 Używanie pg_pconnect()
<?php
$polaczenie = pg_pconnect("dbname=mary");
//Połączenie z bazą o nazwie "mary"
$polaczenie2 = pg_pconnect("host=localhost port=5432 dbname=mary");
//Połączenie z bazą o nazwie "mary" na "localhost" portem "5432"
$polaczenie3 = pg_pconnect("host=owca port=5432 dbname=mary user=jagnie password=foo");
//Połączenie z bazą o nazwie "mary" na hoście "owca" z nazwą użytkownika i hasłem
$lancuch_polaczenia = "host=owca port=5432 dbname=test user=jagnie password=bar";
$polaczenie4 = pg_pconnect($lancuch_polaczenia);
//Połączenie z bazą o nazwie "test" na hoście "owca" z nazwą użytkownika i hasłem
?>
Zobacz też:
- pg_connect() - Otwiera tymczasowe połączenie do PostgreSQL-a
- Trwałe połączenia z serwerem baz danych
pg_ping
(PHP 4 >= 4.3.0, PHP 5)
pg_ping — Ping database connection
Opis
$connection
] )pg_ping() pings a database connection and tries to reconnect it if it is broken.
Parametry
-
connection -
PostgreSQL database connection resource. When
connectionis not present, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 pg_ping() example
<?php
$conn = pg_pconnect("dbname=publisher");
if (!$conn) {
echo "An error occured.\n";
exit;
}
if (!pg_ping($conn))
die("Connection is broken\n");
?>
Zobacz też:
- pg_connection_status() - Zwraca stan połączenia
- pg_connection_reset() - Restartuje połączenie
pg_port
(PHP 4, PHP 5)
pg_port — Zwraca numer portu związany z połączeniem
Opis
$connection
)
pg_port() zwraca numer portu dla połączenia wskazanego przez
connection.
pg_prepare
(PHP 5 >= 5.1.0)
pg_prepare — Submits a request to create a prepared statement with the given parameters, and waits for completion.
Opis
$connection
], string $stmtname
, string $query
)pg_prepare() creates a prepared statement for later execution with pg_execute() or pg_send_execute(). This feature allows commands that will be used repeatedly to be parsed and planned just once, rather than each time they are executed. pg_prepare() is supported only against PostgreSQL 7.4 or higher connections; it will fail when using earlier versions.
The function creates a prepared statement named stmtname from the query
string, which must contain a single SQL command. stmtname may be "" to
create an unnamed statement, in which case any pre-existing unnamed
statement is automatically replaced; otherwise it is an error if the
statement name is already defined in the current session. If any parameters
are used, they are referred to in the query as $1, $2, etc.
Prepared statements for use with pg_prepare() can also be created by executing SQL PREPARE statements. (But pg_prepare() is more flexible since it does not require parameter types to be pre-specified.) Also, although there is no PHP function for deleting a prepared statement, the SQL DEALLOCATE statement can be used for that purpose.
Parametry
-
connection -
PostgreSQL database connection resource. When
connectionis not present, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect(). -
stmtname -
The name to give the prepared statement. Must be unique per-connection. If "" is specified, then an unnamed statement is created, overwriting any previously defined unnamed statement.
-
query -
The parameterized SQL statement. Must contain only a single statement. (multiple statements separated by semi-colons are not allowed.) If any parameters are used, they are referred to as $1, $2, etc.
Zwracane wartości
A query result resource on success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 Using pg_prepare()
<?php
// Connect to a database named "mary"
$dbconn = pg_connect("dbname=mary");
// Prepare a query for execution
$result = pg_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name = $1');
// Execute the prepared query. Note that it is not necessary to escape
// the string "Joe's Widgets" in any way
$result = pg_execute($dbconn, "my_query", array("Joe's Widgets"));
// Execute the same prepared query, this time with a different parameter
$result = pg_execute($dbconn, "my_query", array("Clothes Clothes Clothes"));
?>
Zobacz też:
- pg_execute() - Sends a request to execute a prepared statement with given parameters, and waits for the result.
- pg_send_execute() - Sends a request to execute a prepared statement with given parameters, without waiting for the result(s).
pg_put_line
(PHP 4 >= 4.0.3, PHP 5)
pg_put_line — Wysyła łańcuch zakończony znakiem NULL do serwera PostgreSQL
Opis
$connection
], string $data
)
pg_put_line() wysyła łańcuch zakończony przez NULL
do serwera PostgreSQL. Funkcja jest użyteczna do bardzo szybkiego
wstawiania danych to tabel, inicjowanych przez operację copy PostgreSQL-a.
Końcowy znak NULL jest wstawiany automatycznie. Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Informacja:
Aplikacja musi jawnie wysłać dwa znaki: "\." w końcowej linii, aby poinformować serwer że zakończyła wysyłać dane.
Zobacz także pg_end_copy().
Przykład #1 Szybkie wstawianie danych do tebeli
<?php
$conn = pg_pconnect ("dbname=foo");
pg_query($conn, "create table bar (a int4, b char(16), d float8)");
pg_query($conn, "copy bar from stdin");
pg_put_line($conn, "3\thello world\t4.5\n");
pg_put_line($conn, "4\tgoodbye world\t7.11\n");
pg_put_line($conn, "\\.\n");
pg_end_copy($conn);
?>
pg_query_params
(PHP 5 >= 5.1.0)
pg_query_params — Submits a command to the server and waits for the result, with the ability to pass parameters separately from the SQL command text.
Opis
$connection
], string $query
, array $params
)Submits a command to the server and waits for the result, with the ability to pass parameters separately from the SQL command text.
pg_query_params() is like pg_query(), but offers additional functionality: parameter values can be specified separately from the command string proper. pg_query_params() is supported only against PostgreSQL 7.4 or higher connections; it will fail when using earlier versions.
If parameters are used, they are referred to in the query
string as $1, $2, etc. params specifies the actual values of the
parameters. A NULL value in this array means the corresponding parameter is SQL
NULL.
The primary advantage of pg_query_params() over pg_query()
is that parameter values
may be separated from the query string, thus avoiding the need for tedious
and error-prone quoting and escaping. Unlike pg_query(),
pg_query_params() allows at
most one SQL command in the given string. (There can be semicolons in it,
but not more than one nonempty command.)
Parametry
-
connection -
PostgreSQL database connection resource. When
connectionis not present, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect(). -
query -
The parameterized SQL statement. Must contain only a single statement. (multiple statements separated by semi-colons are not allowed.) If any parameters are used, they are referred to as $1, $2, etc.
-
params -
An array of parameter values to substitute for the $1, $2, etc. placeholders in the original prepared query string. The number of elements in the array must match the number of placeholders.
Zwracane wartości
A query result resource on success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 Using pg_query_params()
<?php
// Connect to a database named "mary"
$dbconn = pg_connect("dbname=mary");
// Find all shops named Joe's Widgets. Note that it is not necessary to
// escape "Joe's Widgets"
$result = pg_query_params($dbconn, 'SELECT * FROM shops WHERE name = $1', array("Joe's Widgets"));
// Compare against just using pg_query
$str = pg_escape_string("Joe's Widgets");
$result = pg_query($dbconn, "SELECT * FROM shops WHERE name = '{$str}'");
?>
pg_query
(PHP 4 >= 4.2.0, PHP 5)
pg_query — Realizujezapytanie do bazy danych
Opis
$zapytanie
)$identyfikator_połączenia
, string $zapytanie
)
pg_query() wykonuje zapytanie
na określonej parametrem identyfikator_połączenia bazie danych.
Jeśli nadarzy się błąd, oraz zwracane jest FALSE, jego szczegóły mogą
zostać wydobyte dzięki użyciu funkcji pg_last_error(),
jeśli połączenie jest poprawne.
Informacja: Chociaż
identyfikator_połączeniamożna pominąć, nie jest to zalecane, gdyż może to powodować trudne do znalezienia błędy w skrypcie.
Informacja:
Ta funkcja była poprzednio nazwana pg_exec(). pg_exec() jest wciąż dostępna w celu zachowania kompatybilności, ale zalecane jest używanie nowej nazwy.
Parametry
-
identyfikator_połączenia -
Identyfikator połączenia do bazy PostgreSQL. Jeśli
identyfikator_połączenianie został podany, zostanie użyte domyślne połączenie. Domyślnym połączeniem jest to, które jako ostatnie zostało stworzone przez jedną z funkcji: pg_connect() lub pg_pconnect(). -
zapytanie -
Polecenie lub polecenia SQL, do wykonania. Kiedy do funkcji podane zostanie więcej jak jedno zapytanie, wykonają się one automatycznie jako jedna operacja, chyba, że komendy BEGIN/COMMIT są zawarte w zapytaniu. Niemniej jednak, używanie wielu operacji w jednym wywołaniu funkcji nie jest zalecane.
Zwracane wartości
Identyfikator wyniku zapytania w przypadku sukcesu, lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 pg_query() - przykład
<?php
$polaczenie = pg_pconnect("dbname=publisher");
if (!$polaczenie) {
echo "Wystąpił błąd.\n";
exit;
}
$wynik = pg_query($polaczenie, "SELECT autor, email FROM autorzy");
if (!$wynik) {
echo "Wystąpił błąd.\n";
exit;
}
while ($wiersz = pg_fetch_row($wynik)) {
echo "Autor: $wiersz[0] E-mail: $wiersz[1]";
echo "<br />\n";
}
?>
Przykład #2 Używanie pg_query() z wieloma zapytaniami
<?php
$polaczenie = pg_pconnect("dbname=wydawca");
// te polecenia wykonają się jako jedna operacja
$zapytanie = "UPDATE autorzy SET autor=UPPER(autor) WHERE id=1;";
$zapytanie .= "UPDATE autorzy SET autor=LOWER(autor) WHERE id=2;";
$zapytanie .= "UPDATE autorzy SET autor=NULL WHERE id=3;";
pg_query($polaczenie, $zapytanie);
?>
Zobacz też:
- pg_connect() - Otwiera tymczasowe połączenie do PostgreSQL-a
- pg_pconnect() - Otwiera trwałe połączenie z serwerem PostgreSQL
- pg_fetch_array() - Pobiera wiersz jako tablicę
- pg_fetch_object() - Pobiera wiersz jako obiekt
- pg_num_rows() - Zwraca liczbę wierszy
- pg_affected_rows() - Zwraca liczbę zmodyfikowanych wierszy
pg_result_error_field
(PHP 5 >= 5.1.0)
pg_result_error_field — Returns an individual field of an error report.
Opis
$result
, int $fieldcode
)
pg_result_error_field() returns one of the detailed error message
fields associated with result resource. It is only available
against a PostgreSQL 7.4 or above server. The error field is specified by
the fieldcode.
Because pg_query() and pg_query_params() return FALSE if the query fails,
you must use pg_send_query() and
pg_get_result() to get the result handle.
If you need to get additional error information from failed pg_query() queries, use pg_set_error_verbosity() and pg_last_error() and then parse the result.
Parametry
-
result -
A PostgreSQL query result resource from a previously executed statement.
-
fieldcode -
Possible
fieldcodevalues are:PGSQL_DIAG_SEVERITY,PGSQL_DIAG_SQLSTATE,PGSQL_DIAG_MESSAGE_PRIMARY,PGSQL_DIAG_MESSAGE_DETAIL,PGSQL_DIAG_MESSAGE_HINT,PGSQL_DIAG_STATEMENT_POSITION,PGSQL_DIAG_INTERNAL_POSITION(PostgreSQL 8.0+ only),PGSQL_DIAG_INTERNAL_QUERY(PostgreSQL 8.0+ only),PGSQL_DIAG_CONTEXT,PGSQL_DIAG_SOURCE_FILE,PGSQL_DIAG_SOURCE_LINEorPGSQL_DIAG_SOURCE_FUNCTION.
Zwracane wartości
A string containing the contents of the error field, NULL if the field does not exist or FALSE
on failure.
Przykłady
Przykład #1 pg_result_error_field() example
<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");
if (!pg_connection_busy($dbconn)) {
pg_send_query($dbconn, "select * from doesnotexist;");
}
$res1 = pg_get_result($dbconn);
echo pg_result_error_field($res1, PGSQL_DIAG_SQLSTATE);
?>
pg_result_error
(PHP 4 >= 4.2.0, PHP 5)
pg_result_error — Zwraca błąd związany z identyfikatorem wyniku
Opis
$result
)
pg_result_error() zwraca komunikat błędu związany z identyfikatorem
wyniku result. Dzięki temu użytkownik ma większą szanse aby
otrzymać właściwy komunikat niż przy użyciu pg_last_error().
Zobacz także pg_query(), pg_send_query(), pg_get_result(), pg_last_error() i pg_last_notice()
pg_result_seek
(PHP 4 >= 4.3.0, PHP 5)
pg_result_seek — Set internal row offset in result resource
Opis
$result
, int $offset
)pg_result_seek() sets the internal row offset in a result resource.
Parametry
-
result -
PostgreSQL query result resource, returned by pg_query(), pg_query_params() or pg_execute() (among others).
-
offset -
Row to move the internal offset to in the
resultresource. Rows are numbered starting from zero.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 pg_result_seek() example
<?php
// Connect to the database
$conn = pg_pconnect("dbname=publisher");
// Execute a query
$result = pg_query($conn, "SELECT author, email FROM authors");
// Seek to the 3rd row (assuming there are 3 rows)
pg_result_seek($result, 2);
// Fetch the 3rd row
$row = pg_fetch_row($result);
?>
Zobacz też:
- pg_fetch_row() - Pobiera wiersz jako tablicę z indeksami numerycznymi
- pg_fetch_assoc() - Fetch a row as an associative array
- pg_fetch_array() - Pobiera wiersz jako tablicę
- pg_fetch_object() - Pobiera wiersz jako obiekt
- pg_fetch_result() - Pobiera dane z wyniku
pg_result_status
(PHP 4 >= 4.2.0, PHP 5)
pg_result_status — Zwraca stan wyniku zapytania
Opis
pg_result_status() zwraca stan identyfikatora wyniku, lub oznaczenie dopełnienia komendy, związane z wynikiem
Parametry
-
wynik -
Identyfikator wyniku zapytania PostgreSQL-a, zwrócony przez pg_query(), pg_query_params() lub pg_execute() (między innymi).
-
typ -
Zarówno
PGSQL_STATUS_LONGaby zwrócić liczbowy stan parametruwynik, jak iPGSQL_STATUS_STRINGaby zwrócić oznaczenie parametruwynik. Jeśli nie podano,PGSQL_STATUS_LONGzostanie domyślnie użyte.
Zwracane wartości
Możliwe zwracane wartości to: PGSQL_EMPTY_QUERY,
PGSQL_COMMAND_OK, PGSQL_TUPLES_OK, PGSQL_COPY_OUT,
PGSQL_COPY_IN, PGSQL_BAD_RESPONSE, PGSQL_NONFATAL_ERROR oraz
PGSQL_FATAL_ERROR gdy określono PGSQL_STATUS_LONG.
W przeciwnym wypadku łańcuch (ang. string) zawierający oznaczenie komendy PostgreSQL-a jest zwracany.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.3.0 |
Parametr typ został dodany.
|
Przykłady
Przykład #1 pg_result_status() - przykład
<?php
// Połącz się z bazą
$polaczenie = pg_pconnect("dbname=wydawca");
// Wykonaj COPY
$wynik = pg_query($polaczenie, "COPY autorzy FROM STDIN;");
// Pobierz stan wyniku
$stan = pg_result_status($wynik);
// Ustal stan
if ($stan == PGSQL_COPY_IN)
echo "Kopiowanie rozpoczęło się.";
else
echo "Kopiowanie nie powiodło się.";
?>
Powyższy przykład wyświetli:
Kopiowanie rozpoczęło się.
pg_select
(PHP 4 >= 4.3.0, PHP 5)
pg_select — Wybiera wiersze
Opis
$identyfikator_połączenia
, string $nazwa_tabeli
, array $tablica_asocjacyjna
[, int $opcje
] )pg_select() wybiera wiersze określone przez tablicę tablica_asocjacyjna która zawiera dane w postaci: kolumna=>wartość. Jeśli zapytanie się powiedzie, zwraca tablicę zawierającą wszystkie wiersze i kolumny spełniające warunek określony przez tablica_asocjacyjna
Jeśli określono parametr opcje to funkcja, pg_convert() stosuje do tablicy tablica_asocjacyjna określone flagi.
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Parametry
-
identyfikator_połączenia -
Identyfikator połączenia do bazy PostgreSQL.
-
nazwa_tabeli -
Nazwa tabeli, z której będą wybrane wiersze.
-
tablica_asocjacyjna -
Tablica (ang. array), której kluczami są nazwy pól w tabeli
nazwa_tabeli, oraz której wartości są warunkami, które muszą spełniać wyszukiwane wiersze. -
opcje -
Dowolna kombinacja dowolnej ilości parametrów:
PGSQL_CONV_FORCE_NULL,PGSQL_DML_NO_CONV,PGSQL_DML_EXEC,PGSQL_DML_ASYNCorazPGSQL_DML_STRING. JeśliPGSQL_DML_STRINGjest częścią podanego parametruopcje, zostanie zwrócony łańcuch zapytania.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu. Returns string if PGSQL_DML_STRING is passed
via options.
Przykłady
Przykład #1 pg_select() example
<?php
$db = pg_connect('dbname=foo');
// This is safe, since $_POST is converted automatically
$rec = pg_select($db, 'post_log', $_POST);
if ($rec) {
echo "Records selected\n";
var_dump($rec);
} else {
echo "User must have sent wrong inputs\n";
}
?>
pg_send_execute
(PHP 5 >= 5.1.0)
pg_send_execute — Sends a request to execute a prepared statement with given parameters, without waiting for the result(s).
Opis
$connection
, string $stmtname
, array $params
)Sends a request to execute a prepared statement with given parameters, without waiting for the result(s).
This is similar to pg_send_query_params(), but the command to be executed is specified by naming a previously-prepared statement, instead of giving a query string. The function's parameters are handled identically to pg_execute(). Like pg_execute(), it will not work on pre-7.4 versions of PostgreSQL.
Parametry
-
connection -
PostgreSQL database connection resource. When
connectionis not present, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect(). -
stmtname -
The name of the prepared statement to execute. if "" is specified, then the unnamed statement is executed. The name must have been previously prepared using pg_prepare(), pg_send_prepare() or a PREPARE SQL command.
-
params -
An array of parameter values to substitute for the $1, $2, etc. placeholders in the original prepared query string. The number of elements in the array must match the number of placeholders.
Zwracane wartości
Returns TRUE on success, FALSE on failure. Use pg_get_result()
to determine the query result.
Przykłady
Przykład #1 Using pg_send_execute()
<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");
// Prepare a query for execution
if (!pg_connection_busy($dbconn)) {
pg_send_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name = $1');
$res1 = pg_get_result($dbconn);
}
// Execute the prepared query. Note that it is not necessary to escape
// the string "Joe's Widgets" in any way
if (!pg_connection_busy($dbconn)) {
pg_send_execute($dbconn, "my_query", array("Joe's Widgets"));
$res2 = pg_get_result($dbconn);
}
// Execute the same prepared query, this time with a different parameter
if (!pg_connection_busy($dbconn)) {
pg_send_execute($dbconn, "my_query", array("Clothes Clothes Clothes"));
$res3 = pg_get_result($dbconn);
}
?>
Zobacz też:
- pg_prepare() - Submits a request to create a prepared statement with the given parameters, and waits for completion.
- pg_send_prepare() - Sends a request to create a prepared statement with the given parameters, without waiting for completion.
- pg_execute() - Sends a request to execute a prepared statement with given parameters, and waits for the result.
pg_send_prepare
(PHP 5 >= 5.1.0)
pg_send_prepare — Sends a request to create a prepared statement with the given parameters, without waiting for completion.
Opis
$connection
, string $stmtname
, string $query
)Sends a request to create a prepared statement with the given parameters, without waiting for completion.
This is an asynchronous version of pg_prepare(): it returns TRUE if it was able to
dispatch the request, and FALSE if not. After a successful call, call
pg_get_result() to determine whether the server successfully created the
prepared statement. The function's parameters are handled identically to
pg_prepare(). Like pg_prepare(), it will not work
on pre-7.4 versions of PostgreSQL.
Parametry
-
connection -
PostgreSQL database connection resource. When
connectionis not present, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect(). -
stmtname -
The name to give the prepared statement. Must be unique per-connection. If "" is specified, then an unnamed statement is created, overwriting any previously defined unnamed statement.
-
query -
The parameterized SQL statement. Must contain only a single statement. (multiple statements separated by semi-colons are not allowed.) If any parameters are used, they are referred to as $1, $2, etc.
Zwracane wartości
Returns TRUE on success, FALSE on failure. Use pg_get_result()
to determine the query result.
Przykłady
Przykład #1 Using pg_send_prepare()
<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");
// Prepare a query for execution
if (!pg_connection_busy($dbconn)) {
pg_send_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name = $1');
$res1 = pg_get_result($dbconn);
}
// Execute the prepared query. Note that it is not necessary to escape
// the string "Joe's Widgets" in any way
if (!pg_connection_busy($dbconn)) {
pg_send_execute($dbconn, "my_query", array("Joe's Widgets"));
$res2 = pg_get_result($dbconn);
}
// Execute the same prepared query, this time with a different parameter
if (!pg_connection_busy($dbconn)) {
pg_send_execute($dbconn, "my_query", array("Clothes Clothes Clothes"));
$res3 = pg_get_result($dbconn);
}
?>
Zobacz też:
- pg_connect() - Otwiera tymczasowe połączenie do PostgreSQL-a
- pg_pconnect() - Otwiera trwałe połączenie z serwerem PostgreSQL
- pg_execute() - Sends a request to execute a prepared statement with given parameters, and waits for the result.
- pg_send_execute() - Sends a request to execute a prepared statement with given parameters, without waiting for the result(s).
- pg_send_query_params() - Submits a command and separate parameters to the server without waiting for the result(s).
pg_send_query_params
(PHP 5 >= 5.1.0)
pg_send_query_params — Submits a command and separate parameters to the server without waiting for the result(s).
Opis
$connection
, string $query
, array $params
)Submits a command and separate parameters to the server without waiting for the result(s).
This is equivalent to pg_send_query() except that query
parameters can be specified separately from the
query string. The function's parameters are
handled identically to pg_query_params(). Like
pg_query_params(), it will not work on pre-7.4 PostgreSQL
connections, and it allows only one command in the query string.
Parametry
-
connection -
PostgreSQL database connection resource.
-
query -
The parameterized SQL statement. Must contain only a single statement. (multiple statements separated by semi-colons are not allowed.) If any parameters are used, they are referred to as $1, $2, etc.
-
params -
An array of parameter values to substitute for the $1, $2, etc. placeholders in the original prepared query string. The number of elements in the array must match the number of placeholders.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Use pg_get_result() to determine the query result.
Przykłady
Przykład #1 Using pg_send_query_params()
<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");
// Using parameters. Note that it is not necessary to quote or escape
// the parameter.
pg_send_query_params($dbconn, 'select count(*) from authors where city = $1', array('Perth'));
// Compare against basic pg_send_query usage
$str = pg_escape_string('Perth');
pg_send_query($dbconn, "select count(*) from authors where city = '${str}'");
?>
pg_send_query
(PHP 4 >= 4.2.0, PHP 5)
pg_send_query — Wysyła zapytanie asynchroniczne
Opis
$identyfikator_połączenia
, string $zapytanie
)
pg_send_query() wysyła asynchroniczne zapytanie lub zapytania do połączenia
określonego przez identyfikator_połączenia. W przeciwieństwie do
pg_query(), pozwala wysłać jednorazowo wiele zapytań do PostgreSQL-a, na następnie
pobrać wyniki jeden po drugim używając funkcji
pg_get_result().
Wykonywanie skryptu nie jest blokowane w czasie wykonywania zapytań. Możesz użyć pg_connection_busy() aby sprawdzić czy połączenie jest nie jest zajęte (np. wykonuje się inne zapytanie). Zapytania mogą zostać przerwane przez użycie funkcji pg_cancel_query().
Tak więc użytkownik może wysłać wiele zapytań jednocześnie, ale nie może ich wysyłać jeśli połączenie jest zajęte. Jeśli zapytanie będzie wysłane gdy połączenie jest zajęte, będzie oczekiwało aż wykona się poprzednie zapytanie i utracone zostaną wszystkie wyniki.
Parametry
-
identyfikator_połączenia -
Identyfikator połączenia do bazy PostgreSQL.
-
zapytanie -
Instrukcja lub instrukcje SQL do wykonania.
Dane w zapytaniu powinny posiadać znaki unikowe.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Użyj pg_get_result(), aby ustalić wynik zapytania.
Przykłady
Przykład #1 Przykład pg_send_query()
<?php
$polaczenie_z_baza = pg_connect("dbname=wydawca") or die("Nie można było się połączyć");
if (!pg_connection_busy($polaczenie_z_baza)) {
pg_send_query($polaczenie_z_baza, "select * from autorzy; select count(*) from autorzy;");
}
$wynik1 = pg_get_result($polaczenie_z_baza);
echo "Pierwsze wywołanie pg_get_result(): $wynik1\n";
$wiersze1 = pg_num_rows($wynik1);
echo "$wynik1 ma $wiersze1 wpisów\n\n";
$wynik2 = pg_get_result($polaczenie_z_baza);
echo "Drugie wywołanie pg_get_result(): $wynik2\n";
$wiersze2 = pg_num_rows($wynik2);
echo "$wynik2 ma $wiersze2 wpisów\n";
?>
Powyższy przykład wyświetli:
Pierwsze wywołanie pg_get_result(): Resource id #3 Resource id #3 ma 8 wpisów Drugie wywołanie pg_get_result(): Resource id #4 Resource id #4 ma 5 wpisów
Zobacz też:
- pg_query() - Realizujezapytanie do bazy danych
- pg_cancel_query() - Przerywa zapytanie asynchroniczne
- pg_get_result() - Pobiera wynik zapytania asynchroniczego
- pg_connection_busy() - Sprawdza czy połączenie jest zajęte czy wolne
pg_set_client_encoding
(PHP 4 >= 4.0.3, PHP 5)
pg_set_client_encoding — Ustawia stronę kodową klienta PostgreSQL-a
Opis
$connection
], string $encoding
)pg_set_client_encoding() ustawia stronę kodową klienta i zwraca 0 w razie powodzenia lub -1 w razie błedu.
encoding jest stroną kodową klienta i może przyjmować następujace
wartości: SQL_ASCII, EUC_JP, EUC_CN, EUC_KR, EUC_TW, UNICODE,
MULE_INTERNAL, LATINX (X=1...9), KOI8, WIN, ALT, SJIS, BIG5,
WIN1250. Dostępne strony kodowe zależą od PostgreSQL-a i wersji libpq.
Sprawdź w podręczniku PostgreSQL jakie są dostępne strony kodowe dla twojego
PostgreSQL-a.
Informacja:
Ta funkcja wymaga PHP-4.0.3 lub nowszego i PostgreSQL-7.0 lub nowszego. Dostępne strony kodowe zależą od wersji PostgreSQL.
Ta funkcja była poprzednio nazwana pg_setclientencoding().
Zobacz także pg_client_encoding().
pg_set_error_verbosity
(PHP 5 >= 5.1.0)
pg_set_error_verbosity — Determines the verbosity of messages returned by pg_last_error() and pg_result_error().
Opis
$connection
], int $verbosity
)Determines the verbosity of messages returned by pg_last_error() and pg_result_error().
pg_set_error_verbosity() sets the verbosity mode, returning the connection's previous
setting. In PGSQL_ERRORS_TERSE mode, returned messages include severity, primary text, and
position only; this will normally fit on a single line. The default mode (PGSQL_ERRORS_DEFAULT)
produces messages that include the above plus any detail, hint, or context
fields (these may span multiple lines). The PGSQL_ERRORS_VERBOSE mode includes all available
fields. Changing the verbosity does not affect the messages available from
already-existing result objects, only subsequently-created ones.
Parametry
-
connection -
PostgreSQL database connection resource. When
connectionis not present, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect(). -
verbosity -
The required verbosity:
PGSQL_ERRORS_TERSE,PGSQL_ERRORS_DEFAULTorPGSQL_ERRORS_VERBOSE.
Zwracane wartości
The previous verbosity level: PGSQL_ERRORS_TERSE,
PGSQL_ERRORS_DEFAULT
or PGSQL_ERRORS_VERBOSE.
Przykłady
Przykład #1 pg_set_error_verbosity() example
<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");
if (!pg_connection_busy($dbconn)) {
pg_send_query($dbconn, "select * from doesnotexist;");
}
pg_set_error_verbosity($dbconn, PGSQL_ERRORS_VERBOSE);
$res1 = pg_get_result($dbconn);
echo pg_result_error($res1);
?>
Zobacz też:
- pg_last_error() - Zwraca łańcuch ostatniego komunikatu błędu dla połączenia
- pg_result_error() - Zwraca błąd związany z identyfikatorem wyniku
pg_trace
(PHP 4 >= 4.0.1, PHP 5)
pg_trace — Uruchamia śledzenie połączeń z PostgreSQL
Opis
$pathname
[, string $mode
[, resource $connection
]] )
pg_trace() uruchamia śledzenie połączeń między
klientem a serwerem PostgreSQL-a. Wynik śledzenia jest zapisywany do pliku
wskazanego przez pathname.
Aby w pełni zrozumieć wyniki śledzenia potrzebna jest wiedza o szczegółach wewnętrznej
komunikacji PostgreSQL-a. Nieobeznani z tymi szczegółami, mogą
jednak wykorzystać tą funkcję do śledzenia błędów w zapytaniach
wysyłanych do serwera. Przykładowo, wykonując
grep '^To backend' trace.log
można zobaczyć zapytania które były wysłane do serwera.
Więcej szczegółow można dowiedzieć się z podręcznika PostgreSQL-a.
Parametry pathname i mode
są takie same jak dla funkcji fopen()
(domyślną wartością mode jest 'w'),
connection wskazuje identyfikator połączenia które ma być
śledzone. Domyślnie przyjmowane jest ostatnio otwarte.
Funkcja zwraca TRUE jeśli pathname został pomyslnie otwarty
do logowania lub FALSE w przeciwnym wypadku.
Zobacz także fopen() i pg_untrace().
pg_transaction_status
(PHP 5 >= 5.1.0)
pg_transaction_status — Returns the current in-transaction status of the server.
Opis
$connection
)Returns the current in-transaction status of the server.
pg_transaction_status() will give incorrect results when using a PostgreSQL 7.3 server that has the parameter autocommit set to off. The server-side autocommit feature has been deprecated and does not exist in later server versions.
Parametry
-
connection -
PostgreSQL database connection resource.
Zwracane wartości
The status can be PGSQL_TRANSACTION_IDLE (currently idle),
PGSQL_TRANSACTION_ACTIVE (a command is in progress),
PGSQL_TRANSACTION_INTRANS (idle, in a valid transaction block),
or PGSQL_TRANSACTION_INERROR (idle, in a failed transaction block).
PGSQL_TRANSACTION_UNKNOWN is reported if the connection is bad.
PGSQL_TRANSACTION_ACTIVE is reported only when a query
has been sent to the server and not yet completed.
Przykłady
Przykład #1 pg_transaction_status() example
<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");
$stat = pg_transaction_status($dbconn);
if ($stat === PGSQL_TRANSACTION_UNKNOWN) {
echo 'Connection is bad';
} else if ($stat === PGSQL_TRANSACTION_IDLE) {
echo 'Connection is currently idle';
} else {
echo 'Connection is in a transaction state';
}
?>
pg_tty
(PHP 4, PHP 5)
pg_tty — Zwraca nazwę konsoli tty związanej z połączeniem
Opis
$connection
)
pg_tty() zwraca nazwę konsoli tty którą serwer PostgreSQL
wykorzystuje do debugowania połączenia wskazanego przez connection.
pg_unescape_bytea
(PHP 4 >= 4.3.0, PHP 5)
pg_unescape_bytea — Unescape binary for bytea type
Opis
$data
)pg_unescape_bytea() unescapes PostgreSQL bytea data values. It returns the unescaped string, possibly containing binary data.
Informacja:
When you SELECT a bytea type, PostgreSQL returns octal byte values prefixed with '\' (e.g. \032). Users are supposed to convert back to binary format manually.
This function requires PostgreSQL 7.2 or later. With PostgreSQL 7.2.0 and 7.2.1, bytea values must be cast when you enable multi-byte support. i.e. INSERT INTO test_table (image) VALUES ('$image_escaped'::bytea); PostgreSQL 7.2.2 or later does not need a cast. The exception is when the client and backend character encoding does not match, and there may be multi-byte stream error. User must then cast to bytea to avoid this error.
Zwracane wartości
A string containing the unescaped data.
Przykłady
Przykład #1 pg_unescape_bytea() example
<?php
// Connect to the database
$dbconn = pg_connect('dbname=foo');
// Get the bytea data
$res = pg_query("SELECT data FROM gallery WHERE name='Pine trees'");
$raw = pg_fetch_result($res, 'data');
// Convert to binary and send to the browser
header('Content-type: image/jpeg');
echo pg_unescape_bytea($raw);
?>
Zobacz też:
- pg_escape_bytea() - Konwertuje łańcuch wstawiając sekwencje Escape dla typu bytea
- pg_escape_string() - Konwertuje łańcuch wpisywany do pola tekstowego, wstawiając sekwencje Escape
pg_untrace
(PHP 4 >= 4.0.1, PHP 5)
pg_untrace — Wyłącza śledzenie połączeń PostgreSQL-a
Opis
$connection
] )
Wyłącza śledzenie połączeń uruchomione przez pg_trace().
connection wskazuje połączenie które było śledzone,
domyślnie przyjmowane jest ostatnio otwarte.
Zawsze zwraca TRUE.
Zobacz także pg_trace().
pg_update
(PHP 4 >= 4.3.0, PHP 5)
pg_update — Aktualizuje tabelę
Opis
$identyfikator_połączenia
, string $nazwa_tabeli
, array $dane
, array $warunek
[, int $opcje
] )pg_update() aktualizuje wiersze spełniające warunki zawarte w parametrze warunek używając danych z parametru dane. Jeśli jest użyty parametr opcje, jest on przekazywany do wywołania pg_convert() z opcjami w parametrze dane.
Ta funkcja jest w stadium EKSPERYMENTALNYM. Oznacza to, że zachowanie funkcji, jej nazwa, w zasadzie wszystko udokumentowane tutaj może zostać zmienione w przyszłych wersjach PHP bez wcześniejszego uprzedzenia. Używaj tej funkcji na własne ryzyko.
Parametry
-
identyfikator_połączenia -
Identyfikator połączenia do bazy PostgreSQL.
-
nazwa_tabeli -
Nazwa tabeli, w której będą aktualizowane wiersze.
-
dane -
Tablica (ang. array), której klucze są nazwami kolumn w tabeli
nazwa_tabeli, oraz której wartości są nową zawartością pasujących do warunków wierszy. -
warunek -
Tablica (ang. array), której klucze są nazwami kolumn w tabeli
nazwa_tabeli, oraz której wartości są warunkami, jakie muszą spełnić uaktualniane wiersze. -
opcje -
Dowolna kombinacja dowolnej ilości parametrów:
PGSQL_CONV_OPTS,PGSQL_DML_NO_CONV,PGSQL_DML_EXECorazPGSQL_DML_STRING. JeśliPGSQL_DML_STRINGzostał podany w parametrzeopcje, zostanie zwrócony łańcuch zapytania.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu. Zwraca łańcuch (ang. string) gdy PGSQL_DML_STRING został podany
poprzez opcje.
Przykłady
Przykład #1 pg_update() - przykład
<?php
$polaczenie = pg_connect ('dbname=foo');
$dane = array('kolumna1'=>'AA', 'kolumna2'=>'BB');
// To jest bezpieczne, gdyż $_POST jest konwertowane automatycznie
$res = pg_update($polaczenie, 'kopia_post', $_POST, $dane);
if ($res) {
echo "Dane zostały zaktualizowane: $res\n";
} else {
echo "Użytkownik wprowadził błędne dane\n";
}
?>
pg_version
(PHP 5)
pg_version — Returns an array with client, protocol and server version (when available)
Opis
$connection
] )pg_version() returns an array with the client, protocol and server version. Protocol and server versions are only available if PHP was compiled with PostgreSQL 7.4 or later.
For more detailed server information, use pg_parameter_status().
Parametry
-
connection -
PostgreSQL database connection resource. When
connectionis not present, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().
Zwracane wartości
Returns an array with client, protocol
and server keys and values (if available). Returns
FALSE on error or invalid connection.
Przykłady
Przykład #1 pg_version() example
<?php
$dbconn = pg_connect("host=localhost port=5432 dbname=mary")
or die("Could not connect");
$v = pg_version($dbconn);
echo $v['client'];
?>
Powyższy przykład wyświetli:
7.4
Spis treści
- pg_affected_rows — Zwraca liczbę zmodyfikowanych wierszy
- pg_cancel_query — Przerywa zapytanie asynchroniczne
- pg_client_encoding — Zwraca stronę kodową klienta
- pg_close — Zamyka połączenie z PostgreSQL
- pg_connect — Otwiera tymczasowe połączenie do PostgreSQL-a
- pg_connection_busy — Sprawdza czy połączenie jest zajęte czy wolne
- pg_connection_reset — Restartuje połączenie
- pg_connection_status — Zwraca stan połączenia
- pg_convert — Konwertuje tablice asocjacyjne na postać użyteczną w zapytaniu SQL.
- pg_copy_from — Wstawia wiersze do tabeli z tablicy
- pg_copy_to — Kopiuje tabelę do tablicy
- pg_dbname — Podaje nazwę bazy danych
- pg_delete — Usuwa rekordy
- pg_end_copy — Synchronizuje klienta z serwerem PostgreSQL.
- pg_escape_bytea — Konwertuje łańcuch wstawiając sekwencje Escape dla typu bytea
- pg_escape_identifier — Escape a identifier for insertion into a text field
- pg_escape_literal — Escape a literal for insertion into a text field
- pg_escape_string — Konwertuje łańcuch wpisywany do pola tekstowego, wstawiając sekwencje Escape
- pg_execute — Sends a request to execute a prepared statement with given parameters, and waits for the result.
- pg_fetch_all_columns — Fetches all rows in a particular result column as an array
- pg_fetch_all — Fetches all rows from a result as an array
- pg_fetch_array — Pobiera wiersz jako tablicę
- pg_fetch_assoc — Fetch a row as an associative array
- pg_fetch_object — Pobiera wiersz jako obiekt
- pg_fetch_result — Pobiera dane z wyniku
- pg_fetch_row — Pobiera wiersz jako tablicę z indeksami numerycznymi
- pg_field_is_null — Sprawdza czy pole SQL zawiera NULL
- pg_field_name — Zwraca nazwę kolumny
- pg_field_num — Zwraza numer kolumny o podanej nazwie
- pg_field_prtlen — Zwraca drukowalną długość
- pg_field_size — Zwraca wewnętrzny rozmiar kolumny
- pg_field_table — Returns the name or oid of the tables field
- pg_field_type_oid — Returns the type ID (OID) for the corresponding field number
- pg_field_type — Zwraca typ wskazanej kolumny
- pg_free_result — Zwalnia pamięć wyniku
- pg_get_notify — Gets SQL NOTIFY message
- pg_get_pid — Gets the backend's process ID
- pg_get_result — Pobiera wynik zapytania asynchroniczego
- pg_host — Zwraca nazwę komputera związanego z połączeniem
- pg_insert — Wstawia tablicę do tabeli
- pg_last_error — Zwraca łańcuch ostatniego komunikatu błędu dla połączenia
- pg_last_notice — Zwraca komunikaty informacyjne serwera PostgreSQL
- pg_last_oid — Zwraca identyfikator OID ostatniego wiersza
- pg_lo_close — Zamyka wielki obiekt (LO)
- pg_lo_create — Tworzy wielki obiekt (Large Object - LO)
- pg_lo_export — Eksportuje wielki obiekt (Large Object - LO) do pliku
- pg_lo_import — Importuje wielki obiekt (Large Object - LO) z pliku
- pg_lo_open — Otwiera wielki obiekt (Large Object - LO)
- pg_lo_read_all — Odczytuje wielki obiekt (Large Object - LO) i wysła go do przeglądarki
- pg_lo_read — Odczytuje wielki obiekt (Large Object - LO)
- pg_lo_seek — Przemieszcza wskaźnik położenia w wielkim obiekcie (Large Object - LO)
- pg_lo_tell — Zwraca wskaźnik położenia w wielkim obiekcie (Large Object - LO)
- pg_lo_unlink — Usuwa wielki obiekt (Large Object - LO)
- pg_lo_write — Zapisuje do wielkiego obiektu (Large Object - LO)
- pg_meta_data — Pobiera informacje o tabeli
- pg_num_fields — Zwraca liczbę kolumn
- pg_num_rows — Zwraca liczbę wierszy
- pg_options — Podaje opcje powiązane z połączenim
- pg_parameter_status — Looks up a current parameter setting of the server.
- pg_pconnect — Otwiera trwałe połączenie z serwerem PostgreSQL
- pg_ping — Ping database connection
- pg_port — Zwraca numer portu związany z połączeniem
- pg_prepare — Submits a request to create a prepared statement with the given parameters, and waits for completion.
- pg_put_line — Wysyła łańcuch zakończony znakiem NULL do serwera PostgreSQL
- pg_query_params — Submits a command to the server and waits for the result, with the ability to pass parameters separately from the SQL command text.
- pg_query — Realizujezapytanie do bazy danych
- pg_result_error_field — Returns an individual field of an error report.
- pg_result_error — Zwraca błąd związany z identyfikatorem wyniku
- pg_result_seek — Set internal row offset in result resource
- pg_result_status — Zwraca stan wyniku zapytania
- pg_select — Wybiera wiersze
- pg_send_execute — Sends a request to execute a prepared statement with given parameters, without waiting for the result(s).
- pg_send_prepare — Sends a request to create a prepared statement with the given parameters, without waiting for completion.
- pg_send_query_params — Submits a command and separate parameters to the server without waiting for the result(s).
- pg_send_query — Wysyła zapytanie asynchroniczne
- pg_set_client_encoding — Ustawia stronę kodową klienta PostgreSQL-a
- pg_set_error_verbosity — Determines the verbosity of messages returned by pg_last_error and pg_result_error.
- pg_trace — Uruchamia śledzenie połączeń z PostgreSQL
- pg_transaction_status — Returns the current in-transaction status of the server.
- pg_tty — Zwraca nazwę konsoli tty związanej z połączeniem
- pg_unescape_bytea — Unescape binary for bytea type
- pg_untrace — Wyłącza śledzenie połączeń PostgreSQL-a
- pg_update — Aktualizuje tabelę
- pg_version — Returns an array with client, protocol and server version (when available)
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Przykłady
- Funkcje PostgreSQL
- pg_affected_rows — Zwraca liczbę zmodyfikowanych wierszy
- pg_cancel_query — Przerywa zapytanie asynchroniczne
- pg_client_encoding — Zwraca stronę kodową klienta
- pg_close — Zamyka połączenie z PostgreSQL
- pg_connect — Otwiera tymczasowe połączenie do PostgreSQL-a
- pg_connection_busy — Sprawdza czy połączenie jest zajęte czy wolne
- pg_connection_reset — Restartuje połączenie
- pg_connection_status — Zwraca stan połączenia
- pg_convert — Konwertuje tablice asocjacyjne na postać użyteczną w zapytaniu SQL.
- pg_copy_from — Wstawia wiersze do tabeli z tablicy
- pg_copy_to — Kopiuje tabelę do tablicy
- pg_dbname — Podaje nazwę bazy danych
- pg_delete — Usuwa rekordy
- pg_end_copy — Synchronizuje klienta z serwerem PostgreSQL.
- pg_escape_bytea — Konwertuje łańcuch wstawiając sekwencje Escape dla typu bytea
- pg_escape_identifier — Escape a identifier for insertion into a text field
- pg_escape_literal — Escape a literal for insertion into a text field
- pg_escape_string — Konwertuje łańcuch wpisywany do pola tekstowego, wstawiając sekwencje Escape
- pg_execute — Sends a request to execute a prepared statement with given parameters, and waits for the result.
- pg_fetch_all_columns — Fetches all rows in a particular result column as an array
- pg_fetch_all — Fetches all rows from a result as an array
- pg_fetch_array — Pobiera wiersz jako tablicę
- pg_fetch_assoc — Fetch a row as an associative array
- pg_fetch_object — Pobiera wiersz jako obiekt
- pg_fetch_result — Pobiera dane z wyniku
- pg_fetch_row — Pobiera wiersz jako tablicę z indeksami numerycznymi
- pg_field_is_null — Sprawdza czy pole SQL zawiera NULL
- pg_field_name — Zwraca nazwę kolumny
- pg_field_num — Zwraza numer kolumny o podanej nazwie
- pg_field_prtlen — Zwraca drukowalną długość
- pg_field_size — Zwraca wewnętrzny rozmiar kolumny
- pg_field_table — Returns the name or oid of the tables field
- pg_field_type_oid — Returns the type ID (OID) for the corresponding field number
- pg_field_type — Zwraca typ wskazanej kolumny
- pg_free_result — Zwalnia pamięć wyniku
- pg_get_notify — Gets SQL NOTIFY message
- pg_get_pid — Gets the backend's process ID
- pg_get_result — Pobiera wynik zapytania asynchroniczego
- pg_host — Zwraca nazwę komputera związanego z połączeniem
- pg_insert — Wstawia tablicę do tabeli
- pg_last_error — Zwraca łańcuch ostatniego komunikatu błędu dla połączenia
- pg_last_notice — Zwraca komunikaty informacyjne serwera PostgreSQL
- pg_last_oid — Zwraca identyfikator OID ostatniego wiersza
- pg_lo_close — Zamyka wielki obiekt (LO)
- pg_lo_create — Tworzy wielki obiekt (Large Object - LO)
- pg_lo_export — Eksportuje wielki obiekt (Large Object - LO) do pliku
- pg_lo_import — Importuje wielki obiekt (Large Object - LO) z pliku
- pg_lo_open — Otwiera wielki obiekt (Large Object - LO)
- pg_lo_read_all — Odczytuje wielki obiekt (Large Object - LO) i wysła go do przeglądarki
- pg_lo_read — Odczytuje wielki obiekt (Large Object - LO)
- pg_lo_seek — Przemieszcza wskaźnik położenia w wielkim obiekcie (Large Object - LO)
- pg_lo_tell — Zwraca wskaźnik położenia w wielkim obiekcie (Large Object - LO)
- pg_lo_unlink — Usuwa wielki obiekt (Large Object - LO)
- pg_lo_write — Zapisuje do wielkiego obiektu (Large Object - LO)
- pg_meta_data — Pobiera informacje o tabeli
- pg_num_fields — Zwraca liczbę kolumn
- pg_num_rows — Zwraca liczbę wierszy
- pg_options — Podaje opcje powiązane z połączenim
- pg_parameter_status — Looks up a current parameter setting of the server.
- pg_pconnect — Otwiera trwałe połączenie z serwerem PostgreSQL
- pg_ping — Ping database connection
- pg_port — Zwraca numer portu związany z połączeniem
- pg_prepare — Submits a request to create a prepared statement with the given parameters, and waits for completion.
- pg_put_line — Wysyła łańcuch zakończony znakiem NULL do serwera PostgreSQL
- pg_query_params — Submits a command to the server and waits for the result, with the ability to pass parameters separately from the SQL command text.
- pg_query — Realizujezapytanie do bazy danych
- pg_result_error_field — Returns an individual field of an error report.
- pg_result_error — Zwraca błąd związany z identyfikatorem wyniku
- pg_result_seek — Set internal row offset in result resource
- pg_result_status — Zwraca stan wyniku zapytania
- pg_select — Wybiera wiersze
- pg_send_execute — Sends a request to execute a prepared statement with given parameters, without waiting for the result(s).
- pg_send_prepare — Sends a request to create a prepared statement with the given parameters, without waiting for completion.
- pg_send_query_params — Submits a command and separate parameters to the server without waiting for the result(s).
- pg_send_query — Wysyła zapytanie asynchroniczne
- pg_set_client_encoding — Ustawia stronę kodową klienta PostgreSQL-a
- pg_set_error_verbosity — Determines the verbosity of messages returned by pg_last_error and pg_result_error.
- pg_trace — Uruchamia śledzenie połączeń z PostgreSQL
- pg_transaction_status — Returns the current in-transaction status of the server.
- pg_tty — Zwraca nazwę konsoli tty związanej z połączeniem
- pg_unescape_bytea — Unescape binary for bytea type
- pg_untrace — Wyłącza śledzenie połączeń PostgreSQL-a
- pg_update — Aktualizuje tabelę
- pg_version — Returns an array with client, protocol and server version (when available)
SQLite
Wstęp
This is an extension for the SQLite Embeddable SQL Database Engine. SQLite is a C library that implements an embeddable SQL database engine. Programs that link with the SQLite library can have SQL database access without running a separate RDBMS process.
SQLite is not a client library used to connect to a big database server. SQLite is the server. The SQLite library reads and writes directly to and from the database files on disk.
Informacja:
For further information see the SQLite Website (» http://sqlite.org/).
Instalacja/Konfiguracja
Spis treści
Wymagania
The SQLite extension is enabled by default as of PHP 5.0. Beginning with PHP 5.4, the SQLite extension is available only via PECL.
Instalacja
Since PHP 5.0 this extension was bundled with PHP. Beginning with PHP 5.4, this extension is available only via PECL.
Windows users must enable php_sqlite.dll inside of php.ini in order to use these functions. DLL z tym rozszerzeniem PECL można pobrać zarówno ze strony » PHP Downloads lub z » http://pecl4win.php.net/
Windows builds must also enable PDO because as of PHP 5.1.0 it depends on it. So, php.ini will end up with something like this:
extension=php_pdo.dll extension=php_sqlite.dll
The PHP 5.0.x series of Windows builds enabled this extension by default, where no DLL file is necessary.
SQLite 3 is supported through PDO SQLite.
Informacja: Windows installation for unprivileged accounts
On Windows operating systems, unprivileged accounts don't have the TMP environment variable set by default. This will make sqlite create temporary files in the windows directory, which is not desirable. So, you should set the TMP environment variable for the web server or the user account the web server is running under. If Apache is your web server, you can accomplish this via a SetEnv directive in your httpd.conf file. For example:
If you are unable to establish this setting at the server level, you can implement the setting in your script:SetEnv TMP c:/tempThe setting must refer to a directory that the web server has permission to create files in and subsequently write to and delete the files it created. Otherwise, you may receive the following error message: malformed database schema - unable to open a temporary database file for storing temporary tables<?php
putenv('TMP=C:/temp');
?>
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Changelog |
|---|---|---|---|
| sqlite.assoc_case | "0" | PHP_INI_ALL | Available since PHP 5.0.0. |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
sqlite.assoc_caseint -
Whether to use mixed case (0), upper case (1) or lower case (2) hash indexes.
This option is primarily useful when you need compatibility with other database systems, where the names of the columns are always returned as uppercase or lowercase, regardless of the case of the actual field names in the database schema.
The SQLite library returns the column names in their natural case (that matches the case you used in your schema). When
sqlite.assoc_caseis set to 0 the natural case will be preserved. When it is set to 1 or 2, PHP will apply case folding on the hash keys to upper- or lower-case the keys, respectively.Use of this option incurs a slight performance penalty, but is MUCH faster than performing the case folding yourself using PHP script.
Typy zasobów
There are two resources used in the SQLite Interface. The first one is the database connection, the second one the result set.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
The functions sqlite_fetch_array() and sqlite_current() use a constant for the different types of result arrays. The following constants are defined:
-
SQLite result type constants
-
SQLITE_ASSOC(int) - Columns are returned into the array having the field name as the array index.
-
SQLITE_BOTH(int) - Columns are returned into the array having both a numerical index and the field name as the array index.
-
SQLITE_NUM(int) - Columns are returned into the array having a numerical index to the fields. This index starts with 0, the first field in the result.
A number of functions may return status codes. The following constants are defined:
-
SQLite status code constants
-
SQLITE_OK(int) - Successful result.
-
SQLITE_ERROR(int) - SQL error or missing database.
-
SQLITE_INTERNAL(int) - An internal logic error in SQLite.
-
SQLITE_PERM(int) - Access permission denied.
-
SQLITE_ABORT(int) - Callback routine requested an abort.
-
SQLITE_BUSY(int) - The database file is locked.
-
SQLITE_LOCKED(int) - A table in the database is locked.
-
SQLITE_NOMEM(int) - Memory allocation failed.
-
SQLITE_READONLY(int) - Attempt to write a readonly database.
-
SQLITE_INTERRUPT(int) - Operation terminated internally.
-
SQLITE_IOERR(int) - Disk I/O error occurred.
-
SQLITE_NOTADB(int) - File opened that is not a database file.
-
SQLITE_CORRUPT(int) - The database disk image is malformed.
-
SQLITE_FORMAT(int) - Auxiliary database format error.
-
SQLITE_NOTFOUND(int) - (Internal) Table or record not found.
-
SQLITE_FULL(int) - Insertion failed because database is full.
-
SQLITE_CANTOPEN(int) - Unable to open the database file.
-
SQLITE_PROTOCOL(int) - Database lock protocol error.
-
SQLITE_EMPTY(int) - (Internal) Database table is empty.
-
SQLITE_SCHEMA(int) - The database schema changed.
-
SQLITE_TOOBIG(int) - Too much data for one row of a table.
-
SQLITE_CONSTRAINT(int) - Abort due to constraint violation.
-
SQLITE_MISMATCH(int) - Data type mismatch.
-
SQLITE_MISUSE(int) - Library used incorrectly.
-
SQLITE_NOLFS(int) - Uses of OS features not supported on host.
-
SQLITE_AUTH(int) - Authorized failed.
-
SQLITE_ROW(int) - Internal process has another row ready.
-
SQLITE_DONE(int) - Internal process has finished executing.
SQLite Funkcje
Klasy predefiniowane
SQLiteDatabase
Represents an opened SQLite database.
Konstruktor
- __construct - construct a new SQLiteDatabase object
Metody
- query - Execute a query
- queryExec - Execute a result-less query
- arrayQuery - Execute a query and return the result as an array
- singleQuery - Execute a query and return either an array for one single column or the value of the first row
- unbufferedQuery - Execute an unbuffered query
- lastInsertRowid - Returns the rowid of the most recently inserted row
- changes - Returns the number of rows changed by the most recent statement
- createAggregate - Register an aggregating UDF for use in SQL statements
- createFunction - Register a UDF for use in SQL statements
- busyTimeout - Sets or disables busy timeout duration
- lastError - Returns the last error code of the most recently encountered error
- fetchColumnTypes - Return an array of column types from a particular table
SQLiteResult
Represents a buffered SQLite result set.
Metody
- fetch - Fetches the next row from the result set as an array
- fetchObject - Fetches the next row from the result set as an object
- fetchSingle - Fetches the first column from the result set as a string
- fetchAll - Fetches all rows from the result set as an array of arrays
- column - Fetches a column from the current row of the result set
- numFields - Returns the number of fields in the result set
- fieldName - Returns the name of a particular field in the result set
- current - Fetches the current row from the result set as an array
- key - Return the current row index
- next - Seek to the next row number
- valid - Returns whether more rows are available
- rewind - Seek to the first row number of the result set
- prev - Seek to the previous row number of the result set
- hasPrev - Returns whether or not a previous row is available
- numRows - Returns the number of rows in the result set
- seek - Seek to a particular row number
SQLiteUnbuffered
Represents an unbuffered SQLite result set. Unbuffered results sets are sequential, forward-seeking only.
Metody
- fetch - Fetches the next row from the result set as an array
- fetchObject - Fetches the next row from the result set as an object
- fetchSingle - Fetches the first column from the result set as a string
- fetchAll - Fetches all rows from the result set as an array of arrays
- column - Fetches a column from the current row of the result set
- numFields - Returns the number of fields in the result set
- fieldName - Returns the name of a particular field in the result set
- current - Fetches the current row from the result set as an array
- next - Seek to the next row number
- valid - Returns whether more rows are available
sqlite_array_query
SQLiteDatabase::arrayQuery
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_array_query -- SQLiteDatabase::arrayQuery — Execute a query against a given database and returns an array
Opis
$dbhandle
, string $query
[, int $result_type = SQLITE_BOTH
[, bool $decode_binary = true
]] )$query
, resource $dbhandle
[, int $result_type = SQLITE_BOTH
[, bool $decode_binary = true
]] )Styl obiektowy (method):
$query
[, int $result_type = SQLITE_BOTH
[, bool $decode_binary = true
]] )sqlite_array_query() executes the given query and returns an array of the entire result set. It is similar to calling sqlite_query() and then sqlite_fetch_array() for each row in the result set. sqlite_array_query() is significantly faster than the aforementioned.
sqlite_array_query() is best suited to queries returning 45 rows or less. If you have more data than that, it is recommended that you write your scripts to use sqlite_unbuffered_query() instead for more optimal performance.
Parametry
-
query -
The query to be executed.
Data inside the query should be properly escaped.
-
dbhandle -
The SQLite Database resource; returned from sqlite_open() when used procedurally. This parameter is not required when using the object-oriented method.
-
result_type -
Opcjonalny parametr
result_typeprzyjmuje wartości stałych i określa jak indeksowane będą zwracane wartości. UżywającSQLITE_ASSOCzwrócone zostaną tylko indeksy asocjacyjne (nazwy pól), podczas gdySQLITE_NUMzwróci tylko indeksy numeryczne (numery pól).SQLITE_BOTHzwróci i indeksy asocjacyjne i numeryczne.SQLITE_BOTHjest domyślną wartością dla tej funkcji. -
decode_binary -
Gdy parametr
decode_binaryzostanie ustawiony naTRUE(domyślnie), PHP zdekoduje kodowanie binarne, któremu zostały poddane dane, jeśli były kodowane przy użyciu funkcji sqlite_escape_string(). Zazwyczaj należy pozostawić domyślną wartość tego parametru, chyba że baza jest współużytkowana przez różne aplikacje.
Informacja: Obsługiwane są dwie alternatywne składnie, dla zachowania kompatybilności z rozszerzeniami dla innych baz danych (takich jak MySQL). Preferowana jest pierwsza, gdzie
dbhandlejest pierwszym parametrem funkcji.
Zwracane wartości
Returns an array of the entire result set; FALSE otherwise.
Wielkość liter w nazwach kolumn zwróconych przez
SQLITE_ASSOC i SQLITE_BOTH zostaną
przetworzone zależnie od ustawienia opcji konfiguracji
sqlite.assoc_case.
Przykłady
Przykład #1 Styl proceduralny
<?php
$dbhandle = sqlite_open('sqlitedb');
$result = sqlite_array_query($dbhandle, 'SELECT name, email FROM users LIMIT 25', SQLITE_ASSOC);
foreach ($result as $entry) {
echo 'Name: ' . $entry['name'] . ' E-mail: ' . $entry['email'];
}
?>
Przykład #2 Object-oriented style
<?php
$dbhandle = new SQLiteDatabase('sqlitedb');
$result = $dbhandle->arrayQuery('SELECT name, email FROM users LIMIT 25', SQLITE_ASSOC);
foreach ($result as $entry) {
echo 'Name: ' . $entry['name'] . ' E-mail: ' . $entry['email'];
}
?>
Zobacz też:
- sqlite_query() - Executes a query against a given database and returns a result handle
- sqlite_fetch_array() - Fetches the next row from a result set as an array
- sqlite_fetch_string() - Alias dla sqlite_fetch_single
sqlite_busy_timeout
SQLiteDatabase::busyTimeout
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_busy_timeout -- SQLiteDatabase::busyTimeout — Set busy timeout duration, or disable busy handlers
Opis
$dbhandle
, int $milliseconds
)Styl obiektowy (method):
$milliseconds
)
Set the maximum time, in milliseconds, that SQLite will wait for a
dbhandle to become ready for use.
Parametry
-
dbhandle -
The SQLite Database resource; returned from sqlite_open() when used procedurally. This parameter is not required when using the object-oriented method.
-
milliseconds -
The number of milliseconds. When set to 0, busy handlers will be disabled and SQLite will return immediately with a SQLITE_BUSY status code if another process/thread has the database locked for an update.
PHP sets the default busy timeout to be 60 seconds when the database is opened.
Informacja:
There are one thousand (1000) milliseconds in one second.
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 Styl proceduralny
<?php
$dbhandle = sqlite_open('sqlitedb');
sqlite_busy_timeout($dbhandle, 10000); // set timeout to 10 seconds
sqlite_busy_timeout($dbhandle, 0); // disable busy handler
?>
Przykład #2 Styl obiektowy
<?php
$dbhandle = new SQLiteDatabase('sqlitedb');
$dbhandle->busyTimeout(10000); // 10 seconds
$dbhandle->busyTimeout(0); // disable
?>
sqlite_changes
SQLiteDatabase::changes
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_changes -- SQLiteDatabase::changes — Returns the number of rows that were changed by the most recent SQL statement
Opis
$dbhandle
)Styl obiektowy (method):
Returns the numbers of rows that were changed by the most recent SQL
statement executed against the dbhandle database
handle.
Parametry
-
dbhandle -
The SQLite Database resource; returned from sqlite_open() when used procedurally. This parameter is not required when using the object-oriented method.
Zwracane wartości
Returns the number of changed rows.
Przykłady
Przykład #1 Styl proceduralny
<?php
$dbhandle = sqlite_open('mysqlitedb');
$query = sqlite_query($dbhandle, "UPDATE users SET email='jDoe@example.com' WHERE username='jDoe'");
if (!$query) {
exit('Error in query.');
} else {
echo 'Number of rows modified: ', sqlite_changes($dbhandle);
}
?>
Przykład #2 Styl obiektowy
<?php
$dbhandle = new SQLiteDatabase('mysqlitedb');
$query = $dbhandle->query("UPDATE users SET email='jDoe@example.com' WHERE username='jDoe'");
if (!$query) {
exit('Error in query.');
} else {
echo 'Number of rows modified: ', $dbhandle->changes();
}
?>
sqlite_close
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_close — Closes an open SQLite database
Opis
$dbhandle
)
Closes the given db_handle database handle.
If the database was persistent, it will be closed and removed from the
persistent list.
Parametry
-
dbhandle -
The SQLite Database resource; returned from sqlite_open() when used procedurally.
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 sqlite_close() example
<?php
$dbhandle = sqlite_open('sqlitedb');
sqlite_close($dbhandle);
?>
Zobacz też:
- sqlite_open() - Opens an SQLite database and create the database if it does not exist
- sqlite_popen() - Opens a persistent handle to an SQLite database and create the database if it does not exist
sqlite_column
SQLiteResult::column
SQLiteUnbuffered::column
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_column -- SQLiteResult::column -- SQLiteUnbuffered::column — Fetches a column from the current row of a result set
Opis
Fetches the value of a column named index_or_name
(if it is a string), or of the ordinal column numbered
index_or_name (if it is an integer) from the
current row of the query result handle result.
Parametry
-
result -
The SQLite result resource. This parameter is not required when using the object-oriented method.
-
index_or_name -
The column index or name to fetch.
-
decode_binary -
Gdy parametr
decode_binaryzostanie ustawiony naTRUE(domyślnie), PHP zdekoduje kodowanie binarne, któremu zostały poddane dane, jeśli były kodowane przy użyciu funkcji sqlite_escape_string(). Zazwyczaj należy pozostawić domyślną wartość tego parametru, chyba że baza jest współużytkowana przez różne aplikacje.
Zwracane wartości
Returns the column value.
Notatki
Informacja:
Use this function when you are iterating a large result set with many columns, or with columns that contain large amounts of data.
sqlite_create_aggregate
SQLiteDatabase::createAggregate
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_create_aggregate -- SQLiteDatabase::createAggregate — Register an aggregating UDF for use in SQL statements
Opis
$dbhandle
, string $function_name
, callable $step_func
, callable $finalize_func
[, int $num_args = -1
] )Styl obiektowy (method):
$function_name
, callable $step_func
, callable $finalize_func
[, int $num_args = -1
] )sqlite_create_aggregate() is similar to sqlite_create_function() except that it registers functions that can be used to calculate a result aggregated across all the rows of a query.
The key difference between this function and
sqlite_create_function() is that two functions are
required to manage the aggregate; step_func is
called for each row of the result set. Your PHP function should
accumulate the result and store it into the aggregation context.
Once all the rows have been processed,
finalize_func will be called and it should then
take the data from the aggregation context and return the result.
Callback functions should return a type understood by SQLite (i.e.
scalar type).
Parametry
-
dbhandle -
The SQLite Database resource; returned from sqlite_open() when used procedurally. This parameter is not required when using the object-oriented method.
-
function_name -
The name of the function used in SQL statements.
-
step_func -
Callback function called for each row of the result set. Function parameters are &$context, $value, ....
-
finalize_func -
Callback function to aggregate the "stepped" data from each row. Function parameter is &$context and the function should return the final result of aggregation.
-
num_args -
Hint to the SQLite parser if the callback function accepts a predetermined number of arguments.
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 max_length aggregation function example
<?php
$data = array(
'one',
'two',
'three',
'four',
'five',
'six',
'seven',
'eight',
'nine',
'ten',
);
$dbhandle = sqlite_open(':memory:');
sqlite_query($dbhandle, "CREATE TABLE strings(a)");
foreach ($data as $str) {
$str = sqlite_escape_string($str);
sqlite_query($dbhandle, "INSERT INTO strings VALUES ('$str')");
}
function max_len_step(&$context, $string)
{
if (strlen($string) > $context) {
$context = strlen($string);
}
}
function max_len_finalize(&$context)
{
return $context;
}
sqlite_create_aggregate($dbhandle, 'max_len', 'max_len_step', 'max_len_finalize');
var_dump(sqlite_array_query($dbhandle, 'SELECT max_len(a) from strings'));
?>
In this example, we are creating an aggregating function that will
calculate the length of the longest string in one of the columns of the
table. For each row, the max_len_step function is
called and passed a context parameter. The context
parameter is just like any other PHP variable and be set to hold an array
or even an object value. In this example, we are simply using it to hold
the maximum length we have seen so far; if the
string has a length longer than the current
maximum, we update the context to hold this new maximum length.
After all of the rows have been processed, SQLite calls the
max_len_finalize function to determine the aggregate
result. Here, we could perform some kind of calculation based on the
data found in the context. In our simple example
though, we have been calculating the result as the query progressed, so we
simply need to return the context value.
Informacja:
The example above will not work correctly if the column contains binary data. Take a look at the manual page for sqlite_udf_decode_binary() for an explanation of why this is so, and an example of how to make it respect the binary encoding.
It is NOT recommended for you to store a copy of the values in the context and then process them at the end, as you would cause SQLite to use a lot of memory to process the query - just think of how much memory you would need if a million rows were stored in memory, each containing a string 32 bytes in length.
You can use sqlite_create_function() and sqlite_create_aggregate() to override SQLite native SQL functions.
Zobacz też:
- sqlite_create_function() - Registers a "regular" User Defined Function for use in SQL statements
- sqlite_udf_encode_binary() - Encode binary data before returning it from an UDF
- sqlite_udf_decode_binary() - Decode binary data passed as parameters to an UDF
sqlite_create_function
SQLiteDatabase::createFunction
(PHP 5 < 5.4.0, sqlite >= 1.0.0)
sqlite_create_function -- SQLiteDatabase::createFunction — Registers a "regular" User Defined Function for use in SQL statements
Opis
$dbhandle
, string $function_name
, callable $callback
[, int $num_args = -1
] )Styl obiektowy (method):
$function_name
, callable $callback
[, int $num_args = -1
] )sqlite_create_function() allows you to register a PHP function with SQLite as an UDF (User Defined Function), so that it can be called from within your SQL statements.
The UDF can be used in any SQL statement that can call functions, such as SELECT and UPDATE statements and also in triggers.
Parametry
-
dbhandle -
The SQLite Database resource; returned from sqlite_open() when used procedurally. This parameter is not required when using the object-oriented method.
-
function_name -
The name of the function used in SQL statements.
-
callback -
Callback function to handle the defined SQL function.
Informacja: Callback functions should return a type understood by SQLite (i.e. scalar type).
-
num_args -
Hint to the SQLite parser if the callback function accepts a predetermined number of arguments.
Informacja: Obsługiwane są dwie alternatywne składnie, dla zachowania kompatybilności z rozszerzeniami dla innych baz danych (takich jak MySQL). Preferowana jest pierwsza, gdzie
dbhandlejest pierwszym parametrem funkcji.
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 sqlite_create_function() example
<?php
function md5_and_reverse($string)
{
return strrev(md5($string));
}
if ($dbhandle = sqlite_open('mysqlitedb', 0666, $sqliteerror)) {
sqlite_create_function($dbhandle, 'md5rev', 'md5_and_reverse', 1);
$sql = 'SELECT md5rev(filename) FROM files';
$rows = sqlite_array_query($dbhandle, $sql);
} else {
echo 'Error opening sqlite db: ' . $sqliteerror;
exit;
}
?>
In this example, we have a function that calculates the md5 sum of a
string, and then reverses it. When the SQL statement executes, it
returns the value of the filename transformed by our function. The data
returned in $rows contains the processed result.
The beauty of this technique is that you do not need to process the result using a foreach loop after you have queried for the data.
PHP registers a special function named php when the database is first opened. The php function can be used to call any PHP function without having to register it first.
Przykład #2 Example of using the PHP function
<?php
$rows = sqlite_array_query($dbhandle, "SELECT php('md5', filename) from files");
?>
This example will call the md5() on each
filename column in the database and return the result
into $rows
Informacja:
For performance reasons, PHP will not automatically encode/decode binary data passed to and from your UDF's. You need to manually encode/decode the parameters and return values if you need to process binary data in this way. Take a look at sqlite_udf_encode_binary() and sqlite_udf_decode_binary() for more details.
It is not recommended to use UDF's to handle processing of binary data, unless high performance is not a key requirement of your application.
You can use sqlite_create_function() and sqlite_create_aggregate() to override SQLite native SQL functions.
sqlite_current
SQLiteResult::current
SQLiteUnbuffered::current
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_current -- SQLiteResult::current -- SQLiteUnbuffered::current — Fetches the current row from a result set as an array
Opis
$result
[, int $result_type = SQLITE_BOTH
[, bool $decode_binary = true
]] )Styl obiektowy (method):
$result_type = SQLITE_BOTH
[, bool $decode_binary = true
]] )$result_type = SQLITE_BOTH
[, bool $decode_binary = true
]] )sqlite_current() is identical to sqlite_fetch_array() except that it does not advance to the next row prior to returning the data; it returns the data from the current position only.
Parametry
-
result -
The SQLite result resource. This parameter is not required when using the object-oriented method.
-
result_type -
Opcjonalny parametr
result_typeprzyjmuje wartości stałych i określa jak indeksowane będą zwracane wartości. UżywającSQLITE_ASSOCzwrócone zostaną tylko indeksy asocjacyjne (nazwy pól), podczas gdySQLITE_NUMzwróci tylko indeksy numeryczne (numery pól).SQLITE_BOTHzwróci i indeksy asocjacyjne i numeryczne.SQLITE_BOTHjest domyślną wartością dla tej funkcji. -
decode_binary -
Gdy parametr
decode_binaryzostanie ustawiony naTRUE(domyślnie), PHP zdekoduje kodowanie binarne, któremu zostały poddane dane, jeśli były kodowane przy użyciu funkcji sqlite_escape_string(). Zazwyczaj należy pozostawić domyślną wartość tego parametru, chyba że baza jest współużytkowana przez różne aplikacje.
Zwracane wartości
Returns an array of the current row from a result set; FALSE if the
current position is beyond the final row.
Wielkość liter w nazwach kolumn zwróconych przez
SQLITE_ASSOC i SQLITE_BOTH zostaną
przetworzone zależnie od ustawienia opcji konfiguracji
sqlite.assoc_case.
Zobacz też:
- sqlite_seek() - Seek to a particular row number of a buffered result set
- sqlite_next() - Seek to the next row number
- sqlite_fetch_array() - Fetches the next row from a result set as an array
sqlite_error_string
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_error_string — Returns the textual description of an error code
Opis
$error_code
)
Returns a human readable description of the
error_code returned from
sqlite_last_error().
Zwracane wartości
Returns a human readable description of the error_code,
as a string.
sqlite_escape_string
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_escape_string — Escapes a string for use as a query parameter
Opis
$item
)
sqlite_escape_string() will correctly quote the string
specified by item
for use in an SQLite SQL statement. This includes doubling up
single-quote characters (') and checking for
binary-unsafe characters in the query string.
Although the encoding makes it safe to insert the data, it will render simple text comparisons and LIKE clauses in your queries unusable for the columns that contain the binary data. In practice, this shouldn't be a problem, as your schema should be such that you don't use such things on binary columns (in fact, it might be better to store binary data using other means, such as in files).
Parametry
-
item -
The string being quoted.
If the
itemcontains a NUL character, or if it begins with a character whose ordinal value is 0x01, PHP will apply a binary encoding scheme so that you can safely store and retrieve binary data.
Zwracane wartości
Returns an escaped string for use in an SQLite SQL statement.
Notatki
Informacja: Do not use this function to encode the return values from UDF's created using sqlite_create_function() or sqlite_create_aggregate() - use sqlite_udf_encode_binary() instead.
addslashes() should NOT be used to quote your strings for SQLite queries; it will lead to strange results when retrieving your data.
sqlite_exec
SQLiteDatabase::exec
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.3)
sqlite_exec -- SQLiteDatabase::exec — Executes a result-less query against a given database
Opis
$dbhandle
, string $query
[, string &$error_msg
] )$query
, resource $dbhandle
)Styl obiektowy (method):
$query
[, string &$error_msg
] )
Executes an SQL statement given by the query against
a given database handle (specified by the dbhandle
parameter).
SQLite will execute multiple queries separated by semicolons, so you can use it to execute a batch of SQL that you have loaded from a file or have embedded in a script.
Parametry
-
dbhandle -
The SQLite Database resource; returned from sqlite_open() when used procedurally. This parameter is not required when using the object-oriented method.
-
query -
The query to be executed.
Data inside the query should be properly escaped.
-
error_msg -
The specified variable will be filled if an error occurs. This is specially important because SQL syntax errors can't be fetched using the sqlite_last_error() function.
Informacja: Obsługiwane są dwie alternatywne składnie, dla zachowania kompatybilności z rozszerzeniami dla innych baz danych (takich jak MySQL). Preferowana jest pierwsza, gdzie
dbhandlejest pierwszym parametrem funkcji.
Zwracane wartości
This function will return a boolean result; TRUE for success or FALSE for failure.
If you need to run a query that returns rows, see sqlite_query().
Wielkość liter w nazwach kolumn zwróconych przez
SQLITE_ASSOC i SQLITE_BOTH zostaną
przetworzone zależnie od ustawienia opcji konfiguracji
sqlite.assoc_case.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.1.0 |
Added the error_msg parameter
|
Przykłady
Przykład #1 Procedural example
<?php
$dbhandle = sqlite_open('mysqlitedb');
$query = sqlite_exec($dbhandle, "UPDATE users SET email='jDoe@example.com' WHERE username='jDoe'", $error);
if (!$query) {
exit("Error in query: '$error'");
} else {
echo 'Number of rows modified: ', sqlite_changes($dbhandle);
}
?>
Przykład #2 Object-oriented example
<?php
$dbhandle = new SQLiteDatabase('mysqlitedb');
$query = $dbhandle->queryExec("UPDATE users SET email='jDoe@example.com' WHERE username='jDoe'", $error);
if (!$query) {
exit("Error in query: '$error'");
} else {
echo 'Number of rows modified: ', $dbhandle->changes();
}
?>
Zobacz też:
- sqlite_query() - Executes a query against a given database and returns a result handle
- sqlite_unbuffered_query() - Execute a query that does not prefetch and buffer all data
- sqlite_array_query() - Execute a query against a given database and returns an array
sqlite_factory
(PHP 5 < 5.4.0)
sqlite_factory — Opens an SQLite database and returns an SQLiteDatabase object
Opis
$filename
[, int $mode = 0666
[, string &$error_message
]] )sqlite_factory() behaves similarly to sqlite_open() in that it opens an SQLite database or attempts to create it if it does not exist. However, a SQLiteDatabase object is returned rather than a resource. Please see the sqlite_open() reference page for further usage and caveats.
Parametry
-
filename -
The filename of the SQLite database.
-
mode -
The mode of the file. Intended to be used to open the database in read-only mode. Presently, this parameter is ignored by the sqlite library. The default value for mode is the octal value 0666 and this is the recommended value.
-
error_message -
Passed by reference and is set to hold a descriptive error message explaining why the database could not be opened if there was an error.
Zwracane wartości
Returns an SQLiteDatabase object on success, NULL on error.
Przykłady
Przykład #1 sqlite_factory() example
<?php
$dbhandle = sqlite_factory('sqlitedb');
$dbhandle->query('SELECT user_id, username FROM users');
/* functionally equivalent to: */
$dbhandle = new SQLiteDatabase('sqlitedb');
$dbhandle->query('SELECT user_id, username FROM users');
?>
Zobacz też:
- sqlite_open() - Opens an SQLite database and create the database if it does not exist
- sqlite_popen() - Opens a persistent handle to an SQLite database and create the database if it does not exist
sqlite_fetch_all
SQLiteResult::fetchAll
SQLiteUnbuffered::fetchAll
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_fetch_all -- SQLiteResult::fetchAll -- SQLiteUnbuffered::fetchAll — Fetches all rows from a result set as an array of arrays
Opis
$result
[, int $result_type = SQLITE_BOTH
[, bool $decode_binary = true
]] )Styl obiektowy (method):
$result_type = SQLITE_BOTH
[, bool $decode_binary = true
]] )$result_type = SQLITE_BOTH
[, bool $decode_binary = true
]] )
sqlite_fetch_all() returns an array of the entire result
set from the result resource. It is similar to calling
sqlite_query() (or
sqlite_unbuffered_query()) and then
sqlite_fetch_array() for each row in the result set.
Parametry
-
result -
The SQLite result resource. This parameter is not required when using the object-oriented method.
-
result_type -
Opcjonalny parametr
result_typeprzyjmuje wartości stałych i określa jak indeksowane będą zwracane wartości. UżywającSQLITE_ASSOCzwrócone zostaną tylko indeksy asocjacyjne (nazwy pól), podczas gdySQLITE_NUMzwróci tylko indeksy numeryczne (numery pól).SQLITE_BOTHzwróci i indeksy asocjacyjne i numeryczne.SQLITE_BOTHjest domyślną wartością dla tej funkcji. -
decode_binary -
Gdy parametr
decode_binaryzostanie ustawiony naTRUE(domyślnie), PHP zdekoduje kodowanie binarne, któremu zostały poddane dane, jeśli były kodowane przy użyciu funkcji sqlite_escape_string(). Zazwyczaj należy pozostawić domyślną wartość tego parametru, chyba że baza jest współużytkowana przez różne aplikacje.
Zwracane wartości
Returns an array of the remaining rows in a result set. If called right after sqlite_query(), it returns all rows. If called after sqlite_fetch_array(), it returns the rest. If there are no rows in a result set, it returns an empty array.
Wielkość liter w nazwach kolumn zwróconych przez
SQLITE_ASSOC i SQLITE_BOTH zostaną
przetworzone zależnie od ustawienia opcji konfiguracji
sqlite.assoc_case.
Przykłady
Przykład #1 Procedural example
<?php
$dbhandle = sqlite_open('sqlitedb');
$query = sqlite_query($dbhandle, 'SELECT name, email FROM users LIMIT 25');
$result = sqlite_fetch_all($query, SQLITE_ASSOC);
foreach ($result as $entry) {
echo 'Name: ' . $entry['name'] . ' E-mail: ' . $entry['email'];
}
?>
Przykład #2 Object-oriented example
<?php
$dbhandle = new SQLiteDatabase('sqlitedb');
$query = $dbhandle->query('SELECT name, email FROM users LIMIT 25'); // buffered result set
$query = $dbhandle->unbufferedQuery('SELECT name, email FROM users LIMIT 25'); // unbuffered result set
$result = $query->fetchAll(SQLITE_ASSOC);
foreach ($result as $entry) {
echo 'Name: ' . $entry['name'] . ' E-mail: ' . $entry['email'];
}
?>
sqlite_fetch_array
SQLiteResult::fetch
SQLiteUnbuffered::fetch
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_fetch_array -- SQLiteResult::fetch -- SQLiteUnbuffered::fetch — Fetches the next row from a result set as an array
Opis
$result
[, int $result_type = SQLITE_BOTH
[, bool $decode_binary = true
]] )Styl obiektowy (method):
$result_type = SQLITE_BOTH
[, bool $decode_binary = true
]] )$result_type = SQLITE_BOTH
[, bool $decode_binary = true
]] )
Fetches the next row from the given result handle.
If there are no more rows, returns FALSE, otherwise returns an
associative array representing the row data.
Parametry
-
result -
The SQLite result resource. This parameter is not required when using the object-oriented method.
-
result_type -
Opcjonalny parametr
result_typeprzyjmuje wartości stałych i określa jak indeksowane będą zwracane wartości. UżywającSQLITE_ASSOCzwrócone zostaną tylko indeksy asocjacyjne (nazwy pól), podczas gdySQLITE_NUMzwróci tylko indeksy numeryczne (numery pól).SQLITE_BOTHzwróci i indeksy asocjacyjne i numeryczne.SQLITE_BOTHjest domyślną wartością dla tej funkcji. -
decode_binary -
Gdy parametr
decode_binaryzostanie ustawiony naTRUE(domyślnie), PHP zdekoduje kodowanie binarne, któremu zostały poddane dane, jeśli były kodowane przy użyciu funkcji sqlite_escape_string(). Zazwyczaj należy pozostawić domyślną wartość tego parametru, chyba że baza jest współużytkowana przez różne aplikacje.
Zwracane wartości
Returns an array of the next row from a result set; FALSE if the
next position is beyond the final row.
Wielkość liter w nazwach kolumn zwróconych przez
SQLITE_ASSOC i SQLITE_BOTH zostaną
przetworzone zależnie od ustawienia opcji konfiguracji
sqlite.assoc_case.
Przykłady
Przykład #1 Procedural example
<?php
$dbhandle = sqlite_open('sqlitedb');
$query = sqlite_query($dbhandle, 'SELECT name, email FROM users LIMIT 25');
while ($entry = sqlite_fetch_array($query, SQLITE_ASSOC)) {
echo 'Name: ' . $entry['name'] . ' E-mail: ' . $entry['email'];
}
?>
Przykład #2 Object-oriented example
<?php
$dbhandle = new SQLiteDatabase('sqlitedb');
$query = $dbhandle->query('SELECT name, email FROM users LIMIT 25'); // buffered result set
$query = $dbhandle->unbufferedQuery('SELECT name, email FROM users LIMIT 25'); // unbuffered result set
while ($entry = $query->fetch(SQLITE_ASSOC)) {
echo 'Name: ' . $entry['name'] . ' E-mail: ' . $entry['email'];
}
?>
Zobacz też:
- sqlite_array_query() - Execute a query against a given database and returns an array
- sqlite_fetch_string() - Alias dla sqlite_fetch_single
sqlite_fetch_column_types
SQLiteDatabase::fetchColumnTypes
(PHP 5 < 5.4.0)
sqlite_fetch_column_types -- SQLiteDatabase::fetchColumnTypes — Return an array of column types from a particular table
Opis
$table_name
, resource $dbhandle
[, int $result_type = SQLITE_ASSOC
] )Styl obiektowy (method):
$table_name
[, int $result_type = SQLITE_ASSOC
] )
sqlite_fetch_column_types() returns an array of column
data types from the specified table_name table.
Parametry
-
table_name -
The table name to query.
-
dbhandle -
The SQLite Database resource; returned from sqlite_open() when used procedurally. This parameter is not required when using the object-oriented method.
-
result_type -
The optional
result_typeparameter accepts a constant and determines how the returned array will be indexed. UsingSQLITE_ASSOCwill return only associative indices (named fields) whileSQLITE_NUMwill return only numerical indices (ordinal field numbers).SQLITE_ASSOCis the default for this function.
Zwracane wartości
Returns an array of column data types; FALSE on error.
Wielkość liter w nazwach kolumn zwróconych przez
SQLITE_ASSOC i SQLITE_BOTH zostaną
przetworzone zależnie od ustawienia opcji konfiguracji
sqlite.assoc_case.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.1.0 | Added result_type |
Przykłady
Przykład #1 Procedural example
<?php
$db = sqlite_open('mysqlitedb');
sqlite_query($db, 'CREATE TABLE foo (bar varchar(10), arf text)');
$cols = sqlite_fetch_column_types('foo', $db, SQLITE_ASSOC);
foreach ($cols as $column => $type) {
echo "Column: $column Type: $type\n";
}
?>
Przykład #2 Object-oriented example
<?php
$db = new SQLiteDatabase('mysqlitedb');
$db->query('CREATE TABLE foo (bar varchar(10), arf text)');
$cols = $db->fetchColumnTypes('foo', SQLITE_ASSOC);
foreach ($cols as $column => $type) {
echo "Column: $column Type: $type\n";
}
?>
Powyższy przykład wyświetli:
Column: bar Type: VARCHAR Column: arf Type: TEXT
sqlite_fetch_object
SQLiteResult::fetchObject
SQLiteUnbuffered::fetchObject
(PHP 5 < 5.4.0)
sqlite_fetch_object -- SQLiteResult::fetchObject -- SQLiteUnbuffered::fetchObject — Fetches the next row from a result set as an object
Opis
$result
[, string $class_name
[, array $ctor_params
[, bool $decode_binary = true
]]] )Styl obiektowy (method):
$class_name
[, array $ctor_params
[, bool $decode_binary = true
]]] )$class_name
[, array $ctor_params
[, bool $decode_binary = true
]]] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
sqlite_fetch_single
SQLiteResult::fetchSingle
SQLiteUnbuffered::fetchSingle
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.1)
sqlite_fetch_single -- SQLiteResult::fetchSingle -- SQLiteUnbuffered::fetchSingle — Fetches the first column of a result set as a string
Opis
$result
[, bool $decode_binary = true
] )Styl obiektowy (method):
$decode_binary = true
] )$decode_binary = true
] )sqlite_fetch_single() is identical to sqlite_fetch_array() except that it returns the value of the first column of the rowset.
This is the most optimal way to retrieve data when you are only interested in the values from a single column of data.
Parametry
-
result -
The SQLite result resource. This parameter is not required when using the object-oriented method.
-
decode_binary -
Gdy parametr
decode_binaryzostanie ustawiony naTRUE(domyślnie), PHP zdekoduje kodowanie binarne, któremu zostały poddane dane, jeśli były kodowane przy użyciu funkcji sqlite_escape_string(). Zazwyczaj należy pozostawić domyślną wartość tego parametru, chyba że baza jest współużytkowana przez różne aplikacje.
Zwracane wartości
Returns the first column value, as a string.
Przykłady
Przykład #1 A sqlite_fetch_single() example
<?php
if ($dbhandle = sqlite_open('mysqlitedb', 0666, $sqliteerror)) {
$sql = "SELECT id FROM sometable WHERE id = 42";
$res = sqlite_query($dbhandle, $sql);
if (sqlite_num_rows($res) > 0) {
echo sqlite_fetch_single($res); // 42
}
sqlite_close($dbhandle);
}
?>
sqlite_fetch_string
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_fetch_string — Alias dla sqlite_fetch_single()
Opis
Ta funkcja jest aliasem dla: sqlite_fetch_single().
sqlite_field_name
SQLiteResult::fieldName
SQLiteUnbuffered::fieldName
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_field_name -- SQLiteResult::fieldName -- SQLiteUnbuffered::fieldName — Returns the name of a particular field
Opis
$result
, int $field_index
)Styl obiektowy (method):
$field_index
)$field_index
)
Given the ordinal column number, field_index,
sqlite_field_name() returns the name of that field in
the result set result.
Parametry
-
result -
The SQLite result resource. This parameter is not required when using the object-oriented method.
-
field_index -
The ordinal column number in the result set.
Zwracane wartości
Returns the name of a field in an SQLite result set, given the ordinal
column number; FALSE on error.
Wielkość liter w nazwach kolumn zwróconych przez
SQLITE_ASSOC i SQLITE_BOTH zostaną
przetworzone zależnie od ustawienia opcji konfiguracji
sqlite.assoc_case.
sqlite_has_more
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_has_more — Finds whether or not more rows are available
Opis
$result
)Finds whether more rows are available from the given result set.
Parametry
-
result -
The SQLite result resource.
Zwracane wartości
Returns TRUE if there are more rows available from the
result handle, or FALSE otherwise.
Zobacz też:
- sqlite_num_rows() - Returns the number of rows in a buffered result set
- sqlite_changes() - Returns the number of rows that were changed by the most recent SQL statement
sqlite_has_prev
SQLiteResult::hasPrev
(PHP 5 < 5.4.0)
sqlite_has_prev -- SQLiteResult::hasPrev — Returns whether or not a previous row is available
Opis
$result
)Styl obiektowy (method):
Find whether there are more previous rows from the given result handle.
Parametry
-
result -
The SQLite result resource. This parameter is not required when using the object-oriented method.
Informacja:
Ta funkcja nie może być używana z niebuforowanymi wynikami.
Zwracane wartości
Returns TRUE if there are more previous rows available from the
result handle, or FALSE otherwise.
Zobacz też:
- sqlite_prev() - Seek to the previous row number of a result set
- sqlite_has_more() - Finds whether or not more rows are available
- sqlite_num_rows() - Returns the number of rows in a buffered result set
sqlite_key
SQLiteResult::key
(PHP 5 >= 5.1.0 and < 5.4.0)
sqlite_key -- SQLiteResult::key — Returns the current row index
Opis
$result
)Styl obiektowy (method):
sqlite_key() returns the current row index of the
buffered result set result.
Parametry
-
result -
The SQLite result resource. This parameter is not required when using the object-oriented method.
Informacja:
Ta funkcja nie może być używana z niebuforowanymi wynikami.
Zwracane wartości
Returns the current row index of the buffered result set
result.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.0.4 | Prior to PHP 5.0.4, sqlite_key() was only able to be called as a method on a SQLiteResult object, not procedurally. |
Zobacz też:
- sqlite_next() - Seek to the next row number
- sqlite_current() - Fetches the current row from a result set as an array
- sqlite_rewind() - Seek to the first row number
sqlite_last_error
SQLiteDatabase::lastError
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_last_error -- SQLiteDatabase::lastError — Returns the error code of the last error for a database
Opis
$dbhandle
)Styl obiektowy (method):
Returns the error code from the last operation performed on
dbhandle (the database handle), or 0
when no error occurred. A human readable
description of the error code can be retrieved using
sqlite_error_string().
Parametry
-
dbhandle -
The SQLite Database resource; returned from sqlite_open() when used procedurally. This parameter is not required when using the object-oriented method.
Zwracane wartości
Returns an error code, or 0 if no error occurred.
sqlite_last_insert_rowid
SQLiteDatabase::lastInsertRowid
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_last_insert_rowid -- SQLiteDatabase::lastInsertRowid — Returns the rowid of the most recently inserted row
Opis
$dbhandle
)Styl obiektowy (method):
Returns the rowid of the row that was most recently inserted into the
database dbhandle, if it was created as an
auto-increment field.
You can create auto-increment fields in SQLite by declaring them as INTEGER PRIMARY KEY in your table schema.
Parametry
-
dbhandle -
The SQLite Database resource; returned from sqlite_open() when used procedurally. This parameter is not required when using the object-oriented method.
Zwracane wartości
Returns the row id, as an integer.
sqlite_libencoding
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_libencoding — Returns the encoding of the linked SQLite library
Opis
The SQLite library may be compiled in either ISO-8859-1 or UTF-8 compatible modes. This function allows you to determine which encoding scheme is used by your version of the library.
The default PHP distribution builds libsqlite in ISO-8859-1 encoding mode. However, this is a misnomer; rather than handling ISO-8859-1, it operates according to your current locale settings for string comparisons and sort ordering. So, rather than ISO-8859-1, you should think of it as being '8-bit' instead.
When compiled with UTF-8 support, sqlite handles encoding and decoding of UTF-8 multi-byte character sequences, but does not yet do a complete job when working with the data (no normalization is performed for example), and some comparison operations may still not be carried out correctly.
It is not recommended that you use PHP in a web-server configuration with a version of the SQLite library compiled with UTF-8 support, since libsqlite will abort the process if it detects a problem with the UTF-8 encoding.
Zwracane wartości
Returns the library encoding.
Zobacz też:
- sqlite_lib_version()
sqlite_libversion
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_libversion — Returns the version of the linked SQLite library
Opis
Returns the version of the linked SQLite library.
Zwracane wartości
Returns the library version, as a string.
sqlite_next
SQLiteResult::next
SQLiteUnbuffered::next
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_next -- SQLiteResult::next -- SQLiteUnbuffered::next — Seek to the next row number
Opis
$result
)Styl obiektowy (method):
sqlite_next() advances the result handle
result to the next row.
Parametry
-
result -
The SQLite result resource. This parameter is not required when using the object-oriented method.
Zwracane wartości
Returns TRUE on success, or FALSE if there are no more rows.
Zobacz też:
- sqlite_seek() - Seek to a particular row number of a buffered result set
- sqlite_current() - Fetches the current row from a result set as an array
- sqlite_rewind() - Seek to the first row number
sqlite_num_fields
SQLiteResult::numFields
SQLiteUnbuffered::numFields
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_num_fields -- SQLiteResult::numFields -- SQLiteUnbuffered::numFields — Returns the number of fields in a result set
Opis
$result
)Styl obiektowy (method):
Returns the number of fields in the result set.
Parametry
-
result -
The SQLite result resource. This parameter is not required when using the object-oriented method.
Zwracane wartości
Returns the number of fields, as an integer.
Zobacz też:
- sqlite_changes() - Returns the number of rows that were changed by the most recent SQL statement
- sqlite_num_rows() - Returns the number of rows in a buffered result set
sqlite_num_rows
SQLiteResult::numRows
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_num_rows -- SQLiteResult::numRows — Returns the number of rows in a buffered result set
Opis
$result
)Styl obiektowy (method):
Returns the number of rows in the buffered result
set.
Parametry
-
result -
The SQLite result resource. This parameter is not required when using the object-oriented method.
Informacja:
Ta funkcja nie może być używana z niebuforowanymi wynikami.
Zwracane wartości
Returns the number of rows, as an integer.
Przykłady
Przykład #1 Procedural example
<?php
$db = sqlite_open('mysqlitedb');
$result = sqlite_query($db, "SELECT * FROM mytable WHERE name='John Doe'");
$rows = sqlite_num_rows($result);
echo "Number of rows: $rows";
?>
Przykład #2 Object-oriented example
<?php
$db = new SQLiteDatabase('mysqlitedb');
$result = $db->query("SELECT * FROM mytable WHERE name='John Doe'");
$rows = $result->numRows();
echo "Number of rows: $rows";
?>
Zobacz też:
- sqlite_changes() - Returns the number of rows that were changed by the most recent SQL statement
- sqlite_query() - Executes a query against a given database and returns a result handle
- sqlite_num_fields() - Returns the number of fields in a result set
sqlite_open
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_open — Opens an SQLite database and create the database if it does not exist
Opis
$filename
[, int $mode = 0666
[, string &$error_message
]] )Styl obiektowy (constructor):
$filename
[, int $mode = 0666
[, string &$error_message
]] )Opens an SQLite database or creates the database if it does not exist.
Parametry
-
filename -
The filename of the SQLite database. If the file does not exist, SQLite will attempt to create it. PHP must have write permissions to the file if data is inserted, the database schema is modified or to create the database if it does not exist.
-
mode -
The mode of the file. Intended to be used to open the database in read-only mode. Presently, this parameter is ignored by the sqlite library. The default value for mode is the octal value 0666 and this is the recommended value.
-
error_message -
Passed by reference and is set to hold a descriptive error message explaining why the database could not be opened if there was an error.
Zwracane wartości
Returns a resource (database handle) on success, FALSE on error.
Przykłady
Przykład #1 sqlite_open() example
<?php
if ($db = sqlite_open('mysqlitedb', 0666, $sqliteerror)) {
sqlite_query($db, 'CREATE TABLE foo (bar varchar(10))');
sqlite_query($db, "INSERT INTO foo VALUES ('fnord')");
$result = sqlite_query($db, 'select bar from foo');
var_dump(sqlite_fetch_array($result));
} else {
die($sqliteerror);
}
?>
Notatki
On Unix platforms, SQLite is sensitive to scripts that use the fork() system call. If you do have such a script, it is recommended that you close the handle prior to forking and then re-open it in the child and/or parent. For more information on this issue, see » The C language interface to the SQLite library in the section entitled Multi-Threading And SQLite.
It is not recommended to work with SQLite databases mounted on NFS partitions. Since NFS is notoriously bad when it comes to locking you may find that you cannot even open the database at all, and if it succeeds, the locking behaviour may be undefined.
Informacja: Starting with SQLite library version 2.8.2, you can specify :memory: as the
filenameto create a database that lives only in the memory of the computer. This is useful mostly for temporary processing, as the in-memory database will be destroyed when the process ends. It can also be useful when coupled with the ATTACH DATABASE SQL statement to load other databases and move and query data between them.
Informacja: SQLite is tryb bezpieczny and open_basedir aware.
Zobacz też:
- sqlite_popen() - Opens a persistent handle to an SQLite database and create the database if it does not exist
- sqlite_close() - Closes an open SQLite database
- sqlite_factory() - Opens an SQLite database and returns an SQLiteDatabase object
sqlite_popen
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_popen — Opens a persistent handle to an SQLite database and create the database if it does not exist
Opis
$filename
[, int $mode = 0666
[, string &$error_message
]] )This function behaves identically to sqlite_open() except that is uses the persistent resource mechanism of PHP. For information about the meaning of the parameters, read the sqlite_open() manual page.
sqlite_popen() will first check to see if a persistent
handle has already been opened for the given
filename. If it finds one, it returns that handle
to your script, otherwise it opens a fresh handle to the database.
The benefit of this approach is that you don't incur the performance cost of re-reading the database and index schema on each page hit served by persistent web server SAPI's (any SAPI except for regular CGI or CLI).
Informacja: If you use persistent handles and have the database updated by a background process (perhaps via a crontab), and that process re-creates the database by overwriting it (either by unlinking and rebuilding, or moving the updated version to replace the current version), you may experience undefined behaviour when a persistent handle on the old version of the database is recycled. To avoid this situation, have your background processes open the same database file and perform their updates in a transaction.
Parametry
-
filename -
The filename of the SQLite database. If the file does not exist, SQLite will attempt to create it. PHP must have write permissions to the file if data is inserted, the database schema is modified or to create the database if it does not exist.
-
mode -
The mode of the file. Intended to be used to open the database in read-only mode. Presently, this parameter is ignored by the sqlite library. The default value for mode is the octal value 0666 and this is the recommended value.
-
error_message -
Passed by reference and is set to hold a descriptive error message explaining why the database could not be opened if there was an error.
Zwracane wartości
Returns a resource (database handle) on success, FALSE on error.
Zobacz też:
- sqlite_open() - Opens an SQLite database and create the database if it does not exist
- sqlite_close() - Closes an open SQLite database
- sqlite_factory() - Opens an SQLite database and returns an SQLiteDatabase object
sqlite_prev
SQLiteResult::prev
(PHP 5 < 5.4.0)
sqlite_prev -- SQLiteResult::prev — Seek to the previous row number of a result set
Opis
$result
)Styl obiektowy (method):
sqlite_prev() seeks back the
result handle to the previous row.
Parametry
-
result -
The SQLite result resource. This parameter is not required when using the object-oriented method.
Informacja:
Ta funkcja nie może być używana z niebuforowanymi wynikami.
Zwracane wartości
Returns TRUE on success, or FALSE if there are no more previous rows.
Zobacz też:
- sqlite_has_prev() - Returns whether or not a previous row is available
- sqlite_rewind() - Seek to the first row number
- sqlite_next() - Seek to the next row number
sqlite_query
SQLiteDatabase::query
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_query -- SQLiteDatabase::query — Executes a query against a given database and returns a result handle
Opis
$dbhandle
, string $query
[, int $result_type = SQLITE_BOTH
[, string &$error_msg
]] )$query
, resource $dbhandle
[, int $result_type = SQLITE_BOTH
[, string &$error_msg
]] )Styl obiektowy (method):
$query
[, int $result_type = SQLITE_BOTH
[, string &$error_msg
]] )
Executes an SQL statement given by the query against
a given database handle.
Parametry
-
dbhandle -
The SQLite Database resource; returned from sqlite_open() when used procedurally. This parameter is not required when using the object-oriented method.
-
query -
The query to be executed.
Data inside the query should be properly escaped.
-
result_type -
Opcjonalny parametr
result_typeprzyjmuje wartości stałych i określa jak indeksowane będą zwracane wartości. UżywającSQLITE_ASSOCzwrócone zostaną tylko indeksy asocjacyjne (nazwy pól), podczas gdySQLITE_NUMzwróci tylko indeksy numeryczne (numery pól).SQLITE_BOTHzwróci i indeksy asocjacyjne i numeryczne.SQLITE_BOTHjest domyślną wartością dla tej funkcji. -
error_msg -
The specified variable will be filled if an error occurs. This is specially important because SQL syntax errors can't be fetched using the sqlite_last_error() function.
Informacja: Obsługiwane są dwie alternatywne składnie, dla zachowania kompatybilności z rozszerzeniami dla innych baz danych (takich jak MySQL). Preferowana jest pierwsza, gdzie
dbhandlejest pierwszym parametrem funkcji.
Zwracane wartości
This function will return a result handle lub FALSE w przypadku niepowodzenia.
For queries that return rows, the result handle can then be used with
functions such as sqlite_fetch_array() and
sqlite_seek().
Regardless of the query type, this function will return FALSE if the
query failed.
sqlite_query() returns a buffered, seekable result handle. This is useful for reasonably small queries where you need to be able to randomly access the rows. Buffered result handles will allocate memory to hold the entire result and will not return until it has been fetched. If you only need sequential access to the data, it is recommended that you use the much higher performance sqlite_unbuffered_query() instead.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.1.0 |
Added the error_msg parameter
|
Notatki
SQLite will execute multiple queries separated by semicolons, so you can use it to execute a batch of SQL that you have loaded from a file or have embedded in a script. However, this works only when the result of the function is not used - if it is used, only the first SQL statement would be executed. Function sqlite_exec() will always execute multiple SQL statements.
When executing multiple queries, the return value of this function
will be FALSE if there was an error, but undefined otherwise (it might
be TRUE for success or it might return a result handle).
Zobacz też:
- sqlite_unbuffered_query() - Execute a query that does not prefetch and buffer all data
- sqlite_array_query() - Execute a query against a given database and returns an array
sqlite_rewind
SQLiteResult::rewind
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_rewind -- SQLiteResult::rewind — Seek to the first row number
Opis
$result
)Styl obiektowy (method):
sqlite_rewind() seeks back to the first row in the given result set.
Parametry
-
result -
The SQLite result resource. This parameter is not required when using the object-oriented method.
Informacja:
Ta funkcja nie może być używana z niebuforowanymi wynikami.
Zwracane wartości
Returns FALSE if there are no rows in the result set, TRUE otherwise.
Zobacz też:
- sqlite_next() - Seek to the next row number
- sqlite_current() - Fetches the current row from a result set as an array
- sqlite_seek() - Seek to a particular row number of a buffered result set
sqlite_seek
SQLiteResult::seek
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_seek -- SQLiteResult::seek — Seek to a particular row number of a buffered result set
Opis
$result
, int $rownum
)Styl obiektowy (method):
$rownum
)
sqlite_seek() seeks to the row given by the parameter
rownum.
Parametry
-
result -
The SQLite result resource. This parameter is not required when using the object-oriented method.
Informacja:
Ta funkcja nie może być używana z niebuforowanymi wynikami.
-
rownum -
The ordinal row number to seek to. The row number is zero-based (0 is the first row).
Informacja:
Ta funkcja nie może być używana z niebuforowanymi wynikami.
Zwracane wartości
Returns FALSE if the row does not exist, TRUE otherwise.
Zobacz też:
- sqlite_next() - Seek to the next row number
- sqlite_current() - Fetches the current row from a result set as an array
- sqlite_rewind() - Seek to the first row number
sqlite_single_query
SQLiteDatabase::singleQuery
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.1)
sqlite_single_query -- SQLiteDatabase::singleQuery — Executes a query and returns either an array for one single column or the value of the first row
Opis
$db
, string $query
[, bool $first_row_only
[, bool $decode_binary
]] )Styl obiektowy (method):
$query
[, bool $first_row_only
[, bool $decode_binary
]] )Ta funkcja jest obecnie nieudokumentowana, dostępna jest jedynie lista jej argumentów.
sqlite_udf_decode_binary
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_udf_decode_binary — Decode binary data passed as parameters to an UDF
Opis
$data
)Decodes binary data passed as parameters to a UDF.
You must call this function on parameters passed to your UDF if you need them to handle binary data, as the binary encoding employed by PHP will obscure the content and of the parameter in its natural, non-coded form.
PHP does not perform this encode/decode operation automatically as it would severely impact performance if it did.
Parametry
-
data -
The encoded data that will be decoded, data that was applied by either sqlite_udf_encode_binary() or sqlite_escape_string().
Zwracane wartości
The decoded string.
Przykłady
Przykład #1 binary-safe max_length aggregation function example
<?php
$data = array(
'one',
'two',
'three',
'four',
'five',
'six',
'seven',
'eight',
'nine',
'ten',
);
$db = sqlite_open(':memory:');
sqlite_query($db, "CREATE TABLE strings(a)");
foreach ($data as $str) {
$str = sqlite_escape_string($str);
sqlite_query($db, "INSERT INTO strings VALUES ('$str')");
}
function max_len_step(&$context, $string)
{
$string = sqlite_udf_decode_binary($string);
if (strlen($string) > $context) {
$context = strlen($string);
}
}
function max_len_finalize(&$context)
{
return $context;
}
sqlite_create_aggregate($db, 'max_len', 'max_len_step', 'max_len_finalize');
var_dump(sqlite_array_query($db, 'SELECT max_len(a) from strings'));
?>
Zobacz też:
- sqlite_udf_encode_binary() - Encode binary data before returning it from an UDF
- sqlite_create_function() - Registers a "regular" User Defined Function for use in SQL statements
- sqlite_create_aggregate() - Register an aggregating UDF for use in SQL statements
sqlite_udf_encode_binary
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_udf_encode_binary — Encode binary data before returning it from an UDF
Opis
$data
)
sqlite_udf_encode_binary() applies a binary encoding
to the data so that it can be safely returned from
queries (since the underlying libsqlite API is not binary safe).
If there is a chance that your data might be binary unsafe (e.g.: it contains a NUL byte in the middle rather than at the end, or if it has and 0x01 byte as the first character) then you must call this function to encode the return value from your UDF.
PHP does not perform this encode/decode operation automatically as it would severely impact performance if it did.
Informacja:
Do not use sqlite_escape_string() to quote strings returned from UDF's as it will lead to double-quoting of the data. Use sqlite_udf_encode_binary() instead!
Zwracane wartości
The encoded string.
Zobacz też:
- sqlite_udf_decode_binary() - Decode binary data passed as parameters to an UDF
- sqlite_escape_string() - Escapes a string for use as a query parameter
- sqlite_create_function() - Registers a "regular" User Defined Function for use in SQL statements
- sqlite_create_aggregate() - Register an aggregating UDF for use in SQL statements
sqlite_unbuffered_query
SQLiteDatabase::unbufferedQuery
(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_unbuffered_query -- SQLiteDatabase::unbufferedQuery — Execute a query that does not prefetch and buffer all data
Opis
$dbhandle
, string $query
[, int $result_type = SQLITE_BOTH
[, string &$error_msg
]] )$query
, resource $dbhandle
[, int $result_type = SQLITE_BOTH
[, string &$error_msg
]] )Styl obiektowy (method):
$query
[, int $result_type = SQLITE_BOTH
[, string &$error_msg
]] )sqlite_unbuffered_query() is identical to sqlite_query() except that the result that is returned is a sequential forward-only result set that can only be used to read each row, one after the other.
This function is ideal for generating things such as HTML tables where you only need to process one row at a time and don't need to randomly access the row data.
Informacja:
Functions such as sqlite_seek(), sqlite_rewind(), sqlite_next(), sqlite_current(), and sqlite_num_rows() do not work on result handles returned from sqlite_unbuffered_query().
Parametry
-
dbhandle -
The SQLite Database resource; returned from sqlite_open() when used procedurally. This parameter is not required when using the object-oriented method.
-
query -
The query to be executed.
Data inside the query should be properly escaped.
-
result_type -
Opcjonalny parametr
result_typeprzyjmuje wartości stałych i określa jak indeksowane będą zwracane wartości. UżywającSQLITE_ASSOCzwrócone zostaną tylko indeksy asocjacyjne (nazwy pól), podczas gdySQLITE_NUMzwróci tylko indeksy numeryczne (numery pól).SQLITE_BOTHzwróci i indeksy asocjacyjne i numeryczne.SQLITE_BOTHjest domyślną wartością dla tej funkcji. -
error_msg -
The specified variable will be filled if an error occurs. This is specially important because SQL syntax errors can't be fetched using the sqlite_last_error() function.
Informacja: Obsługiwane są dwie alternatywne składnie, dla zachowania kompatybilności z rozszerzeniami dla innych baz danych (takich jak MySQL). Preferowana jest pierwsza, gdzie
dbhandlejest pierwszym parametrem funkcji.
Zwracane wartości
Returns a result handle lub FALSE w przypadku niepowodzenia.
sqlite_unbuffered_query() returns a sequential forward-only result set that can only be used to read each row, one after the other.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.1.0 |
Added the error_msg parameter
|
sqlite_valid
SQLiteResult::valid
SQLiteUnbuffered::valid
(PHP 5 < 5.4.0)
sqlite_valid -- SQLiteResult::valid -- SQLiteUnbuffered::valid — Returns whether more rows are available
Opis
$result
)Styl obiektowy (method):
Finds whether more rows are available from the given result handle.
Parametry
-
result -
The SQLite result resource. This parameter is not required when using the object-oriented method.
Informacja:
Ta funkcja nie może być używana z niebuforowanymi wynikami.
Zwracane wartości
Returns TRUE if there are more rows available from the
result handle, or FALSE otherwise.
Zobacz też:
- sqlite_num_rows() - Returns the number of rows in a buffered result set
- sqlite_changes() - Returns the number of rows that were changed by the most recent SQL statement
Spis treści
- sqlite_array_query — Execute a query against a given database and returns an array
- sqlite_busy_timeout — Set busy timeout duration, or disable busy handlers
- sqlite_changes — Returns the number of rows that were changed by the most recent SQL statement
- sqlite_close — Closes an open SQLite database
- sqlite_column — Fetches a column from the current row of a result set
- sqlite_create_aggregate — Register an aggregating UDF for use in SQL statements
- sqlite_create_function — Registers a "regular" User Defined Function for use in SQL statements
- sqlite_current — Fetches the current row from a result set as an array
- sqlite_error_string — Returns the textual description of an error code
- sqlite_escape_string — Escapes a string for use as a query parameter
- sqlite_exec — Executes a result-less query against a given database
- sqlite_factory — Opens an SQLite database and returns an SQLiteDatabase object
- sqlite_fetch_all — Fetches all rows from a result set as an array of arrays
- sqlite_fetch_array — Fetches the next row from a result set as an array
- sqlite_fetch_column_types — Return an array of column types from a particular table
- sqlite_fetch_object — Fetches the next row from a result set as an object
- sqlite_fetch_single — Fetches the first column of a result set as a string
- sqlite_fetch_string — Alias dla sqlite_fetch_single
- sqlite_field_name — Returns the name of a particular field
- sqlite_has_more — Finds whether or not more rows are available
- sqlite_has_prev — Returns whether or not a previous row is available
- sqlite_key — Returns the current row index
- sqlite_last_error — Returns the error code of the last error for a database
- sqlite_last_insert_rowid — Returns the rowid of the most recently inserted row
- sqlite_libencoding — Returns the encoding of the linked SQLite library
- sqlite_libversion — Returns the version of the linked SQLite library
- sqlite_next — Seek to the next row number
- sqlite_num_fields — Returns the number of fields in a result set
- sqlite_num_rows — Returns the number of rows in a buffered result set
- sqlite_open — Opens an SQLite database and create the database if it does not exist
- sqlite_popen — Opens a persistent handle to an SQLite database and create the database if it does not exist
- sqlite_prev — Seek to the previous row number of a result set
- sqlite_query — Executes a query against a given database and returns a result handle
- sqlite_rewind — Seek to the first row number
- sqlite_seek — Seek to a particular row number of a buffered result set
- sqlite_single_query — Executes a query and returns either an array for one single column or the value of the first row
- sqlite_udf_decode_binary — Decode binary data passed as parameters to an UDF
- sqlite_udf_encode_binary — Encode binary data before returning it from an UDF
- sqlite_unbuffered_query — Execute a query that does not prefetch and buffer all data
- sqlite_valid — Returns whether more rows are available
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- SQLite Funkcje
- sqlite_array_query — Execute a query against a given database and returns an array
- sqlite_busy_timeout — Set busy timeout duration, or disable busy handlers
- sqlite_changes — Returns the number of rows that were changed by the most recent SQL statement
- sqlite_close — Closes an open SQLite database
- sqlite_column — Fetches a column from the current row of a result set
- sqlite_create_aggregate — Register an aggregating UDF for use in SQL statements
- sqlite_create_function — Registers a "regular" User Defined Function for use in SQL statements
- sqlite_current — Fetches the current row from a result set as an array
- sqlite_error_string — Returns the textual description of an error code
- sqlite_escape_string — Escapes a string for use as a query parameter
- sqlite_exec — Executes a result-less query against a given database
- sqlite_factory — Opens an SQLite database and returns an SQLiteDatabase object
- sqlite_fetch_all — Fetches all rows from a result set as an array of arrays
- sqlite_fetch_array — Fetches the next row from a result set as an array
- sqlite_fetch_column_types — Return an array of column types from a particular table
- sqlite_fetch_object — Fetches the next row from a result set as an object
- sqlite_fetch_single — Fetches the first column of a result set as a string
- sqlite_fetch_string — Alias dla sqlite_fetch_single
- sqlite_field_name — Returns the name of a particular field
- sqlite_has_more — Finds whether or not more rows are available
- sqlite_has_prev — Returns whether or not a previous row is available
- sqlite_key — Returns the current row index
- sqlite_last_error — Returns the error code of the last error for a database
- sqlite_last_insert_rowid — Returns the rowid of the most recently inserted row
- sqlite_libencoding — Returns the encoding of the linked SQLite library
- sqlite_libversion — Returns the version of the linked SQLite library
- sqlite_next — Seek to the next row number
- sqlite_num_fields — Returns the number of fields in a result set
- sqlite_num_rows — Returns the number of rows in a buffered result set
- sqlite_open — Opens an SQLite database and create the database if it does not exist
- sqlite_popen — Opens a persistent handle to an SQLite database and create the database if it does not exist
- sqlite_prev — Seek to the previous row number of a result set
- sqlite_query — Executes a query against a given database and returns a result handle
- sqlite_rewind — Seek to the first row number
- sqlite_seek — Seek to a particular row number of a buffered result set
- sqlite_single_query — Executes a query and returns either an array for one single column or the value of the first row
- sqlite_udf_decode_binary — Decode binary data passed as parameters to an UDF
- sqlite_udf_encode_binary — Encode binary data before returning it from an UDF
- sqlite_unbuffered_query — Execute a query that does not prefetch and buffer all data
- sqlite_valid — Returns whether more rows are available
SQLite3
Wstęp
Obsługa baz danych SQLite 3.
Instalacja/Konfiguracja
Spis treści
Wymagania
Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.
Instalacja
The SQLite3 extension is enabled by default as of PHP 5.3.0. It's possible to disable it by using --without-sqlite3 at compile time.
Windows users must enable php_sqlite3.dll in order to use this extension. This DLL is included with Windows distributions of PHP as of PHP 5.3.0.
Informacja:
This extension was briefly a PECL extension but that version is only recommended for experimental use.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Changelog |
|---|---|---|---|
| sqlite3.extension_dir | NULL | PHP_INI_SYSTEM |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
sqlite3.extension_dirstring -
Path to the directory where the loadable extensions for SQLite reside.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
-
SQLITE3_ASSOC(integer) - Specifies that the Sqlite3Result::fetchArray() method shall return an array indexed by column name as returned in the corresponding result set.
-
SQLITE3_NUM(integer) - Specifies that the Sqlite3Result::fetchArray() method shall return an array indexed by column number as returned in the corresponding result set, starting at column 0.
-
SQLITE3_BOTH(integer) - Specifies that the Sqlite3Result::fetchArray() method shall return an array indexed by both column name and number as returned in the corresponding result set, starting at column 0.
-
SQLITE3_INTEGER(integer) - Represents the SQLite3 INTEGER storage class.
-
SQLITE3_FLOAT(integer) - Represents the SQLite3 REAL (FLOAT) storage class.
-
SQLITE3_TEXT(integer) - Represents the SQLite3 TEXT storage class.
-
SQLITE3_BLOB(integer) - Represents the SQLite3 BLOB storage class.
-
SQLITE3_NULL(integer) - Represents the SQLite3 NULL storage class.
-
SQLITE3_OPEN_READONLY(integer) - Specifies that the SQLite3 database be opened for reading only.
-
SQLITE3_OPEN_READWRITE(integer) - Specifies that the SQLite3 database be opened for reading and writing.
-
SQLITE3_OPEN_CREATE(integer) - Specifies that the SQLite3 database be created if it does not already exist.
The SQLite3 class
(No version information available, might only be in SVN)
Wstęp
A class that interfaces SQLite 3 databases.
Krótki opis klasy
$name
, mixed $step_callback
, mixed $final_callback
[, int $argument_count = -1
] )$filename
[, int $flags = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE
[, string $encryption_key
]] )SQLite3::busyTimeout
(PHP 5 >= 5.3.3)
SQLite3::busyTimeout — Sets the busy connection handler
Opis
$msecs
)Sets a busy handler that will sleep until the database is not locked or the timeout is reached.
Parametry
-
msecs -
The milliseconds to sleep. Setting this value to a value less than or equal to zero, will turn off an already set timeout handler.
Zwracane wartości
Returns TRUE on success, FALSE on failure.
SQLite3::changes
(PHP 5 >= 5.3.0)
SQLite3::changes — Returns the number of database rows that were changed (or inserted or deleted) by the most recent SQL statement
Opis
Returns the number of database rows that were changed (or inserted or deleted) by the most recent SQL statement.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns an integer value corresponding to the number of database rows changed (or inserted or deleted) by the most recent SQL statement.
Przykłady
Przykład #1 SQLite3::changes() example
<?php
$db = new SQLite3('mysqlitedb.db');
$query = $db->exec('UPDATE counter SET views=0 WHERE page="test"');
if ($query) {
echo 'Number of rows modified: ', $db->changes();
}
?>
SQLite3::close
(PHP 5 >= 5.3.0)
SQLite3::close — Closes the database connection
Opis
Closes the database connection.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns TRUE on success, FALSE on failure.
Przykłady
Przykład #1 SQLite3::close() example
<?php
$db = new SQLite3('mysqlitedb.db');
$db->close();
?>
SQLite3::__construct
(PHP 5 >= 5.3.0)
SQLite3::__construct — Instantiates an SQLite3 object and opens an SQLite 3 database
Opis
$filename
[, int $flags
[, string $encryption_key
]] )Instantiates an SQLite3 object and opens a connection to an SQLite 3 database. If the build includes encryption, then it will attempt to use the key.
Parametry
-
filename -
Path to the SQLite database, or :memory: to use in-memory database.
-
flags -
Optional flags used to determine how to open the SQLite database. By default, open uses SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE.
-
SQLITE3_OPEN_READONLY: Open the database for reading only.
-
SQLITE3_OPEN_READWRITE: Open the database for reading and writing.
-
SQLITE3_OPEN_CREATE: Create the database if it does not exist.
-
-
encryption_key -
An optional encryption key used when encrypting and decrypting an SQLite database.
Zwracane wartości
Returns an SQLite3 object on success.
Przykłady
Przykład #1 SQLite3::__construct() example
<?php
$db = new SQLite3('mysqlitedb.db');
$db->exec('CREATE TABLE foo (bar STRING)');
$db->exec("INSERT INTO foo (bar) VALUES ('This is a test')");
$result = $db->query('SELECT bar FROM foo');
var_dump($result->fetchArray());
?>
SQLite3::createAggregate
(PHP 5 >= 5.3.0)
SQLite3::createAggregate — Registers a PHP function for use as an SQL aggregate function
Opis
$name
, mixed $step_callback
, mixed $final_callback
[, int $argument_count = -1
] )Registers a PHP function or user-defined function for use as an SQL aggregate function for use within SQL statements.
Parametry
-
name -
Name of the SQL aggregate to be created or redefined.
-
step_callback -
The name of a PHP function or user-defined function to apply as a callback for every item in the aggregate.
-
final_callback -
The name of a PHP function or user-defined function to apply as a callback at the end of the aggregate data.
-
argument_count -
The number of arguments that the SQL aggregate takes. If this parameter is negative, then the SQL aggregate may take any number of arguments.
Zwracane wartości
Returns TRUE upon successful creation of the aggregate, FALSE on
failure.
SQLite3::createFunction
(PHP 5 >= 5.3.0)
SQLite3::createFunction — Registers a PHP function for use as an SQL scalar function
Opis
$name
, mixed $callback
[, int $argument_count = -1
] )Registers a PHP function or user-defined function for use as an SQL scalar function for use within SQL statements.
Parametry
-
name -
Name of the SQL function to be created or redefined.
-
callback -
The name of a PHP function or user-defined function to apply as a callback, defining the behavior of the SQL function.
-
argument_count -
The number of arguments that the SQL function takes. If this parameter is negative, then the SQL function may take any number of arguments.
Zwracane wartości
Returns TRUE upon successful creation of the function, FALSE on failure.
Przykłady
Przykład #1 SQLite3::createFunction() example
<?php
function my_udf_md5($string) {
return md5($string);
}
$db = new SQLite3('mysqlitedb.db');
$db->createFunction('my_udf_md5', 'my_udf_md5');
var_dump($db->querySingle('SELECT my_udf_md5("test")'));
?>
Powyższy przykład wyświetli coś podobnego do:
string(32) "098f6bcd4621d373cade4e832627b4f6"
SQLite3::escapeString
(PHP 5 >= 5.3.0)
SQLite3::escapeString — Returns a string that has been properly escaped
Opis
$value
)Returns a string that has been properly escaped for safe inclusion in an SQL statement.
Parametry
-
value -
The string to be escaped.
Zwracane wartości
Returns a properly escaped string that may be used safely in an SQL statement.
Notatki
addslashes() should NOT be used to quote your strings for SQLite queries; it will lead to strange results when retrieving your data.
SQLite3::exec
(PHP 5 >= 5.3.0)
SQLite3::exec — Executes a result-less query against a given database
Opis
$query
)Executes a result-less query against a given database.
Parametry
-
query -
The SQL query to execute (typically an INSERT, UPDATE, or DELETE query).
Zwracane wartości
Returns TRUE if the query succeeded, FALSE on failure.
Przykłady
Przykład #1 SQLite3::exec() example
<?php
$db = new SQLite3('mysqlitedb.db');
$db->exec('CREATE TABLE bar (bar STRING)');
?>
SQLite3::lastErrorCode
(PHP 5 >= 5.3.0)
SQLite3::lastErrorCode — Returns the numeric result code of the most recent failed SQLite request
Opis
Returns the numeric result code of the most recent failed SQLite request.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns an integer value representing the numeric result code of the most recent failed SQLite request.
SQLite3::lastErrorMsg
(PHP 5 >= 5.3.0)
SQLite3::lastErrorMsg — Returns English text describing the most recent failed SQLite request
Opis
Returns English text describing the most recent failed SQLite request.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns an English string describing the most recent failed SQLite request.
SQLite3::lastInsertRowID
(PHP 5 >= 5.3.0)
SQLite3::lastInsertRowID — Returns the row ID of the most recent INSERT into the database
Opis
Returns the row ID of the most recent INSERT into the database.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the row ID of the most recent INSERT into the database
SQLite3::loadExtension
(PHP 5 >= 5.3.0)
SQLite3::loadExtension — Attempts to load an SQLite extension library
Opis
$shared_library
)Attempts to load an SQLite extension library.
Parametry
-
shared_library -
The name of the library to load. The library must be located in the directory specified in the configure option sqlite3.extension_dir.
Zwracane wartości
Returns TRUE if the extension is successfully loaded, FALSE on failure.
Przykłady
Przykład #1 SQLite3::loadExtension() example
<?php
$db = new SQLite3('mysqlitedb.db');
$db->loadExtension('libagg.so');
?>
SQLite3::open
(PHP 5 >= 5.3.0)
SQLite3::open — Opens an SQLite database
Opis
$filename
[, int $flags = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE
[, string $encryption_key
]] )Opens an SQLite 3 Database. If the build includes encryption, then it will attempt to use the key.
Parametry
-
filename -
Path to the SQLite database, or :memory: to use in-memory database.
-
flags -
Optional flags used to determine how to open the SQLite database. By default, open uses SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE.
-
SQLITE3_OPEN_READONLY: Open the database for reading only.
-
SQLITE3_OPEN_READWRITE: Open the database for reading and writing.
-
SQLITE3_OPEN_CREATE: Create the database if it does not exist.
-
-
encryption_key -
An optional encryption key used when encrypting and decrypting an SQLite database.
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 SQLite3::open() example
<?php
/**
* Simple example of extending the SQLite3 class and changing the __construct
* parameters, then using the open method to initialize the DB.
*/
class MyDB extends SQLite3
{
function __construct()
{
$this->open('mysqlitedb.db');
}
}
$db = new MyDB();
$db->exec('CREATE TABLE foo (bar STRING)');
$db->exec("INSERT INTO foo (bar) VALUES ('This is a test')");
$result = $db->query('SELECT bar FROM foo');
var_dump($result->fetchArray());
?>
SQLite3::prepare
(PHP 5 >= 5.3.0)
SQLite3::prepare — Prepares an SQL statement for execution
Opis
Prepares an SQL statement for execution and returns an SQLite3Stmt object.
Parametry
-
query -
The SQL query to prepare.
Zwracane wartości
Returns an SQLite3Stmt object on success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 SQLite3::prepare() example
<?php
unlink('mysqlitedb.db');
$db = new SQLite3('mysqlitedb.db');
$db->exec('CREATE TABLE foo (id INTEGER, bar STRING)');
$db->exec("INSERT INTO foo (id, bar) VALUES (1, 'This is a test')");
$stmt = $db->prepare('SELECT bar FROM foo WHERE id=:id');
$stmt->bindValue(':id', 1, SQLITE3_INTEGER);
$result = $stmt->execute();
var_dump($result->fetchArray());
?>
SQLite3::query
(PHP 5 >= 5.3.0)
SQLite3::query — Executes an SQL query
Opis
Executes an SQL query, returning an SQLite3Result object if the query returns results.
Parametry
-
query -
The SQL query to execute.
Zwracane wartości
Returns an SQLite3Result object if the query returns results. Otherwise,
returns TRUE if the query succeeded, FALSE on failure.
Przykłady
Przykład #1 SQLite3::query() example
<?php
$db = new SQLite3('mysqlitedb.db');
$results = $db->query('SELECT bar FROM foo');
while ($row = $results->fetchArray()) {
var_dump($row);
}
?>
SQLite3::querySingle
(PHP 5 >= 5.3.0)
SQLite3::querySingle — Executes a query and returns a single result
Opis
Executes a query and returns a single result.
Parametry
-
query -
The SQL query to execute.
-
entire_row -
By default, querySingle() returns the value of the first column returned by the query. If
entire_rowisTRUE, then it returns an array of the entire first row.
Zwracane wartości
Returns the value of the first column of results or an array of the entire
first row (if entire_row is TRUE).
If the query is valid but no results are returned, then NULL will be
returned if entire_row is FALSE, otherwise an
empty array is returned.
Invalid or failing queries will return FALSE.
Przykłady
Przykład #1 SQLite3::querySingle() example
<?php
$db = new SQLite3('mysqlitedb.db');
var_dump($db->querySingle('SELECT username FROM user WHERE userid=1'));
print_r($db->querySingle('SELECT username, email FROM user WHERE userid=1', true));
?>
Powyższy przykład wyświetli coś podobnego do:
string(5) "Scott"
Array
(
[username] => Scott
[email] => scott@example.com
)
SQLite3::version
(PHP 5 >= 5.3.0)
SQLite3::version — Returns the SQLite3 library version as a string constant and as a number
Opis
Returns the SQLite3 library version as a string constant and as a number.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns an associative array with the keys "versionString" and "versionNumber".
Przykłady
Przykład #1 SQLite3::version() example
<?php
print_r(SQLite3::version());
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[versionString] => 3.5.9
[versionNumber] => 3005009
)
Spis treści
- SQLite3::busyTimeout — Sets the busy connection handler
- SQLite3::changes — Returns the number of database rows that were changed (or inserted or deleted) by the most recent SQL statement
- SQLite3::close — Closes the database connection
- SQLite3::__construct — Instantiates an SQLite3 object and opens an SQLite 3 database
- SQLite3::createAggregate — Registers a PHP function for use as an SQL aggregate function
- SQLite3::createFunction — Registers a PHP function for use as an SQL scalar function
- SQLite3::escapeString — Returns a string that has been properly escaped
- SQLite3::exec — Executes a result-less query against a given database
- SQLite3::lastErrorCode — Returns the numeric result code of the most recent failed SQLite request
- SQLite3::lastErrorMsg — Returns English text describing the most recent failed SQLite request
- SQLite3::lastInsertRowID — Returns the row ID of the most recent INSERT into the database
- SQLite3::loadExtension — Attempts to load an SQLite extension library
- SQLite3::open — Opens an SQLite database
- SQLite3::prepare — Prepares an SQL statement for execution
- SQLite3::query — Executes an SQL query
- SQLite3::querySingle — Executes a query and returns a single result
- SQLite3::version — Returns the SQLite3 library version as a string constant and as a number
The SQLite3Stmt class
(No version information available, might only be in SVN)
Wstęp
A class that handles prepared statements for the SQLite 3 extension.
Krótki opis klasy
SQLite3Stmt::bindParam
(PHP 5 >= 5.3.0)
SQLite3Stmt::bindParam — Binds a parameter to a statement variable
Opis
Binds a parameter to a statement variable.
Parametry
-
sql_param -
An string identifying the statement variable to which the parameter should be bound.
-
param -
The parameter to bind to a statement variable.
-
type -
The data type of the parameter to bind.
-
SQLITE3_INTEGER: The value is a signed integer, stored in 1, 2, 3, 4, 6, or 8 bytes depending on the magnitude of the value.
-
SQLITE3_FLOAT: The value is a floating point value, stored as an 8-byte IEEE floating point number.
-
SQLITE3_TEXT: The value is a text string, stored using the database encoding (UTF-8, UTF-16BE or UTF-16-LE).
-
SQLITE3_BLOB: The value is a blob of data, stored exactly as it was input.
-
SQLITE3_NULL: The value is a NULL value.
-
Zwracane wartości
Returns TRUE if the parameter is bound to the statement variable, FALSE
on failure.
SQLite3Stmt::bindValue
(PHP 5 >= 5.3.0)
SQLite3Stmt::bindValue — Binds the value of a parameter to a statement variable
Opis
Binds the value of a parameter to a statement variable.
Parametry
-
sql_param -
An string identifying the statement variable to which the value should be bound.
-
value -
The value to bind to a statement variable.
-
type -
The data type of the value to bind.
-
SQLITE3_INTEGER: The value is a signed integer, stored in 1, 2, 3, 4, 6, or 8 bytes depending on the magnitude of the value.
-
SQLITE3_FLOAT: The value is a floating point value, stored as an 8-byte IEEE floating point number.
-
SQLITE3_TEXT: The value is a text string, stored using the database encoding (UTF-8, UTF-16BE or UTF-16-LE).
-
SQLITE3_BLOB: The value is a blob of data, stored exactly as it was input.
-
SQLITE3_NULL: The value is a NULL value.
-
Zwracane wartości
Returns TRUE if the value is bound to the statement variable, FALSE
on failure.
Przykłady
Przykład #1 SQLite3Stmt::bindValue() example
<?php
unlink('mysqlitedb.db');
$db = new SQLite3('mysqlitedb.db');
$db->exec('CREATE TABLE foo (id INTEGER, bar STRING)');
$db->exec("INSERT INTO foo (id, bar) VALUES (1, 'This is a test')");
$stmt = $db->prepare('SELECT bar FROM foo WHERE id=:id');
$stmt->bindValue(':id', 1, SQLITE3_INTEGER);
$result = $stmt->execute();
var_dump($result->fetchArray());
?>
SQLite3Stmt::clear
(PHP 5 >= 5.3.0)
SQLite3Stmt::clear — Clears all current bound parameters
Opis
Clears all current bound parameters.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns TRUE on successful clearing of bound parameters, FALSE on
failure.
SQLite3Stmt::close
(PHP 5 >= 5.3.0)
SQLite3Stmt::close — Closes the prepared statement
Opis
Closes the prepared statement.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns TRUE
SQLite3Stmt::execute
(PHP 5 >= 5.3.0)
SQLite3Stmt::execute — Executes a prepared statement and returns a result set object
Opis
Executes a prepared statement and returns a result set object.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns an SQLite3Result object on successful execution of the prepared
statement, FALSE on failure.
SQLite3Stmt::paramCount
(PHP 5 >= 5.3.0)
SQLite3Stmt::paramCount — Returns the number of parameters within the prepared statement
Opis
Returns the number of parameters within the prepared statement.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the number of parameters within the prepared statement.
SQLite3Stmt::reset
(PHP 5 >= 5.3.0)
SQLite3Stmt::reset — Resets the prepared statement
Opis
Resets the prepared statement to its state prior to execution. All bindings remain intact after reset.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns TRUE if the statement is successfully reset, FALSE on failure.
Spis treści
- SQLite3Stmt::bindParam — Binds a parameter to a statement variable
- SQLite3Stmt::bindValue — Binds the value of a parameter to a statement variable
- SQLite3Stmt::clear — Clears all current bound parameters
- SQLite3Stmt::close — Closes the prepared statement
- SQLite3Stmt::execute — Executes a prepared statement and returns a result set object
- SQLite3Stmt::paramCount — Returns the number of parameters within the prepared statement
- SQLite3Stmt::reset — Resets the prepared statement
The SQLite3Result class
(No version information available, might only be in SVN)
Wstęp
A class that handles result sets for the SQLite 3 extension.
Krótki opis klasy
SQLite3Result::columnName
(PHP 5 >= 5.3.0)
SQLite3Result::columnName — Returns the name of the nth column
Opis
$column_number
)
Returns the name of the column specified by the
column_number.
Parametry
-
column_number -
The numeric zero-based index of the column.
Zwracane wartości
Returns the string name of the column identified by
column_number.
SQLite3Result::columnType
(PHP 5 >= 5.3.0)
SQLite3Result::columnType — Returns the type of the nth column
Opis
$column_number
)
Returns the type of the column identified by
column_number.
Parametry
-
column_number -
The numeric zero-based index of the column.
Zwracane wartości
Returns the data type index of the column identified by
column_number (one of
SQLITE3_INTEGER, SQLITE3_FLOAT,
SQLITE3_TEXT, SQLITE3_BLOB, or
SQLITE3_NULL).
SQLite3Result::fetchArray
(PHP 5 >= 5.3.0)
SQLite3Result::fetchArray — Fetches a result row as an associative or numerically indexed array or both
Opis
$mode = SQLITE3_BOTH
] )Fetches a result row as an associative or numerically indexed array or both. By default, fetches as both.
Parametry
-
mode -
Controls how the next row will be returned to the caller. This value must be one of either SQLITE3_ASSOC, SQLITE3_NUM, or SQLITE3_BOTH.
-
SQLITE3_ASSOC: returns an array indexed by column name as returned in the corresponding result set
-
SQLITE3_NUM: returns an array indexed by column number as returned in the corresponding result set, starting at column 0
-
SQLITE3_BOTH: returns an array indexed by both column name and number as returned in the corresponding result set, starting at column 0
-
Zwracane wartości
Returns a result row as an associatively or numerically indexed array or both.
SQLite3Result::finalize
(PHP 5 >= 5.3.0)
SQLite3Result::finalize — Closes the result set
Opis
Closes the result set.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns TRUE.
SQLite3Result::numColumns
(PHP 5 >= 5.3.0)
SQLite3Result::numColumns — Returns the number of columns in the result set
Opis
Returns the number of columns in the result set.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the number of columns in the result set.
SQLite3Result::reset
(PHP 5 >= 5.3.0)
SQLite3Result::reset — Resets the result set back to the first row
Opis
Resets the result set back to the first row.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns TRUE if the result set is successfully reset
back to the first row, FALSE on failure.
Spis treści
- SQLite3Result::columnName — Returns the name of the nth column
- SQLite3Result::columnType — Returns the type of the nth column
- SQLite3Result::fetchArray — Fetches a result row as an associative or numerically indexed array or both
- SQLite3Result::finalize — Closes the result set
- SQLite3Result::numColumns — Returns the number of columns in the result set
- SQLite3Result::reset — Resets the result set back to the first row
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- SQLite3 — The SQLite3 class
- SQLite3::busyTimeout — Sets the busy connection handler
- SQLite3::changes — Returns the number of database rows that were changed (or inserted or deleted) by the most recent SQL statement
- SQLite3::close — Closes the database connection
- SQLite3::__construct — Instantiates an SQLite3 object and opens an SQLite 3 database
- SQLite3::createAggregate — Registers a PHP function for use as an SQL aggregate function
- SQLite3::createFunction — Registers a PHP function for use as an SQL scalar function
- SQLite3::escapeString — Returns a string that has been properly escaped
- SQLite3::exec — Executes a result-less query against a given database
- SQLite3::lastErrorCode — Returns the numeric result code of the most recent failed SQLite request
- SQLite3::lastErrorMsg — Returns English text describing the most recent failed SQLite request
- SQLite3::lastInsertRowID — Returns the row ID of the most recent INSERT into the database
- SQLite3::loadExtension — Attempts to load an SQLite extension library
- SQLite3::open — Opens an SQLite database
- SQLite3::prepare — Prepares an SQL statement for execution
- SQLite3::query — Executes an SQL query
- SQLite3::querySingle — Executes a query and returns a single result
- SQLite3::version — Returns the SQLite3 library version as a string constant and as a number
- SQLite3Stmt — The SQLite3Stmt class
- SQLite3Stmt::bindParam — Binds a parameter to a statement variable
- SQLite3Stmt::bindValue — Binds the value of a parameter to a statement variable
- SQLite3Stmt::clear — Clears all current bound parameters
- SQLite3Stmt::close — Closes the prepared statement
- SQLite3Stmt::execute — Executes a prepared statement and returns a result set object
- SQLite3Stmt::paramCount — Returns the number of parameters within the prepared statement
- SQLite3Stmt::reset — Resets the prepared statement
- SQLite3Result — The SQLite3Result class
- SQLite3Result::columnName — Returns the name of the nth column
- SQLite3Result::columnType — Returns the type of the nth column
- SQLite3Result::fetchArray — Fetches a result row as an associative or numerically indexed array or both
- SQLite3Result::finalize — Closes the result set
- SQLite3Result::numColumns — Returns the number of columns in the result set
- SQLite3Result::reset — Resets the result set back to the first row
Microsoft SQL Server Driver for PHP
Wstęp
The SQLSRV extension allows you to access Microsoft SQL Server and SQL Azure databases when running PHP on Windows.
The SQLSRV extension is supported by Microsoft and available for download here: » http://msdn.microsoft.com/en-us/sqlserver/ff657782.aspx.
Instalacja/Konfiguracja
Spis treści
Wymagania
The SQLSRV extension can be used on the following operating systems:
- Windows Server 2003 Service Pack 1
- Windows XP Service Pack 3
- Windows Vista Service Pack 1 or later
- Windows Server 2008
- Windows Server 2008 R2
- Windows 7
The SQLSRV extension requires that the Microsoft SQL Server 2008 R2 Native Client be installed on the same computer that is running PHP. If the Microsoft SQL Server 2008 R2 is not already installed, click the appropriate link below to download it:
The SQLSRV download comes with several driver files. Which driver file you use will depend on 3 factors: the PHP version you are using, whether you are using thread-safe or non-thread-safe PHP, and whether your PHP installation was compiled with the VC6 or VC9 compiler. For example, if you are running PHP 5.3, you are using non-thread-safe PHP, and your PHP installation was compiled with the VC9 compiler, you should use the php_sqlsrv_53_nts_vc9.dll file. (You should use a non-thread-safe version compiled with the VC9 compiler if you are using IIS as your web server). If you are running PHP 5.2, you are using thread-safe PHP, and your PHP installation was compiled with the VC6 compiler, you should use the php_sqlsrv_52_ts_vc6.dll file.
For more information about SQLSRV requirements, see » SQLSRV System Requirements.
Instalacja
The SQLSRV extension is enabled by adding appropriate DLL file to your PHP extension directory and the corresponding entry to the php.ini file. The SQLSRV download comes with several driver files. Which driver file you use will depend on 3 factors: the PHP version you are using, whether you are using thread-safe or non-thread-safe PHP, and whether your PHP installation was compiled with the VC6 or VC9 compiler. For example, if you are running PHP 5.3, you are using non-thread-safe PHP, and your PHP installation was compiled with the VC9 compiler, you should use the php_sqlsrv_53_nts_vc9.dll file. (You should use a non-thread-safe version compiled with the VC9 compiler if you are using IIS as your web server). If you are running PHP 5.2, you are using thread-safe PHP, and your PHP installation was compiled with the VC6 compiler, you should use the php_sqlsrv_52_ts_vc6.dll file.
For more information about SQLSRV requirements, see » SQLSRV System Requirements.
The SQLSRV extension is only compatible with PHP running on Windows.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
The following table lists the configuration options available in the SQLSRV extension. For more information about these options, see » Handling SQLSRV Warnings and Errors.
| Nazwa | Domyślnie | Możliwość zmian | Changelog |
|---|---|---|---|
| sqlsrv.WarningsReturnAsErrors | 1 (TRUE) |
PHP_INI_ALL | Available since SQLSRV 1.0 |
| sqlsrv.LogSubsystems | 0 | PHP_INI_ALL | Available since SQLSRV 1.0 |
| sqlsrv.LogSeverity | 1 | PHP_INI_ALL | Available since SQLSRV 1.0 |
Typy zasobów
Connection resource
A connection resource returned by sqlsrv_connect().
Statement resource
A statement resource returned by sqlsrv_query() or by sqlsrv_prepare().
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
-
SQLSRV_FETCH_ASSOC(integer) - Forces sqlsrv_fetch_array() to return an associative array when passed as a parameter.
-
SQLSRV_FETCH_NUMERIC(integer) - Forces sqlsrv_fetch_array() to return an array with numeric when passed as a parameter.
-
SQLSRV_FETCH_BOTH(integer) - Forces sqlsrv_fetch_array() to return an array with both associative and numeric keys when passed as a parameter (the default behavior).
-
SQLSRV_ERR_ALL(integer) - Forces sqlsrv_errors() to return both errors and warings when passed as a parameter (the default behavior).
-
SQLSRV_ERR_ERRORS(integer) - Forces sqlsrv_errors() to return errors only (no warnings) when passed as a parameter.
-
SQLSRV_ERR_WARNINGS(integer) - Forces sqlsrv_errors() to return warnings only (no errors) when passed as a parameter.
-
SQLSRV_LOG_SYSTEM_ALL(integer) - Turns on logging of all subsystems when passed to sqlsrv_configure() as a parameter.
-
SQLSRV_LOG_SYSTEM_CONN(integer) - Turns on logging of connection activity when passed to sqlsrv_configure() as a parameter.
-
SQLSRV_LOG_SYSTEM_INIT(integer) - Turns on logging of initialization activity when passed to sqlsrv_configure() as a parameter.
-
SQLSRV_LOG_SYSTEM_OFF(integer) - Turns off logging of all subsystems when passed to sqlsrv_configure() as a parameter.
-
SQLSRV_LOG_SYSTEM_STMT(integer) - Turns on logging of statement activity when passed to sqlsrv_configure() as a parameter.
-
SQLSRV_LOG_SYSTEM_UTIL(integer) - Turns on logging of error function activity when passed to sqlsrv_configure() as a parameter.
-
SQLSRV_LOG_SEVERITY_ALL(integer) - Specifies that errors, warnings, and notices will be logged when passed to sqlsrv_configure() as a parameter.
-
SQLSRV_LOG_SEVERITY_ERROR(integer) - Specifies that errors will be logged when passed to sqlsrv_configure() as a parameter.
-
SQLSRV_LOG_SEVERITY_NOTICE(integer) - Specifies that notices will be logged when passed to sqlsrv_configure() as a parameter.
-
SQLSRV_LOG_SEVERITY_WARNING(integer) - Specifies that warnings will be logged when passed to sqlsrv_configure() as a parameter.
-
SQLSRV_NULLABLE_YES(integer) - Indicates that a column is nullable.
-
SQLSRV_NULLABLE_NO(integer) - Indicates that a column is not nullable.
-
SQLSRV_NULLABLE_UNKNOWN(integer) - Indicates that it is not known if a column is nullable.
-
SQLSRV_PARAM_IN(integer) - Indicates an input parameter when passed to sqlsrv_query() or sqlsrv_prepare().
-
SQLSRV_PARAM_INOUT(integer) - Indicates a bidirectional parameter when passed to sqlsrv_query() or sqlsrv_prepare().
-
SQLSRV_PARAM_OUT(integer) - Indicates an output parameter when passed to sqlsrv_query() or sqlsrv_prepare().
-
SQLSRV_PHPTYPE_INT(integer) - Specifies an integer PHP data type. For usage information, see » How to: Specify PHP Types.
-
SQLSRV_PHPTYPE_DATETIME(integer) - Specifies a datetime PHP data type. For usage information, see » How to: Specify PHP Types.
-
SQLSRV_PHPTYPE_FLOAT(integer) - Specifies a float PHP data type. For usage information, see » How to: Specify PHP Types.
-
SQLSRV_PHPTYPE_STREAM(integer) - Specifies a PHP stream. This constant works like a function and accepts an encoding constant. See the SQLSRV_ENC_* constants. For usage information, see » How to: Specify PHP Types.
-
SQLSRV_PHPTYPE_STRING(integer) - Specifies a string PHP data type. This constant works like a function and accepts an encoding constant. See the SQLSRV_ENC_* constants. For usage information, see » How to: Specify PHP Types.
-
SQLSRV_ENC_BINARY(integer) - Specifies that data is returned as a raw byte stream from the server without performing encoding or translation. For usage information, see » How to: Specify PHP Types.
-
SQLSRV_ENC_CHAR(integer) - Data is returned in 8-bit characters as specified in the code page of the Windows locale that is set on the system. Any multi-byte characters or characters that do not map into this code page are substituted with a single byte question mark (?) character. This is the default encoding. For usage information, see » How to: Specify PHP Types.
-
UTF-8(integer) - Specifies that data is returned with UTF-8 encoding. For usage information, see » How to: Specify PHP Types.
-
SQLSRV_SQLTYPE_BIGINT(integer) - Describes the bigint SQL Server data type. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_BINARY(integer) - Describes the binary SQL Server data type. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_BIT(integer) - Describes the bit SQL Server data type. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_CHAR(integer) - Describes the char SQL Server data type. This constant works like a function and accepts a parameter indicating the number characters. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_DATE(integer) - Describes the date SQL Server data type. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_DATETIME(integer) - Describes the datetime SQL Server data type. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_DATETIME2(integer) - Describes the datetime2 SQL Server data type. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_DATETIMEOFFSET(integer) - Describes the datetimeoffset SQL Server data type. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_DECIMAL(integer) - Describes the decimal SQL Server data type. This constant works like a function and accepts two parameters indicating (in order) precision and scale. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_FLOAT(integer) - Describes the float SQL Server data type. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_IMAGE(integer) - Describes the image SQL Server data type. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_INT(integer) - Describes the int SQL Server data type. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_MONEY(integer) - Describes the money SQL Server data type. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_NCHAR(integer) - Describes the nchar SQL Server data type. This constant works like a function and accepts a single parameter indicating the character count. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_NUMERIC(integer) - Describes the numeric SQL Server data type. This constant works like a function and accepts two parameter indicating (in order) precision and scale. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_NVARCHAR(integer) - Describes the nvarchar SQL Server data type. This constant works like a function and accepts a single parameter indicating the character count. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_NVARCHAR('max') (integer) - Describes the nvarchar(MAX) SQL Server data type. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_NTEXT(integer) - Describes the ntext SQL Server data type. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_REAL(integer) - Describes the real SQL Server data type. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_SMALLDATETIME(integer) - Describes the smalldatetime SQL Server data type. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_SMALLINT(integer) - Describes the smallint SQL Server data type. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_SMALLMONEY(integer) - Describes the smallmoney SQL Server data type. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_TEXT(integer) - Describes the text SQL Server data type. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_TIME(integer) - Describes the time SQL Server data type. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_TIMESTAMP(integer) - Describes the timestamp SQL Server data type. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_TINYINT(integer) - Describes the tinyint SQL Server data type. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_UNIQUEIDENTIFIER(integer) - Describes the uniqueidentifier SQL Server data type. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_UDT(integer) - Describes the UDT SQL Server data type. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_VARBINARY(integer) - Describes the varbinary SQL Server data type. This constant works like a function and accepts a single parameter indicating the byte count. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_VARBINARY('max') (integer) - Describes the varbinary(MAX) SQL Server data type. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_VARCHAR(integer) - Describes the varchar SQL Server data type. This constant works like a function and accepts a single parameter indicating the character count. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_VARCHAR('max') (integer) - Describes the varchar(MAX) SQL Server data type. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_SQLTYPE_XML(integer) - Describes the XML SQL Server data type. For usage information, see » How to: Specify SQL Types.
-
SQLSRV_TXN_READ_UNCOMMITTED(integer) - Inidicates a transaction isolation level of READ UNCOMMITTED. This value is used to set the TransactionIsolation level in the $connectionOptions arrary passed to sqlsrv_connect().
-
SQLSRV_TXN_READ_COMMITTED(integer) - Inidicates a transaction isolation level of READ COMMITTED. This value is used to set the TransactionIsolation level in the $connectionOptions arrary passed to sqlsrv_connect().
-
SQLSRV_TXN_REPEATABLE_READ(integer) - Inidicates a transaction isolation level of REPEATABLE READ. This value is used to set the TransactionIsolation level in the $connectionOptions arrary passed to sqlsrv_connect().
-
SQLSRV_TXN_SNAPSHOT(integer) - Inidicates a transaction isolation level of SNAPSHOT. This value is used to set the TransactionIsolation level in the $connectionOptions arrary passed to sqlsrv_connect().
-
SQLSRV_TXN_READ_SERIALIZABLE(integer) - Inidicates a transaction isolation level of SERIALIZABLE. This value is used to set the TransactionIsolation level in the $connectionOptions arrary passed to sqlsrv_connect().
-
SQLSRV_CURSOR_FORWARD(integer) - Inidicates a forward-only cursor. For usage information, see » How to: Specify a Cursor Type.
-
SQLSRV_CURSOR_STATIC(integer) - Inidicates a static cursor. For usage information, see » How to: Specify a Cursor Type.
-
SQLSRV_DYNAMIC(integer) - Inidicates a dynamic cursor. For usage information, see » How to: Specify a Cursor Type.
-
SQLSRV_CURSOR_KEYSET(integer) - Inidicates a keyset cursor. For usage information, see » How to: Specify a Cursor Type.
-
SQLSRV_SCROLL_NEXT(integer) - Specifies which row to select in a result set. For usage information, see » How to: Specify a Cursor Type and Select Rows.
-
SQLSRV_SCROLL_PRIOR(integer) - Specifies which row to select in a result set. For usage information, see » How to: Specify a Cursor Type and Select Rows.
-
SQLSRV_SCROLL_FIRST(integer) - Specifies which row to select in a result set. For usage information, see » How to: Specify a Cursor Type and Select Rows.
-
SQLSRV_SCROLL_LAST(integer) - Specifies which row to select in a result set. For usage information, see » How to: Specify a Cursor Type and Select Rows.
-
SQLSRV_SCROLL_ABSOLUTE(integer) - Specifies which row to select in a result set. For usage information, see » How to: Specify a Cursor Type and Select Rows.
-
SQLSRV_SCROLL_RELATIVE(integer) - Specifies which row to select in a result set. For usage information, see » How to: Specify a Cursor Type and Select Rows.
SQLSRV Funkcje
sqlsrv_begin_transaction
(No version information available, might only be in SVN)
sqlsrv_begin_transaction — Begins a database transaction
Opis
$conn
)The transaction begun by sqlsrv_begin_transaction() includes all statements that were executed after the call to sqlsrv_begin_transaction() and before calls to sqlsrv_rollback() or sqlsrv_commit(). Explicit transactions should be started and committed or rolled back using these functions instead of executing SQL statements that begin and committ/roll back transactions. For more information, see » SQLSRV Transactions.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 sqlsrv_begin_transaction() example
The following example demonstrates how to use sqlsrv_begin_transaction() together with sqlsrv_commit() and sqlsrv_rollback().
<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true ));
}
/* Begin the transaction. */
if ( sqlsrv_begin_transaction( $conn ) === false ) {
die( print_r( sqlsrv_errors(), true ));
}
/* Initialize parameter values. */
$orderId = 1; $qty = 10; $productId = 100;
/* Set up and execute the first query. */
$sql1 = "INSERT INTO OrdersTable (ID, Quantity, ProductID)
VALUES (?, ?, ?)";
$params1 = array( $orderId, $qty, $productId );
$stmt1 = sqlsrv_query( $conn, $sql1, $params1 );
/* Set up and execute the second query. */
$sql2 = "UPDATE InventoryTable
SET Quantity = (Quantity - ?)
WHERE ProductID = ?";
$params2 = array($qty, $productId);
$stmt2 = sqlsrv_query( $conn, $sql2, $params2 );
/* If both queries were successful, commit the transaction. */
/* Otherwise, rollback the transaction. */
if( $stmt1 && $stmt2 ) {
sqlsrv_commit( $conn );
echo "Transaction committed.<br />";
} else {
sqlsrv_rollback( $conn );
echo "Transaction rolled back.<br />";
}
?>
Powyższy przykład wyświetli coś podobnego do:
Zobacz też:
- sqlsrv_commit() - Commits a transaction that was begun with sqlsrv_begin_transaction
- sqlsrv_rollback() - Rolls back a transaction that was begun with sqlsrv_begin_transaction
sqlsrv_cancel
(No version information available, might only be in SVN)
sqlsrv_cancel — Cancels a statement
Opis
$stmt
)Cancels a statement. Any results associated with the statement that have not been consumed are deleted. After sqlsrv_cancel() has been called, the specified statement can be re-executed if it was created with sqlsrv_prepare(). Calling sqlsrv_cancel() is not necessary if all the results associated with the statement have been consumed.
Parametry
-
stmt -
The statement resource to be cancelled.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 sqlsrv_cancel() example
<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}
$sql = "SELECT Sales FROM Table_1";
$stmt = sqlsrv_prepare( $conn, $sql);
if( $stmt === false ) {
die( print_r( sqlsrv_errors(), true));
}
if( sqlsrv_execute( $stmt ) === false) {
die( print_r( sqlsrv_errors(), true));
}
$salesTotal = 0;
$count = 0;
while( ($row = sqlsrv_fetch_array( $stmt)) && $salesTotal <=100000)
{
$qty = $row[0];
$price = $row[1];
$salesTotal += ( $price * $qty);
$count++;
}
echo "$count sales accounted for the first $$salesTotal in revenue.<br />";
// Cancel the pending results. The statement can be reused.
sqlsrv_cancel( $stmt);
?>
Notatki
The main difference between sqlsrv_cancel() and sqlsrv_free_stmt() is that a statement resource cancelled with sqlsrv_cancel() can be re-executed if it was created with sqlsrv_prepare(). A statement resource cancelled with sqlsrv_free_statement() cannot be re-executed.
Zobacz też:
- sqlsrv_free_stmt() - Frees all resources for the specified statement
- sqlsrv_prepare() - Prepares a query for execution
sqlsrv_client_info
(No version information available, might only be in SVN)
sqlsrv_client_info — Returns information about the client and specified connection
Opis
$conn
)Returns information about the client and specified connection
Parametry
-
conn -
The connection about which information is returned.
Zwracane wartości
Returns an associative array with keys described in the table below.
Returns FALSE otherwise.
| Key | Description |
|---|---|
| DriverDllName | SQLNCLI10.DLL |
| DriverODBCVer | ODBC version (xx.yy) |
| DriverVer | SQL Server Native Client DLL version (10.5.xxx) |
| ExtensionVer | php_sqlsrv.dll version (2.0.xxx.x) |
Przykłady
Przykład #1 sqlsrv_client_info() example
<?php
$serverName = "serverName\sqlexpress";
$connOptions = array("UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connOptions );
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}
if( $client_info = sqlsrv_client_info( $conn)) {
foreach( $client_info as $key => $value) {
echo $key.": ".$value."<br />";
}
} else {
echo "Error in retrieving client info.<br />";
}
?>
sqlsrv_close
(No version information available, might only be in SVN)
sqlsrv_close — Closes an open connection and releases resourses associated with the connection
Opis
$conn
)Closes an open connection and releases resourses associated with the connection.
Parametry
-
conn -
The connection to be closed.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 sqlsrv_close() example
<?php
$serverName = "serverName\sqlexpres";
$connOptions = array("UID"=>"username", "PWD"=>"password", "Database"=>"dbname");
$conn = sqlsrv_connect( $serverName, $connOptions );
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}
//-------------------------------------
// Perform database operations here.
//-------------------------------------
// Close the connection.
sqlsrv_close( $conn );
?>
sqlsrv_commit
(No version information available, might only be in SVN)
sqlsrv_commit — Commits a transaction that was begun with sqlsrv_begin_transaction()
Opis
$conn
)Commits a transaction that was begun with sqlsrv_begin_transaction(). The connection is returned to auto-commit mode after sqlsrv_commit() is called. The transaction that is committed includes all statements that were executed after the call to sqlsrv_begin_transaction(). Explicit transactions should be started and committed or rolled back using these functions instead of executing SQL statements that begin and committ/roll back transactions. For more information, see » SQLSRV Transactions.
Parametry
-
conn -
The connection on which the transaction is to be committed.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 sqlsrv_commit() example
The following example demonstrates how to use sqlsrv_commit() together with sqlsrv_begin_transaction() and sqlsrv_rollback().
<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true ));
}
/* Begin the transaction. */
if ( sqlsrv_begin_transaction( $conn ) === false ) {
die( print_r( sqlsrv_errors(), true ));
}
/* Initialize parameter values. */
$orderId = 1; $qty = 10; $productId = 100;
/* Set up and execute the first query. */
$sql1 = "INSERT INTO OrdersTable (ID, Quantity, ProductID)
VALUES (?, ?, ?)";
$params1 = array( $orderId, $qty, $productId );
$stmt1 = sqlsrv_query( $conn, $sql1, $params1 );
/* Set up and execute the second query. */
$sql2 = "UPDATE InventoryTable
SET Quantity = (Quantity - ?)
WHERE ProductID = ?";
$params2 = array($qty, $productId);
$stmt2 = sqlsrv_query( $conn, $sql2, $params2 );
/* If both queries were successful, commit the transaction. */
/* Otherwise, rollback the transaction. */
if( $stmt1 && $stmt2 ) {
sqlsrv_commit( $conn );
echo "Transaction committed.<br />";
} else {
sqlsrv_rollback( $conn );
echo "Transaction rolled back.<br />";
}
?>
Zobacz też:
- sqlsrv_begin_transaction() - Begins a database transaction
- sqlsrv_rollback() - Rolls back a transaction that was begun with sqlsrv_begin_transaction
sqlsrv_configure
(No version information available, might only be in SVN)
sqlsrv_configure — Changes the driver error handling and logging configurations
Opis
Changes the driver error handling and logging configurations.
Parametry
-
setting -
The name of the setting to set. The possible values are "WarningsReturnAsErrors", "LogSubsystems", and "LogSeverity".
-
value -
The value of the specified setting. The following table shows possible values:
Error and Logging Setting Options Setting Options WarningsReturnAsErrors 1 ( TRUE) or 0 (FALSE)LogSubsystems SQLSRV_LOG_SYSTEM_ALL (-1) SQLSRV_LOG_SYSTEM_CONN (2) SQLSRV_LOG_SYSTEM_INIT (1) SQLSRV_LOG_SYSTEM_OFF (0) SQLSRV_LOG_SYSTEM_STMT (4) SQLSRV_LOG_SYSTEM_UTIL (8) LogSeverity SQLSRV_LOG_SEVERITY_ALL (-1) SQLSRV_LOG_SEVERITY_ERROR (1) SQLSRV_LOG_SEVERITY_NOTICE (4) SQLSRV_LOG_SEVERITY_WARNING (2)
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
sqlsrv_connect
(No version information available, might only be in SVN)
sqlsrv_connect — Opens a connection to a Microsoft SQL Server database
Opis
$serverName
[, array $connectionInfo
] )Opens a connection to a Microsoft SQL Server database. By default, the connection is attempted using Windows Authentication. To connect using SQL Server Authentication, include "UID" and "PWD" in the connection options array.
Parametry
-
serverName -
The name of the server to which a connection is established. To connect to a specific instance, follow the server name with a forward slash and the instance name (e.g. serverName\sqlexpress).
-
connectionInfo -
An associative array that specifies options for connecting to the server. If values for the UID and PWD keys are not specified, the connection will be attempted using Windows Authentication. For a complete list of supported keys, see » SQLSRV Connection Options.
Zwracane wartości
A connection resource. If a connection cannot be successfully opened, FALSE is returned.
Przykłady
Przykład #1 Connect using Windows Authentication.
<?php
$serverName = "serverName\sqlexpress"; //serverName\instanceName
// Since UID and PWD are not specified in the $connectionInfo array,
// The connection will be attempted using Windows Authentication.
$connectionInfo = array( "Database"=>"dbName");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn ) {
echo "Connection established.<br />";
}else{
echo "Connection could not be established.<br />";
die( print_r( sqlsrv_errors(), true));
}
?>
Przykład #2 Connect by specifying a user name and password.
<?php
$serverName = "serverName\sqlexpress"; //serverName\instanceName
$connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn ) {
echo "Connection established.<br />";
}else{
echo "Connection could not be established.<br />";
die( print_r( sqlsrv_errors(), true));
}
?>
Przykład #3 Connect on a specifed port.
<?php
$serverName = "serverName\sqlexpress, 1542"; //serverName\instanceName, portNumber (default is 1433)
$connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn ) {
echo "Connection established.<br />";
}else{
echo "Connection could not be established.<br />";
die( print_r( sqlsrv_errors(), true));
}
?>
Notatki
By default, the sqlsrv_connect() uses connection pooling to
improve connection performance. To turn off connection pooling (i.e. force a
new connection on each call), set the "ConnectionPooling" option in the
$connectionOptions array to 0 (or FALSE). For more information, see
» SQLSRV Connection Pooling.
The SQLSRV extension does not have a dedicated function for changing which database is connected to. The target database is specified in the $connectionOptions array that is passed to sqlsrv_connect. To change the database on an open connection, execute the following query "USE dbName" (e.g. sqlsrv_query($conn, "USE dbName")).
Zobacz też:
- sqlsrv_close() - Closes an open connection and releases resourses associated with the connection
- sqlsrv_errors() - Returns error and warning information about the last SQLSRV operation performed
- sqlsrv_query() - Prepares and executes a query.
sqlsrv_errors
(No version information available, might only be in SVN)
sqlsrv_errors — Returns error and warning information about the last SQLSRV operation performed
Opis
Returns error and warning information about the last SQLSRV operation performed.
Parametry
-
errorsOrWarnings -
Determines whether error information, warning information, or both are returned. If this parameter is not supplied, both error information and warning information are returned. The following are the supported values for this parameter: SQLSRV_ERR_ALL, SQLSRV_ERR_ERRORS, SQLSRV_ERR_WARNINGS.
Zwracane wartości
If errors and/or warnings occured on the last sqlsrv operation, and array of
arrays containing error information is returned. If no errors and/or warnings
occured on the last sqlsrv operation, NULL is returned. The following table
describes the structure of the returned arrays:
| Key | Description |
|---|---|
| SQLSTATE | For errors that originate from the ODBC driver, the SQLSTATE returned by ODBC. For errors that originate from the Microsoft Drivers for PHP for SQL Server, a SQLSTATE of IMSSP. For warnings that originate from the Microsoft Drivers for PHP for SQL Server, a SQLSTATE of 01SSP. |
| code | For errors that originate from SQL Server, the native SQL Server error code. For errors that originate from the ODBC driver, the error code returned by ODBC. For errors that originate from the Microsoft Drivers for PHP for SQL Server, the Microsoft Drivers for PHP for SQL Server error code. |
| message | A description of the error. |
Przykłady
Przykład #1 functionname() example
<?php
$serverName = "serverName/sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}
/* Set up a query to select an invalid column name. */
$sql = "SELECT BadColumnName FROM Table_1";
/* Execution of the query will fail because of the bad column name. */
$stmt = sqlsrv_query( $conn, $sql );
if( $stmt === false ) {
if( ($errors = sqlsrv_errors() ) != null) {
foreach( $errors as $error ) {
echo "SQLSTATE: ".$error[ 'SQLSTATE']."<br />";
echo "code: ".$error[ 'code']."<br />";
echo "message: ".$error[ 'message']."<br />";
}
}
}
?>
Notatki
By default, warnings generated on a call to any SQLSRV function are treated
as errors. This means that if a warning occurs on a call to a SQLSRV function,
the function returns FALSE. However, warnings that correspond to SQLSTATE
values 01000, 01001, 01003, and 01S02 are never treated as errors. For
information about changing this behavior, see sqlsrv_configure()
and the WarningsReturnAsErrors setting.
sqlsrv_execute
(No version information available, might only be in SVN)
sqlsrv_execute — Executes a statement prepared with sqlsrv_prepare()
Opis
$stmt
)Executes a statement prepared with sqlsrv_prepare(). This function is ideal for executing a prepared statement multiple times with different parameter values.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 sqlsrv_execute() example
This example demonstrates how to prepare a statement with sqlsrv_prepare() and re-execute it multiple times (with different parameter values) using sqlsrv_execute().
<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false) {
die( print_r( sqlsrv_errors(), true));
}
$sql = "UPDATE Table_1
SET OrderQty = ?
WHERE SalesOrderID = ?";
// Initialize parameters and prepare the statement.
// Variables $qty and $id are bound to the statement, $stmt.
$qty = 0; $id = 0;
$stmt = sqlsrv_prepare( $conn, $sql, array( &$qty, &$id));
if( !$stmt ) {
die( print_r( sqlsrv_errors(), true));
}
// Set up the SalesOrderDetailID and OrderQty information.
// This array maps the order ID to order quantity in key=>value pairs.
$orders = array( 1=>10, 2=>20, 3=>30);
// Execute the statement for each order.
foreach( $orders as $id => $qty) {
// Because $id and $qty are bound to $stmt1, their updated
// values are used with each execution of the statement.
if( sqlsrv_execute( $stmt ) === false ) {
die( print_r( sqlsrv_errors(), true));
}
}
?>
Notatki
When you prepare a statement that uses variables as parameters, the variables are bound to the statement. This means that if you update the values of the variables, the next time you execute the statement it will run with updated parameter values. For statements that you plan to execute only once, use sqlsrv_query().
Zobacz też:
- sqlsrv_prepare() - Prepares a query for execution
- sqlsrv_query() - Prepares and executes a query.
sqlsrv_fetch_array
(No version information available, might only be in SVN)
sqlsrv_fetch_array — Returns a row as an array
Opis
$stmt
[, int $fetchType
[, int $row
[, int $offset
]]] )Returns the next available row of data as an associative array, a numeric array, or both (the default).
Parametry
-
stmt -
A statement resource returned by sqlsrv_query or sqlsrv_execute.
-
fetchType -
A predefined constant specifying the type of array to return. Possible values are
SQLSRV_FETCH_ASSOC,SQLSRV_FETCH_NUMERIC, andSQLSRV_FETCH_BOTH(the default).A fetch type of SQLSRV_FETCH_ASSOC should not be used when consuming a result set with multiple columns of the same name.
-
row -
Specifies the row to access in a result set that uses a scrollable cursor. Possible values are
SQLSRV_SCROLL_NEXT,SQLSRV_SCROLL_PRIOR,SQLSRV_SCROLL_FIRST,SQLSRV_SCROLL_LAST,SQLSRV_SCROLL_ABSOLUTEand,SQLSRV_SCROLL_RELATIVE(the default). When this parameter is specified, thefetchTypemust be explicitly defined.
Zwracane wartości
Returns an array on success, NULL if there are no more rows to return, and
FALSE if an error occurs.
Przykłady
Przykład #1 Retrieving an associative array.
<?php
$serverName = "serverName\instanceName";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo );
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}
$sql = "SELECT FirstName, LastName FROM SomeTable";
$stmt = sqlsrv_query( $conn, $sql );
if( $stmt === false) {
die( print_r( sqlsrv_errors(), true) );
}
while( $row = sqlsrv_fetch_array( $stmt, SQLSRV_FETCH_ASSOC) ) {
echo $row['LastName'].", ".$row['FirstName']."<br />";
}
sqlsrv_free_stmt( $stmt);
?>
Przykład #2 Retrieving a numeric array.
<?php
$serverName = "serverName\instanceName";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo );
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}
$sql = "SELECT FirstName, LastName FROM SomeTable";
$stmt = sqlsrv_query( $conn, $sql );
if( $stmt === false) {
die( print_r( sqlsrv_errors(), true) );
}
while( $row = sqlsrv_fetch_array( $stmt, SQLSRV_FETCH_NUMERIC) ) {
echo $row[0].", ".$row[1]."<br />";
}
sqlsrv_free_stmt( $stmt);
?>
Notatki
Not specifying the fetchType or explicity using the
SQLSRV_FETCH_TYPE constant in the examples above will
return an array that has both associative and numeric keys.
If more than one column is returned with the same name, the last column will take precedence. To avoid field name collisions, use aliases.
If a column with no name is returned, the associative key for the array element will be an empty string ("").
Zobacz też:
- sqlsrv_connect() - Opens a connection to a Microsoft SQL Server database
- sqlsrv_query() - Prepares and executes a query.
- sqlsrv_errors() - Returns error and warning information about the last SQLSRV operation performed
- sqlsrv_fetch() - Makes the next row in a result set available for reading
sqlsrv_fetch_object
(No version information available, might only be in SVN)
sqlsrv_fetch_object — Retrieves the next row of data in a result set as an object
Opis
$stmt
[, string $className
[, array $ctorParams
[, int $row
[, int $offset
]]]] )Retrieves the next row of data in a result set as an instance of the specified class with properties that match the row field names and values that correspond to the row field values.
Parametry
-
stmt -
A statement resource created by sqlsrv_query() or sqlsrv_execute().
-
className -
The name of the class to instantiate. If no class name is specified, stdClass is instantiated.
-
ctorParams -
Values passed to the constructor of the specified class. If the constructor of the specified class takes parameters, the ctorParams array must be supplied.
-
row -
The row to be accessed. This parameter can only be used if the specified statement was prepared with a scrollable cursor. In that case, this parameter can take on one of the following values:
- SQLSRV_SCROLL_NEXT
- SQLSRV_SCROLL_PRIOR
- SQLSRV_SCROLL_FIRST
- SQLSRV_SCROLL_LAST
- SQLSRV_SCROLL_ABSOLUTE
- SQLSRV_SCROLL_RELATIVE
-
offset -
Specifies the row to be accessed if the row parameter is set to SQLSRV_SCROLL_ABSOLUTE or SQLSRV_SCROLL_RELATIVE. Note that the first row in a result set has index 0.
Zwracane wartości
Returns an object on success, NULL if there are no more rows to return,
and FALSE if an error occurs or if the specified class does not exist.
Przykłady
Przykład #1 sqlsrv_fetch_object() example
The following example demonstrates how to retrieve a row as a stdClass object.
<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}
$sql = "SELECT fName, lName FROM Table_1";
$stmt = sqlsrv_query( $conn, $sql);
if( $stmt === false ) {
die( print_r( sqlsrv_errors(), true));
}
// Retrieve each row as an object.
// Because no class is specified, each row will be retrieved as a stdClass object.
// Property names correspond to field names.
while( $obj = sqlsrv_fetch_object( $stmt)) {
echo $obj->fName.", ".$obj->lName."<br />";
}
?>
Notatki
If a class name is specified with the optional $className parameter and the class has properties whose names match the result set field names, the corresponding result set values are applied to the properties. If a result set field name does not match a class property, a property with the result set field name is added to the object and the result set value is applied to the property. The following rules apply when using the $className parameter:
- Field-property name matching is case-sensitive.
- Field-property matching occurs regardless of access modifiers.
- Class property data types are ignored when applying a field value to a property.
- If the class does not exist, the function returns
FALSEand adds an error to the error collection.
When consuming a result set that has multiple columns with the same name, it may be better to use sqlsrv_fetch_array() or the combination of sqlsrv_fetch() and sqlsrv_get_field().
Zobacz też:
- sqlsrv_fetch() - Makes the next row in a result set available for reading
- sqlsrv_fetch_array() - Returns a row as an array
sqlsrv_fetch
(No version information available, might only be in SVN)
sqlsrv_fetch — Makes the next row in a result set available for reading
Opis
Makes the next row in a result set available for reading. Use sqlsrv_get_field() to read the fields of the row.
Parametry
-
stmt -
A statement resource created by executing sqlsrv_query() or sqlsrv_execute().
-
row -
The row to be accessed. This parameter can only be used if the specified statement was prepared with a scrollable cursor. In that case, this parameter can take on one of the following values:
- SQLSRV_SCROLL_NEXT
- SQLSRV_SCROLL_PRIOR
- SQLSRV_SCROLL_FIRST
- SQLSRV_SCROLL_LAST
- SQLSRV_SCROLL_ABSOLUTE
- SQLSRV_SCROLL_RELATIVE
-
offset -
Specifies the row to be accessed if the row parameter is set to SQLSRV_SCROLL_ABSOLUTE or SQLSRV_SCROLL_RELATIVE. Note that the first row in a result set has index 0.
Zwracane wartości
Returns TRUE if the next row of a result set was successfully retrieved,
FALSE if an error occurs, and NULL if there are no more rows in the result set.
Przykłady
Przykład #1 sqlsrv_fetch() example
The following example demonstrates how to retrieve a row with sqlsrv_fetch() and get the row fields with sqlsrv_get_field().
<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}
$sql = "SELECT Name, Comment
FROM Table_1
WHERE ReviewID=1";
$stmt = sqlsrv_query( $conn, $sql);
if( $stmt === false ) {
die( print_r( sqlsrv_errors(), true));
}
// Make the first (and in this case, only) row of the result set available for reading.
if( sqlsrv_fetch( $stmt ) === false) {
die( print_r( sqlsrv_errors(), true));
}
// Get the row fields. Field indeces start at 0 and must be retrieved in order.
// Retrieving row fields by name is not supported by sqlsrv_get_field.
$name = sqlsrv_get_field( $stmt, 0);
echo "$name: ";
$comment = sqlsrv_get_field( $stmt, 1);
echo $comment;
?>
Zobacz też:
- sqlsrv_get_field() - Gets field data from the currently selected row
- sqlsrv_fetch_array() - Returns a row as an array
- sqlsrv_fetch_object() - Retrieves the next row of data in a result set as an object
sqlsrv_field_metadata
(No version information available, might only be in SVN)
sqlsrv_field_metadata — Retrieves metadata for the fields of a statement prepared by sqlsrv_prepare() or sqlsrv_query()
Opis
Retrieves metadata for the fields of a statement prepared by sqlsrv_prepare() or sqlsrv_query(). sqlsrv_field_metadata() can be called on a statement before or after statement execution.
Parametry
-
stmt -
The statment resource for which metadata is returned.
Zwracane wartości
Returns an array of arrays is returned on success. Otherwise, FALSE is returned.
Each returned array is described by the following table:
| Key | Description |
|---|---|
| Name | The name of the field. |
| Type | The numeric value for the SQL type. |
| Size | The number of characters for fields of character type, the number of
bytes for fields of binary type, or NULL for other types. |
| Precision | The precision for types of variable precision, NULL for other types. |
| Scale | The scale for types of variable scale, NULL for other types. |
| Nullable | An enumeration indicating whether the column is nullable, not nullable, or if it is not known. |
Przykłady
Przykład #1 sqlsrv_field_metadata() example
<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"AdventureWorks", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}
$sql = "SELECT * FROM Table_1";
$stmt = sqlsrv_prepare( $conn, $sql );
foreach( sqlsrv_field_metadata( $stmt ) as $fieldMetadata ) {
foreach( $fieldMetadata as $name => $value) {
echo "$name: $value<br />";
}
echo "<br />";
}
?>
sqlsrv_free_stmt
(No version information available, might only be in SVN)
sqlsrv_free_stmt — Frees all resources for the specified statement
Opis
$stmt
)Frees all resources for the specified statement. The statement cannot be used after sqlsrv_free_stmt() has been called on it. If sqlsrv_free_stmt() is called on an in-progress statement that alters server state, statement execution is terminated and the statement is rolled back.
Parametry
-
stmt -
The statment for which resources are freed. Note that
NULLis a valid parameter value. This allows the function to be called multiple times in a script.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 sqlsrv_free_stmt() example
<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}
$stmt = sqlsrv_query( $conn, "SELECT * FROM Table_1");
if( $stmt === false ) {
die( print_r( sqlsrv_errors(), true));
}
/*-------------------------------
Process query results here.
-------------------------------*/
/* Free the statement resources. */
sqlsrv_free_stmt( $stmt);
?>
Notatki
The main difference between sqlsrv_free_stmt() and sqlsrv_cancel() is that a statement resource cancelled with sqlsrv_cancel() can be re-executed if it was created with sqlsrv_prepare(). A statement resource cancelled with sqlsrv_free_statement() cannot be re-executed.
sqlsrv_get_config
(No version information available, might only be in SVN)
sqlsrv_get_config — Returns the value of the specified configuration setting
Opis
Returns the value of the specified configuration setting.
Parametry
-
setting -
The name of the setting for which the value is returned. For a list of configurable settings, see sqlsrv_configure().
Zwracane wartości
Returns the value of the specified setting. If an invalid setting is specified,
FALSE is returned.
sqlsrv_get_field
(No version information available, might only be in SVN)
sqlsrv_get_field — Gets field data from the currently selected row
Opis
Gets field data from the currently selected row. Fields must be accessed in order. Field indices start at 0.
Parametry
-
stmt -
A statement resource returned by sqlsrv_query() or sqlsrv_execute().
-
fieldIndex -
The index of the field to be retrieved. Field indices start at 0. Fields must be accessed in order. i.e. If you access field index 1, then field index 0 will not be available.
-
getAsType -
The PHP data type for the returned field data. If this parameter is not set, the field data will be returned as its default PHP data type. For information about default PHP data types, see » Default PHP Data Types in the Microsoft SQLSRV documentation.
Zwracane wartości
Returns data from the specified field on success. Returns FALSE otherwise.
Przykłady
Przykład #1 sqlsrv_get_field() example
The following example demonstrates how to retrieve a row with sqlsrv_fetch() and get the row fields with sqlsrv_get_field().
<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}
$sql = "SELECT Name, Comment
FROM Table_1
WHERE ReviewID=1";
$stmt = sqlsrv_query( $conn, $sql);
if( $stmt === false ) {
die( print_r( sqlsrv_errors(), true));
}
// Make the first (and in this case, only) row of the result set available for reading.
if( sqlsrv_fetch( $stmt ) === false) {
die( print_r( sqlsrv_errors(), true));
}
// Get the row fields. Field indeces start at 0 and must be retrieved in order.
// Retrieving row fields by name is not supported by sqlsrv_get_field.
$name = sqlsrv_get_field( $stmt, 0);
echo "$name: ";
$comment = sqlsrv_get_field( $stmt, 1);
echo $comment;
?>
Zobacz też:
- sqlsrv_fetch() - Makes the next row in a result set available for reading
- sqlsrv_fetch_array() - Returns a row as an array
- sqlsrv_fetch_object() - Retrieves the next row of data in a result set as an object
sqlsrv_has_rows
(No version information available, might only be in SVN)
sqlsrv_has_rows — Indicates whether the specified statement has rows
Opis
$stmt
)Indicates whether the specified statement has rows.
Zwracane wartości
Returns TRUE if the specified statement has rows and FALSE if the statement
does not have rows or if an error occured.
Przykłady
Przykład #1 sqlsrv_has_rows() example
<?php
$server = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" )
$conn = sqlsrv_connect( $server, $connectionInfo );
$stmt = sqlsrv_query( $conn, "SELECT * FROM Table_1");
if ($stmt) {
$rows = sqlsrv_has_rows( $stmt );
if ($rows === true)
echo "There are rows. <br />";
else
echo "There are no rows. <br />";
}
?>
Zobacz też:
- sqlsrv_num_rows() - Retrieves the number of rows in a result set
- sqlsrv_query() - Prepares and executes a query.
sqlsrv_next_result
(No version information available, might only be in SVN)
sqlsrv_next_result — Makes the next result of the specified statement active
Opis
Makes the next result of the specified statement active. Results include result sets, row counts, and output parameters.
Parametry
-
stmt -
The statment on which the next result is being called.
Zwracane wartości
Returns TRUE if the next result was successfully retrieved, FALSE if an error
occurred, and NULL if there are no more results to retrieve.
Przykłady
Przykład #1 sqlsrv_next_result() example
The following example executes a batch query that inserts into a table and then selects from the table. This produces two results on the statement: one for the rows affected by the INSERT and one for the rows returned by the SELECT. To get to the rows returned by the SELECT, sqlsrv_next_result() must be called to move past the first result.
<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array("Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
$query = "INSERT INTO Table_1 (id, data) VALUES (?,?); SELECT * FROM TABLE_1;";
$params = array(1, "some data");
$stmt = sqlsrv_query($conn, $query, $params);
// Consume the first result (rows affected by INSERT) without calling sqlsrv_next_result.
echo "Rows affected: ".sqlsrv_rows_affected($stmt)."<br />";
// Move to the next result and display results.
$next_result = sqlsrv_next_result($stmt);
if( $next_result ) {
while( $row = sqlsrv_fetch_array( $stmt, SQLSRV_FETCH_ASSOC)){
echo $row['id'].": ".$row['data']."<br />";
}
} elseif( is_null($next_result)) {
echo "No more results.<br />";
} else {
die(print_r(sqlsrv_errors(), true));
}
?>
Zobacz też:
- sqlsrv_query() - Prepares and executes a query.
- sqlsrv_fetch_array() - Returns a row as an array
- sqlsrv_rows_affected() - Returns the number of rows modified by the last INSERT, UPDATE, or DELETE query executed
sqlsrv_num_fields
(No version information available, might only be in SVN)
sqlsrv_num_fields — Retrieves the number of fields (columns) on a statement
Opis
Retrieves the number of fields (columns) on a statement.
Parametry
-
stmt -
The statment for which the number of fields is returned. sqlsrv_num_fields() can be called on a statement before or after statement execution.
Zwracane wartości
Returns the number of fields on success. Returns FALSE otherwise.
Przykłady
Przykład #1 sqlsrv_num_fields() example
<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}
$sql = "SELECT * FROM Table_1";
$stmt = sqlsrv_query($conn, $sql);
if( $stmt === false) {
die( print_r( sqlsrv_errors(), true));
}
$numFields = sqlsrv_num_fields( $stmt );
while( sqlsrv_fetch( $stmt )) {
// Iterate through the fields of each row.
for($i = 0; $i < $numFields; $i++) {
{
echo sqlsrv_get_field($stmt, $i)." ";
}
echo "<br />";
}
?>
Zobacz też:
- sqlsrv_field_metadata() - Retrieves metadata for the fields of a statement prepared by sqlsrv_prepare or sqlsrv_query
- sqlsrv_fetch() - Makes the next row in a result set available for reading
- sqlsrv_get_field() - Gets field data from the currently selected row
sqlsrv_num_rows
(No version information available, might only be in SVN)
sqlsrv_num_rows — Retrieves the number of rows in a result set
Opis
Retrieves the number of rows in a result set. This function requires that the statment resource be created with a static or keyset cursor. For more information, see sqlsrv_query(), sqlsrv_prepare(), or » Specifying a Cursor Type and Selecting Rows in the Microsoft SQLSRV documentation.
Parametry
-
stmt -
The statement for which the row count is returned. The statment resource must be created with a static or keyset cursor. For more information, see sqlsrv_query(), sqlsrv_prepare(), or » Specifying a Cursor Type and Selecting Rows in the Microsoft SQLSRV documentation.
Zwracane wartości
Returns the number of rows retrieved on success and FALSE if an error occured.
If a forward cursor (the default) or dynamic cursor is used, FALSE is returned.
Przykłady
Przykład #1 sqlsrv_num_rows() example
<?php
$server = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
$conn = sqlsrv_connect( $server, $connectionInfo );
$sql = "SELECT * FROM Table_1";
$params = array();
$options = array( "Scrollable" => SQLSRV_CURSOR_KEYSET );
$stmt = sqlsrv_query( $conn, $sql , $params, $options );
$row_count = sqlsrv_num_rows( $stmt );
if ($row_count === false)
echo "Error in retrieveing row count.";
else
echo $row_count;
?>
Zobacz też:
- sqlsrv_has_rows() - Indicates whether the specified statement has rows
- sqlsrv_rows_affected() - Returns the number of rows modified by the last INSERT, UPDATE, or DELETE query executed
sqlsrv_prepare
(No version information available, might only be in SVN)
sqlsrv_prepare — Prepares a query for execution
Opis
Prepares a query for execution. This function is ideal for preparing a query that will be executed multiple times with different parameter values.
Parametry
-
conn -
A connection resource returned by sqlsrv_connect().
-
sql -
The string that defines the query to be prepared and executed.
-
params -
An array specifying parameter information when executing a parameterized query. Array elements can be any of the following:
- A literal value
- A PHP variable
- An array with this structure: array($value [, $direction [, $phpType [, $sqlType]]])
Array structure Element Description $value A literal value, a PHP variable, or a PHP by-reference variable. $direction (optional) One of the following SQLSRV constants used to indicate the parameter direction: SQLSRV_PARAM_IN, SQLSRV_PARAM_OUT, SQLSRV_PARAM_INOUT. The default value is SQLSRV_PARAM_IN. $phpType (optional) A SQLSRV_PHPTYPE_* constant that specifies PHP data type of the returned value. $sqlType (optional) A SQLSRV_SQLTYPE_* constant that specifies the SQL Server data type of the input value. -
options -
An array specifing query property options. The supported keys are described in the following table:
Query Options Key Values Description QueryTimeout A positive integer value. Sets the query timeout in seconds. By default, the driver will wait indefinitely for results. SendStreamParamsAtExec TRUEorFALSE(the default isTRUE)Configures the driver to send all stream data at execution ( TRUE), or to send stream data in chunks (FALSE). By default, the value is set toTRUE. For more information, see sqlsrv_send_stream_data().Scrollable SQLSRV_CURSOR_FORWARD, SQLSRV_CURSOR_STATIC, SQLSRV_CURSOR_DYNAMIC, or SQLSRV_CURSOR_KEYSET See » Specifying a Cursor Type and Selecting Rows in the Microsoft SQLSRV documentation.
Zwracane wartości
Returns a statement resource on success and FALSE if an error occurred.
Przykłady
Przykład #1 sqlsrv_prepare() example
This example demonstrates how to prepare a statement with sqlsrv_prepare() and re-execute it multiple times (with different parameter values) using sqlsrv_execute().
<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false) {
die( print_r( sqlsrv_errors(), true));
}
$sql = "UPDATE Table_1
SET OrderQty = ?
WHERE SalesOrderID = ?";
// Initialize parameters and prepare the statement.
// Variables $qty and $id are bound to the statement, $stmt.
$qty = 0; $id = 0;
$stmt = sqlsrv_prepare( $conn, $sql, array( &$qty, &$id));
if( !$stmt ) {
die( print_r( sqlsrv_errors(), true));
}
// Set up the SalesOrderDetailID and OrderQty information.
// This array maps the order ID to order quantity in key=>value pairs.
$orders = array( 1=>10, 2=>20, 3=>30);
// Execute the statement for each order.
foreach( $orders as $id => $qty) {
// Because $id and $qty are bound to $stmt1, their updated
// values are used with each execution of the statement.
if( sqlsrv_execute( $stmt ) === false ) {
die( print_r( sqlsrv_errors(), true));
}
}
?>
Notatki
When you prepare a statement that uses variables as parameters, the variables are bound to the statement. This means that if you update the values of the variables, the next time you execute the statement it will run with updated parameter values. For statements that you plan to execute only once, use sqlsrv_query().
Zobacz też:
- sqlsrv_execute() - Executes a statement prepared with sqlsrv_prepare
- sqlsrv_query() - Prepares and executes a query.
sqlsrv_query
(No version information available, might only be in SVN)
sqlsrv_query — Prepares and executes a query.
Opis
Prepares and executes a query.
Parametry
-
conn -
A connection resource returned by sqlsrv_connect().
-
sql -
The string that defines the query to be prepared and executed.
-
params -
An array specifying parameter information when executing a parameterized query. Array elements can be any of the following:
- A literal value
- A PHP variable
- An array with this structure: array($value [, $direction [, $phpType [, $sqlType]]])
Array structure Element Description $value A literal value, a PHP variable, or a PHP by-reference variable. $direction (optional) One of the following SQLSRV constants used to indicate the parameter direction: SQLSRV_PARAM_IN, SQLSRV_PARAM_OUT, SQLSRV_PARAM_INOUT. The default value is SQLSRV_PARAM_IN. $phpType (optional) A SQLSRV_PHPTYPE_* constant that specifies PHP data type of the returned value. $sqlType (optional) A SQLSRV_SQLTYPE_* constant that specifies the SQL Server data type of the input value. -
options -
An array specifing query property options. The supported keys are described in the following table:
Query Options Key Values Description QueryTimeout A positive integer value. Sets the query timeout in seconds. By default, the driver will wait indefinitely for results. SendStreamParamsAtExec TRUEorFALSE(the default isTRUE)Configures the driver to send all stream data at execution ( TRUE), or to send stream data in chunks (FALSE). By default, the value is set toTRUE. For more information, see sqlsrv_send_stream_data().Scrollable SQLSRV_CURSOR_FORWARD, SQLSRV_CURSOR_STATIC, SQLSRV_CURSOR_DYNAMIC, or SQLSRV_CURSOR_KEYSET See » Specifying a Cursor Type and Selecting Rows in the Microsoft SQLSRV documentation.
Zwracane wartości
Returns a statement resource on success and FALSE if an error occurred.
Przykłady
Przykład #1 sqlsrv_query() example
<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}
$sql = "INSERT INTO Table_1 (id, data) VALUES (?, ?)";
$params = array(1, "some data");
$stmt = sqlsrv_query( $conn, $sql, $params);
if( $stmt === false ) {
die( print_r( sqlsrv_errors(), true));
}
?>
Notatki
For statements that you plan to execute only once, use sqlsrv_query(). If you intend to re-execute a statement with different parameter values, use the combination of sqlsrv_prepare() and sqlsrv_execute().
Zobacz też:
- sqlsrv_prepare() - Prepares a query for execution
- sqlsrv_execute() - Executes a statement prepared with sqlsrv_prepare
sqlsrv_rollback
(No version information available, might only be in SVN)
sqlsrv_rollback — Rolls back a transaction that was begun with sqlsrv_begin_transaction()
Opis
$conn
)Rolls back a transaction that was begun with sqlsrv_begin_transaction() and returns the connection to auto-commit mode.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 sqlsrv_rollback() example
The following example demonstrates how to use sqlsrv_begin_transaction() together with sqlsrv_commit() and sqlsrv_rollback().
<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true ));
}
/* Begin the transaction. */
if ( sqlsrv_begin_transaction( $conn ) === false ) {
die( print_r( sqlsrv_errors(), true ));
}
/* Initialize parameter values. */
$orderId = 1; $qty = 10; $productId = 100;
/* Set up and execute the first query. */
$sql1 = "INSERT INTO OrdersTable (ID, Quantity, ProductID)
VALUES (?, ?, ?)";
$params1 = array( $orderId, $qty, $productId );
$stmt1 = sqlsrv_query( $conn, $sql1, $params1 );
/* Set up and execute the second query. */
$sql2 = "UPDATE InventoryTable
SET Quantity = (Quantity - ?)
WHERE ProductID = ?";
$params2 = array($qty, $productId);
$stmt2 = sqlsrv_query( $conn, $sql2, $params2 );
/* If both queries were successful, commit the transaction. */
/* Otherwise, rollback the transaction. */
if( $stmt1 && $stmt2 ) {
sqlsrv_commit( $conn );
echo "Transaction committed.<br />";
} else {
sqlsrv_rollback( $conn );
echo "Transaction rolled back.<br />";
}
?>
Zobacz też:
- sqlsrv_begin_transaction() - Begins a database transaction
- sqlsrv_commit() - Commits a transaction that was begun with sqlsrv_begin_transaction
sqlsrv_rows_affected
(No version information available, might only be in SVN)
sqlsrv_rows_affected — Returns the number of rows modified by the last INSERT, UPDATE, or DELETE query executed
Opis
$stmt
)Returns the number of rows modified by the last INSERT, UPDATE, or DELETE query executed. For information about the number of rows returned by a SELECT query, see sqlsrv_num_rows().
Parametry
-
stmt -
The executed statement resource for which the number of affected rows is returned.
Zwracane wartości
Returns the number of rows affected by the last INSERT, UPDATE, or DELETE query.
If no rows were affected, 0 is returned. If the number of affected rows cannot
be determined, -1 is returned. If an error occured, FALSE is returned.
Przykłady
Przykład #1 sqlsrv_rows_affected() example
<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}
$sql = "UPDATE Table_1 SET data = ? WHERE id = ?";
$params = array("updated data", 1);
$stmt = sqlsrv_query( $conn, $sql, $params);
$rows_affected = sqlsrv_rows_affected( $stmt);
if( $rows_affected === false) {
die( print_r( sqlsrv_errors(), true));
} elseif( $rows_affected == -1) {
echo "No information available.<br />";
} else {
echo $rows_affected." rows were updated.<br />";
}
?>
sqlsrv_send_stream_data
(No version information available, might only be in SVN)
sqlsrv_send_stream_data — Sends data from parameter streams to the server
Opis
$stmt
)Send data from parameter streams to the server. Up to 8 KB of data is sent with each call.
Zwracane wartości
Returns TRUE if there is more data to send and FALSE if there is not.
Przykłady
Przykład #1 sqlsrv_send_stream_data() example
<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}
$sql = "UPDATE Table_1 SET data = ( ?) WHERE id = 100";
// Open parameter data as a stream and put it in the $params array.
$data = fopen( "data://text/plain,[ Lengthy content here. ]", "r");
$params = array( &$data);
// Prepare the statement. Use the $options array to turn off the
// default behavior, which is to send all stream data at the time of query
// execution.
$options = array("SendStreamParamsAtExec"=>0);
$stmt = sqlsrv_prepare( $conn, $sql, $params, $options);
sqlsrv_execute( $stmt);
// Send up to 8K of parameter data to the server
// with each call to sqlsrv_send_stream_data.
$i = 1;
while( sqlsrv_send_stream_data( $stmt)) {
$i++;
}
echo "$i calls were made.";
?>
Zobacz też:
- sqlsrv_prepare() - Prepares a query for execution
- sqlsrv_query() - Prepares and executes a query.
sqlsrv_server_info
(No version information available, might only be in SVN)
sqlsrv_server_info — Returns information about the server
Opis
$conn
)Returns information about the server.
Parametry
-
conn -
The connection resource that connects the client and the server.
Zwracane wartości
Returns an array as described in the following table:
| CurrentDatabase | The connected-to database. |
|---|---|
| SQLServerVersion | The SQL Server version. |
| SQLServerName | The name of the server. |
Przykłady
Przykład #1 sqlsrv_server_info() example
<?php
$serverName = "serverName\sqlexpress";
$conn = sqlsrv_connect( $serverName);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}
$server_info = sqlsrv_server_info( $conn);
if( $server_info )
{
foreach( $server_info as $key => $value) {
echo $key.": ".$value."<br />";
}
} else {
die( print_r( sqlsrv_errors(), true));
}
?>
Spis treści
- sqlsrv_begin_transaction — Begins a database transaction
- sqlsrv_cancel — Cancels a statement
- sqlsrv_client_info — Returns information about the client and specified connection
- sqlsrv_close — Closes an open connection and releases resourses associated with the connection
- sqlsrv_commit — Commits a transaction that was begun with sqlsrv_begin_transaction
- sqlsrv_configure — Changes the driver error handling and logging configurations
- sqlsrv_connect — Opens a connection to a Microsoft SQL Server database
- sqlsrv_errors — Returns error and warning information about the last SQLSRV operation performed
- sqlsrv_execute — Executes a statement prepared with sqlsrv_prepare
- sqlsrv_fetch_array — Returns a row as an array
- sqlsrv_fetch_object — Retrieves the next row of data in a result set as an object
- sqlsrv_fetch — Makes the next row in a result set available for reading
- sqlsrv_field_metadata — Retrieves metadata for the fields of a statement prepared by sqlsrv_prepare or sqlsrv_query
- sqlsrv_free_stmt — Frees all resources for the specified statement
- sqlsrv_get_config — Returns the value of the specified configuration setting
- sqlsrv_get_field — Gets field data from the currently selected row
- sqlsrv_has_rows — Indicates whether the specified statement has rows
- sqlsrv_next_result — Makes the next result of the specified statement active
- sqlsrv_num_fields — Retrieves the number of fields (columns) on a statement
- sqlsrv_num_rows — Retrieves the number of rows in a result set
- sqlsrv_prepare — Prepares a query for execution
- sqlsrv_query — Prepares and executes a query.
- sqlsrv_rollback — Rolls back a transaction that was begun with sqlsrv_begin_transaction
- sqlsrv_rows_affected — Returns the number of rows modified by the last INSERT, UPDATE, or DELETE query executed
- sqlsrv_send_stream_data — Sends data from parameter streams to the server
- sqlsrv_server_info — Returns information about the server
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- SQLSRV Funkcje
- sqlsrv_begin_transaction — Begins a database transaction
- sqlsrv_cancel — Cancels a statement
- sqlsrv_client_info — Returns information about the client and specified connection
- sqlsrv_close — Closes an open connection and releases resourses associated with the connection
- sqlsrv_commit — Commits a transaction that was begun with sqlsrv_begin_transaction
- sqlsrv_configure — Changes the driver error handling and logging configurations
- sqlsrv_connect — Opens a connection to a Microsoft SQL Server database
- sqlsrv_errors — Returns error and warning information about the last SQLSRV operation performed
- sqlsrv_execute — Executes a statement prepared with sqlsrv_prepare
- sqlsrv_fetch_array — Returns a row as an array
- sqlsrv_fetch_object — Retrieves the next row of data in a result set as an object
- sqlsrv_fetch — Makes the next row in a result set available for reading
- sqlsrv_field_metadata — Retrieves metadata for the fields of a statement prepared by sqlsrv_prepare or sqlsrv_query
- sqlsrv_free_stmt — Frees all resources for the specified statement
- sqlsrv_get_config — Returns the value of the specified configuration setting
- sqlsrv_get_field — Gets field data from the currently selected row
- sqlsrv_has_rows — Indicates whether the specified statement has rows
- sqlsrv_next_result — Makes the next result of the specified statement active
- sqlsrv_num_fields — Retrieves the number of fields (columns) on a statement
- sqlsrv_num_rows — Retrieves the number of rows in a result set
- sqlsrv_prepare — Prepares a query for execution
- sqlsrv_query — Prepares and executes a query.
- sqlsrv_rollback — Rolls back a transaction that was begun with sqlsrv_begin_transaction
- sqlsrv_rows_affected — Returns the number of rows modified by the last INSERT, UPDATE, or DELETE query executed
- sqlsrv_send_stream_data — Sends data from parameter streams to the server
- sqlsrv_server_info — Returns information about the server
Sybase
Wstęp
Instalacja/Konfiguracja
Spis treści
Wymagania
Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.
Instalacja
To enable Sybase-DB support configure PHP --with-sybase[=DIR] . DIR is the Sybase home directory, defaults to /home/sybase. To enable Sybase-CT support configure PHP --with-sybase-ct[=DIR] . DIR is the Sybase home directory, defaults to /home/sybase.
Informacja:
As of PHP 5.3.0, the Sybase extension has been superseded by the sybase_ct extension and is no longer maintained. To continue using sybase you must use the sybase_ct extension.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| sybase.allow_persistent | "1" | PHP_INI_ALL | PHP_INI_ALL in PHP <= 4.0.2. PHP_INI_SYSTEM in PHP <= 4.0.3. |
| sybase.max_persistent | "-1" | PHP_INI_ALL | PHP_INI_ALL in PHP <= 4.0.2. PHP_INI_SYSTEM in PHP <= 4.0.3. |
| sybase.max_links | "-1" | PHP_INI_ALL | PHP_INI_ALL in PHP <= 4.0.2. PHP_INI_SYSTEM in PHP <= 4.0.3. |
| sybase.interface_file | "/usr/sybase/interfaces" | PHP_INI_SYSTEM | |
| sybase.min_error_severity | "10" | PHP_INI_ALL | |
| sybase.min_message_severity | "10" | PHP_INI_ALL | |
| sybase.compatability_mode | "0" | PHP_INI_ALL | |
| magic_quotes_sybase | "0" | PHP_INI_ALL | Deprecated in PHP 5.3.0. Ta przestarzała funkcja zostanie na pewno w przyszłości usunięta. |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
sybase.allow_persistentboolean -
Whether to allow persistent Sybase connections.
-
sybase.max_persistentinteger -
The maximum number of persistent Sybase connections per process. -1 means no limit.
-
sybase.max_linksinteger -
The maximum number of Sybase connections per process, including persistent connections. -1 means no limit.
-
sybase.min_error_severityinteger -
Minimum error severity to display.
-
sybase.min_message_severityinteger -
Minimum message severity to display.
-
magic_quotes_sybaseboolean -
If
magic_quotes_sybaseis on, a single-quote is escaped with a single-quote instead of a backslash if magic_quotes_gpc or magic_quotes_runtime are enabled. This setting is also respected by addslashes() and stripslashes().Informacja:
Note that when
magic_quotes_sybaseis ON it completely overridesmagic_quotes_gpc. In this case even whenmagic_quotes_gpcis enabled neither double quotes, backslashes or NUL's will be escaped.OstrzeżenieThis feature has been DEPRECATED as of PHP 5.3.0 and REMOVED as of PHP 5.4.0.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| sybct.allow_persistent | "1" | PHP_INI_SYSTEM | PHP_INI_ALL in PHP <= 4.0.2. Available since PHP 4.0.2. Removed in PHP 4.0.3. |
| sybct.max_persistent | "-1" | PHP_INI_SYSTEM | PHP_INI_ALL in PHP <= 4.0.2. Available since PHP 4.0.2. Removed in PHP 4.0.3. |
| sybct.max_links | "-1" | PHP_INI_SYSTEM | PHP_INI_ALL in PHP <= 4.0.2. Available since PHP 4.0.2. Removed in PHP 4.0.3. |
| sybct.min_server_severity | "10" | PHP_INI_ALL | Available since PHP 4.0.2. Removed in PHP 4.0.3. |
| sybct.min_client_severity | "10" | PHP_INI_ALL | Available since PHP 4.0.2. Removed in PHP 4.0.3. |
| sybct.hostname | NULL | PHP_INI_ALL | Available since PHP 4.0.2. Removed in PHP 4.0.3. |
| sybct.deadlock_retry_count | "0" | PHP_INI_ALL | Available since PHP 4.3.0. |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
sybct.allow_persistentboolean -
Whether to allow persistent Sybase-CT connections. The default is on.
-
sybct.max_persistentinteger -
The maximum number of persistent Sybase-CT connections per process. The default is -1 meaning unlimited.
-
sybct.max_linksinteger -
The maximum number of Sybase-CT connections per process, including persistent connections. The default is -1 meaning unlimited.
-
sybct.min_server_severityinteger -
Server messages with severity greater than or equal to sybct.min_server_severity will be reported as warnings. This value can also be set from a script by calling sybase_min_server_severity(). The default is 10 which reports errors of information severity or greater.
-
sybct.min_client_severityinteger -
Client library messages with severity greater than or equal to sybct.min_client_severity will be reported as warnings. This value can also be set from a script by calling sybase_min_client_severity(). The default is 10 which effectively disables reporting.
-
sybct.login_timeoutinteger -
The maximum time in seconds to wait for a connection attempt to succeed before returning failure. Note that if max_execution_time has been exceeded when a connection attempt times out, your script will be terminated before it can take action on failure. The default is one minute.
-
sybct.timeoutinteger -
The maximum time in seconds to wait for a select_db or query operation to succeed before returning failure. Note that if max_execution_time has been exceeded when an operation times out, your script will be terminated before it can take action on failure. The default is no limit.
-
sybct.hostnamestring -
The name of the host you claim to be connecting from, for display by sp_who. The default is none.
-
sybct.deadlock_retry_countint -
Allows you to define how often deadlocks are to be retried. The default is 0, value -1 means "forever".
Szczegóły i definicje dotyczące działania PHP_INI_* znajdują się w rozdziale Where a configuration setting may be set.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
To rozszerzenie nie posiada żadnych stałych.
Sybase Funkcje
sybase_affected_rows
(PHP 4, PHP 5)
sybase_affected_rows — Gets number of affected rows in last query
Opis
$link_identifier
] )sybase_affected_rows() returns the number of rows affected by the last INSERT, UPDATE or DELETE query on the server associated with the specified link identifier.
This command is not effective for SELECT statements, only on statements which modify records. To retrieve the number of rows returned from a SELECT, use sybase_num_rows().
Parametry
-
link_identifier -
If the link identifier isn't specified, the last opened link is assumed.
Zwracane wartości
Returns the number of affected rows, as an integer.
Przykłady
Przykład #1 Delete-Query
<?php
/* connect to database */
sybase_connect('SYBASE', '', '') or
die("Could not connect");
sybase_select_db("db");
sybase_query("DELETE FROM sometable WHERE id < 10");
printf("Records deleted: %d\n", sybase_affected_rows());
?>
Powyższy przykład wyświetli:
Records deleted: 10
sybase_close
(PHP 4, PHP 5)
sybase_close — Closes a Sybase connection
Opis
$link_identifier
] )
sybase_close() closes the link to a Sybase
database that's associated with the specified link
link_identifier.
Note that this isn't usually necessary, as non-persistent open links are automatically closed at the end of the script's execution.
sybase_close() will not close persistent links generated by sybase_pconnect().
Parametry
-
link_identifier -
If the link identifier isn't specified, the last opened link is assumed.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- sybase_connect() - Opens a Sybase server connection
- sybase_pconnect() - Open persistent Sybase connection
sybase_connect
(PHP 4, PHP 5)
sybase_connect — Opens a Sybase server connection
Opis
$servername
[, string $username
[, string $password
[, string $charset
[, string $appname
[, bool $new = false
]]]]]] )sybase_connect() establishes a connection to a Sybase server.
In case a second call is made to sybase_connect() with the same arguments, no new link will be established, but instead, the link identifier of the already opened link will be returned.
The link to the server will be closed as soon as the execution of the script ends, unless it's closed earlier by explicitly calling sybase_close().
Parametry
-
servername -
The servername argument has to be a valid servername that is defined in the 'interfaces' file.
-
username -
Sybase user name
-
password -
Password associated with
username. -
charset -
Specifies the charset for the connection
-
appname -
Specifies an appname for the Sybase connection. This allow you to make separate connections in the same script to the same database. This may come handy when you have started a transaction in your current connection, and you need to be able to do a separate query which cannot be performed inside this transaction.
-
new -
Whether to open a new connection or use the existing one.
Zwracane wartości
Returns a positive Sybase link identifier on success, or FALSE on
failure.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.0 |
The new parameter was added.
|
| 4.2.0 |
The appname parameter was added.
|
| 4.0.2 |
The charset parameter was added.
|
Przykłady
Przykład #1 sybase_connect() example
<?php
$link = sybase_connect('SYBASE', '', '')
or die("Could not connect !");
echo "Connected successfully";
sybase_close($link);
?>
Zobacz też:
- sybase_pconnect() - Open persistent Sybase connection
- sybase_close() - Closes a Sybase connection
sybase_data_seek
(PHP 4, PHP 5)
sybase_data_seek — Moves internal row pointer
Opis
$result_identifier
, int $row_number
)sybase_data_seek() moves the internal row pointer of the Sybase result associated with the specified result identifier to pointer to the specified row number. The next call to sybase_fetch_row() would return that row.
Parametry
-
result_identifier -
-
row_number -
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
sybase_deadlock_retry_count
(PHP 4 >= 4.3.0, PHP 5)
sybase_deadlock_retry_count — Sets the deadlock retry count
Opis
$retry_count
)Using sybase_deadlock_retry_count(), the number of retries can be defined in cases of deadlocks. By default, every deadlock is retried an infinite number of times or until the process is killed by Sybase, the executing script is killed (for instance, by set_time_limit()) or the query succeeds.
Parametry
-
retry_count -
Values for retry_count -1 Retry forever (default) 0 Do not retry n Retry n times
Zwracane wartości
Nie jest zwracana żadna wartość.
Notatki
Informacja: Ta funkcja jest dostępna tylko jeśli za interfejs do Sybase służy biblioteka CT, a nie DB.
sybase_fetch_array
(PHP 4, PHP 5)
sybase_fetch_array — Fetch row as array
Opis
$result
)sybase_fetch_array() is an extended version of sybase_fetch_row(). In addition to storing the data in the numeric indices of the result array, it also stores the data in associative indices, using the field names as keys.
An important thing to note is that using sybase_fetch_array() is NOT significantly slower than using sybase_fetch_row(), while it provides a significant added value.
Parametry
-
result -
Zwracane wartości
Returns an array that corresponds to the fetched row, or FALSE if there
are no more rows.
Informacja:
When selecting fields with identical names (for instance, in a join), the associative indices will have a sequential number prepended. See the example for details.
Przykłady
Przykład #1 Identical fieldnames
<?php
$dbh = sybase_connect('SYBASE', '', '');
$q = sybase_query('SELECT * FROM p, a WHERE p.person_id= a.person_id');
var_dump(sybase_fetch_array($q));
sybase_close($dbh);
?>
The above example would produce the following output (assuming the two tables only have each one column called "person_id"):
array(4) {
[0]=>
int(1)
["person_id"]=>
int(1)
[1]=>
int(1)
["person_id1"]=>
int(1)
}
Zobacz też:
- sybase_fetch_row() - Get a result row as an enumerated array
- sybase_fetch_assoc() - Fetch a result row as an associative array
- sybase_fetch_object() - Fetch a row as an object
sybase_fetch_assoc
(PHP 4 >= 4.3.0, PHP 5)
sybase_fetch_assoc — Fetch a result row as an associative array
Opis
$result
)sybase_fetch_assoc() is a version of sybase_fetch_row() that uses column names instead of integers for indices in the result array. Columns from different tables with the same names are returned as name, name1, name2, ..., nameN.
An important thing to note is that using sybase_fetch_assoc() is NOT significantly slower than using sybase_fetch_row(), while it provides a significant added value.
Parametry
-
result -
Zwracane wartości
Returns an array that corresponds to the fetched row, or FALSE if there
are no more rows.
Notatki
Informacja: Ta funkcja jest dostępna tylko jeśli za interfejs do Sybase służy biblioteka CT, a nie DB.
Zobacz też:
- sybase_fetch_row() - Get a result row as an enumerated array
- sybase_fetch_array() - Fetch row as array
- sybase_fetch_object() - Fetch a row as an object
sybase_fetch_field
(PHP 4, PHP 5)
sybase_fetch_field — Get field information from a result
Opis
$result
[, int $field_offset = -1
] )sybase_fetch_field() can be used in order to obtain information about fields in a certain query result.
Parametry
-
result -
-
field_offset -
If the field offset isn't specified, the next field that wasn't yet retrieved by sybase_fetch_field() is retrieved.
Zwracane wartości
Returns an object containing field information.
The properties of the object are:
- name - column name. if the column is a result of a function, this property is set to computed#N, where #N is a serial number.
- column_source - the table from which the column was taken
- max_length - maximum length of the column
- numeric - 1 if the column is numeric
- type - datatype of the column
sybase_fetch_object
(PHP 4, PHP 5)
sybase_fetch_object — Fetch a row as an object
Opis
sybase_fetch_object() is similar to sybase_fetch_assoc(), with one difference - an object is returned, instead of an array.
Speed-wise, the function is identical to sybase_fetch_array(), and almost as quick as sybase_fetch_row() (the difference is insignificant).
Parametry
-
result -
-
object -
Use the second
objectto specify the type of object you want to return. If this parameter is omitted, the object will be of type stdClass.
Zwracane wartości
Returns an object with properties that correspond to the fetched row, or
FALSE if there are no more rows.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.3.0 | This function will no longer return numeric object members. Old behaviour: object(stdclass)(3) {
[0]=>
string(3) "foo"
["foo"]=>
string(3) "foo"
[1]=>
string(3) "bar"
["bar"]=>
string(3) "bar"
}
object(stdclass)(3) {
["foo"]=>
string(3) "foo"
["bar"]=>
string(3) "bar"
}
|
Przykłady
Przykład #1 sybase_fetch_object() return as Foo
<?php
class Foo {
var $foo, $bar, $baz;
}
// {...]
$qrh= sybase_query('SELECT foo, bar, baz FROM example');
$foo= sybase_fetch_object($qrh, 'Foo');
$bar= sybase_fetch_object($qrh, new Foo());
// {...]
?>
Zobacz też:
- sybase_fetch_array() - Fetch row as array
- sybase_fetch_row() - Get a result row as an enumerated array
sybase_fetch_row
(PHP 4, PHP 5)
sybase_fetch_row — Get a result row as an enumerated array
Opis
$result
)sybase_fetch_row() fetches one row of data from the result associated with the specified result identifier.
Subsequent call to sybase_fetch_row() would
return the next row in the result set, or FALSE if there are no
more rows.
Parametry
-
result -
Zwracane wartości
Returns an array that corresponds to the fetched row, or FALSE if there
are no more rows. Each result column is stored in an array offset,
starting at offset 0.
| PHP | Sybase |
|---|---|
| string | VARCHAR, TEXT, CHAR, IMAGE, BINARY, VARBINARY, DATETIME |
| int | NUMERIC (w/o precision), DECIMAL (w/o precision), INT, BIT, TINYINT, SMALLINT |
| float | NUMERIC (w/ precision), DECIMAL (w/ precision), REAL, FLOAT, MONEY |
NULL |
NULL |
Zobacz też:
- sybase_fetch_array() - Fetch row as array
- sybase_fetch_assoc() - Fetch a result row as an associative array
- sybase_fetch_object() - Fetch a row as an object
- sybase_data_seek() - Moves internal row pointer
- sybase_result() - Get result data
sybase_field_seek
(PHP 4, PHP 5)
sybase_field_seek — Sets field offset
Opis
$result
, int $field_offset
)Seeks to the specified field offset. If the next call to sybase_fetch_field() won't include a field offset, this field would be returned.
Parametry
-
result -
-
field_offset -
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
sybase_free_result
(PHP 4, PHP 5)
sybase_free_result — Frees result memory
Opis
$result
)sybase_free_result() only needs to be called if you are worried about using too much memory while your script is running. All result memory will automatically be freed when the script ends. You may call sybase_free_result() with the result identifier as an argument and the associated result memory will be freed.
Parametry
-
result -
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
sybase_get_last_message
(PHP 4, PHP 5)
sybase_get_last_message — Returns the last message from the server
Opis
sybase_get_last_message() returns the last message reported by the server.
Zwracane wartości
Returns the message as a string.
sybase_min_client_severity
(PHP 4, PHP 5)
sybase_min_client_severity — Sets minimum client severity
Opis
$severity
)sybase_min_client_severity() sets the minimum client severity level.
Parametry
-
severity -
Zwracane wartości
Nie jest zwracana żadna wartość.
Notatki
Informacja: Ta funkcja jest dostępna tylko jeśli za interfejs do Sybase służy biblioteka CT, a nie DB.
sybase_min_error_severity
(PHP 4, PHP 5)
sybase_min_error_severity — Sets minimum error severity
Opis
$severity
)sybase_min_error_severity() sets the minimum error severity level.
Parametry
-
severity -
Zwracane wartości
Nie jest zwracana żadna wartość.
Notatki
Informacja: Ta funkcja jest dostępna tylko jeśli za interfejs do Sybase służy biblioteka CT, a nie DB.
sybase_min_message_severity
(PHP 4, PHP 5)
sybase_min_message_severity — Sets minimum message severity
Opis
$severity
)sybase_min_message_severity() sets the minimum message severity level.
Parametry
-
severity -
Zwracane wartości
Nie jest zwracana żadna wartość.
Notatki
Informacja: Ta funkcja jest dostępna tylko jeśli za interfejs do Sybase służy biblioteka DB, a nie CT.
sybase_min_server_severity
(PHP 4, PHP 5)
sybase_min_server_severity — Sets minimum server severity
Opis
$severity
)sybase_min_server_severity() sets the minimum server severity level.
Parametry
-
severity -
Zwracane wartości
Nie jest zwracana żadna wartość.
Notatki
Informacja: Ta funkcja jest dostępna tylko jeśli za interfejs do Sybase służy biblioteka CT, a nie DB.
sybase_num_fields
(PHP 4, PHP 5)
sybase_num_fields — Gets the number of fields in a result set
Opis
$result
)sybase_num_fields() returns the number of fields in a result set.
Parametry
-
result -
Zwracane wartości
Returns the number of fields as an integer.
Zobacz też:
- sybase_query() - Sends a Sybase query
- sybase_fetch_field() - Get field information from a result
- sybase_num_rows() - Get number of rows in a result set
sybase_num_rows
(PHP 4, PHP 5)
sybase_num_rows — Get number of rows in a result set
Opis
$result
)sybase_num_rows() returns the number of rows in a result set.
Parametry
-
result -
Zwracane wartości
Returns the number of rows as an integer.
Zobacz też:
- sybase_num_fields() - Gets the number of fields in a result set
- sybase_query() - Sends a Sybase query
- sybase_fetch_row() - Get a result row as an enumerated array
sybase_pconnect
(PHP 4, PHP 5)
sybase_pconnect — Open persistent Sybase connection
Opis
$servername
[, string $username
[, string $password
[, string $charset
[, string $appname
]]]]] )sybase_pconnect() acts very much like sybase_connect() with two major differences.
First, when connecting, the function would first try to find a (persistent) link that's already open with the same host, username and password. If one is found, an identifier for it will be returned instead of opening a new connection.
Second, the connection to the SQL server will not be closed when the execution of the script ends. Instead, the link will remain open for future use (sybase_close() will not close links established by sybase_pconnect()).
This type of links is therefore called 'persistent'.
Parametry
-
servername -
The servername argument has to be a valid servername that is defined in the 'interfaces' file.
-
username -
Sybase user name
-
password -
Password associated with
username. -
charset -
Specifies the charset for the connection
-
appname -
Specifies an appname for the Sybase connection. This allow you to make separate connections in the same script to the same database. This may come handy when you have started a transaction in your current connection, and you need to be able to do a separate query which cannot be performed inside this transaction.
Zwracane wartości
Returns a positive Sybase persistent link identifier on success, or
FALSE on error.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.2.0 |
The appname parameter was added.
|
| 4.0.2 |
The charset parameter was added.
|
sybase_query
(PHP 4, PHP 5)
sybase_query — Sends a Sybase query
Opis
sybase_query() sends a query to the currently active database on the server that's associated with the specified link identifier.
Parametry
-
query -
-
link_identifier -
If the link identifier isn't specified, the last opened link is assumed. If no link is open, the function tries to establish a link as if sybase_connect() was called, and use it.
Zwracane wartości
Returns a positive Sybase result identifier on success, FALSE on error,
or TRUE if the query was successful but didn't return any columns.
Zobacz też:
- sybase_select_db() - Selects a Sybase database
- sybase_connect() - Opens a Sybase server connection
sybase_result
(PHP 4, PHP 5)
sybase_result — Get result data
Opis
Returns the contents of the cell at the row and offset in the specified Sybase result set.
When working on large result sets, you should consider using one of the functions that fetch an entire row (specified below). As these functions return the contents of multiple cells in one function call, they're MUCH quicker than sybase_result(). Also, note that specifying a numeric offset for the field argument is much quicker than specifying a fieldname or tablename.fieldname argument.
Recommended high-performance alternatives: sybase_fetch_row(), sybase_fetch_array() and sybase_fetch_object().
Parametry
-
result -
-
row -
-
field -
The field argument can be the field's offset, or the field's name, or the field's table dot field's name (tablename.fieldname). If the column name has been aliased ('select foo as bar from...'), use the alias instead of the column name.
Zwracane wartości
sybase_result() returns the contents of one cell from a Sybase result set.
sybase_select_db
(PHP 4, PHP 5)
sybase_select_db — Selects a Sybase database
Opis
$database_name
[, resource $link_identifier
] )sybase_select_db() sets the current active database on the server that's associated with the specified link identifier.
Every subsequent call to sybase_query() will be made on the active database.
Parametry
-
database_name -
-
link_identifier -
If no link identifier is specified, the last opened link is assumed. If no link is open, the function will try to establish a link as if sybase_connect() was called, and use it.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- sybase_connect() - Opens a Sybase server connection
- sybase_pconnect() - Open persistent Sybase connection
- sybase_query() - Sends a Sybase query
sybase_set_message_handler
(PHP 4 >= 4.3.0, PHP 5)
sybase_set_message_handler — Sets the handler called when a server message is raised
Opis
$handler
[, resource $link_identifier
] )sybase_set_message_handler() sets a user function to handle messages generated by the server. You may specify the name of a global function, or use an array to specify an object reference and a method name.
Parametry
-
handler -
The handler expects five arguments in the following order: message number, severity, state, line number and description. The first four are integers. The last is a string. If the function returns
FALSE, PHP generates an ordinary error message. -
link_identifier -
If the link identifier isn't specified, the last opened link is assumed.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.3.5 |
The link_identifier parameter was added.
|
Przykłady
Przykład #1 sybase_set_message_handler() callback function
<?php
function msg_handler($msgnumber, $severity, $state, $line, $text)
{
var_dump($msgnumber, $severity, $state, $line, $text);
}
sybase_set_message_handler('msg_handler');
?>
Przykład #2 sybase_set_message_handler() callback to a class
<?php
class Sybase {
function handler($msgnumber, $severity, $state, $line, $text)
{
var_dump($msgnumber, $severity, $state, $line, $text);
}
}
$sybase= new Sybase();
sybase_set_message_handler(array($sybase, 'handler'));
?>
Przykład #3 sybase_set_message_handler() unhandled messages
<?php
// Return FALSE from this function to indicate you can't handle
// this. The error is printed out as a warning, the way you're used
// to it if there is no handler installed.
function msg_handler($msgnumber, $severity, $state, $line, $text)
{
if (257 == $msgnumber) {
return false;
}
var_dump($msgnumber, $severity, $state, $line, $text);
}
sybase_set_message_handler('msg_handler');
?>
Notatki
Informacja: Ta funkcja jest dostępna tylko jeśli za interfejs do Sybase służy biblioteka CT, a nie DB.
sybase_unbuffered_query
(PHP 4 >= 4.3.0, PHP 5)
sybase_unbuffered_query — Send a Sybase query and do not block
Opis
$query
, resource $link_identifier
[, bool $store_result
] )sybase_unbuffered_query() sends a query to the currently active database on the server that's associated with the specified link identifier. If the link identifier isn't specified, the last opened link is assumed. If no link is open, the function tries to establish a link as if sybase_connect() was called, and use it.
Unlike sybase_query(), sybase_unbuffered_query() reads only the first row of the result set. sybase_fetch_array() and similar function read more rows as needed. sybase_data_seek() reads up to the target row. The behavior may produce better performance for large result sets.
sybase_num_rows() will only return the correct number of rows if all result sets have been read. To Sybase, the number of rows is not known and is therefore computed by the client implementation.
Informacja:
If you don't read all of the resultsets prior to executing the next query, PHP will raise a warning and cancel all of the pending results. To get rid of this, use sybase_free_result() which will cancel pending results of an unbuffered query.
Parametry
-
query -
-
link_identifier -
-
store_result -
The optional
store_resultcan beFALSEto indicate the resultsets shouldn't be fetched into memory, thus minimizing memory usage which is particularly interesting with very large resultsets.
Zwracane wartości
Returns a positive Sybase result identifier on success, or FALSE on
error.
Przykłady
Przykład #1 sybase_unbuffered_query() example
<?php
$dbh = sybase_connect('SYBASE', '', '');
$q = sybase_unbuffered_query('select firstname, lastname from huge_table', $dbh, false);
sybase_data_seek($q, 10000);
$i = 0;
while ($row = sybase_fetch_row($q)) {
echo $row[0], ' ', $row[1], '<br />';
if ($i++ > 40000) {
break;
}
}
sybase_free_result($q);
sybase_close($dbh);
?>
Notatki
Informacja: Ta funkcja jest dostępna tylko jeśli za interfejs do Sybase służy biblioteka CT, a nie DB.
Spis treści
- sybase_affected_rows — Gets number of affected rows in last query
- sybase_close — Closes a Sybase connection
- sybase_connect — Opens a Sybase server connection
- sybase_data_seek — Moves internal row pointer
- sybase_deadlock_retry_count — Sets the deadlock retry count
- sybase_fetch_array — Fetch row as array
- sybase_fetch_assoc — Fetch a result row as an associative array
- sybase_fetch_field — Get field information from a result
- sybase_fetch_object — Fetch a row as an object
- sybase_fetch_row — Get a result row as an enumerated array
- sybase_field_seek — Sets field offset
- sybase_free_result — Frees result memory
- sybase_get_last_message — Returns the last message from the server
- sybase_min_client_severity — Sets minimum client severity
- sybase_min_error_severity — Sets minimum error severity
- sybase_min_message_severity — Sets minimum message severity
- sybase_min_server_severity — Sets minimum server severity
- sybase_num_fields — Gets the number of fields in a result set
- sybase_num_rows — Get number of rows in a result set
- sybase_pconnect — Open persistent Sybase connection
- sybase_query — Sends a Sybase query
- sybase_result — Get result data
- sybase_select_db — Selects a Sybase database
- sybase_set_message_handler — Sets the handler called when a server message is raised
- sybase_unbuffered_query — Send a Sybase query and do not block
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Sybase Funkcje
- sybase_affected_rows — Gets number of affected rows in last query
- sybase_close — Closes a Sybase connection
- sybase_connect — Opens a Sybase server connection
- sybase_data_seek — Moves internal row pointer
- sybase_deadlock_retry_count — Sets the deadlock retry count
- sybase_fetch_array — Fetch row as array
- sybase_fetch_assoc — Fetch a result row as an associative array
- sybase_fetch_field — Get field information from a result
- sybase_fetch_object — Fetch a row as an object
- sybase_fetch_row — Get a result row as an enumerated array
- sybase_field_seek — Sets field offset
- sybase_free_result — Frees result memory
- sybase_get_last_message — Returns the last message from the server
- sybase_min_client_severity — Sets minimum client severity
- sybase_min_error_severity — Sets minimum error severity
- sybase_min_message_severity — Sets minimum message severity
- sybase_min_server_severity — Sets minimum server severity
- sybase_num_fields — Gets the number of fields in a result set
- sybase_num_rows — Get number of rows in a result set
- sybase_pconnect — Open persistent Sybase connection
- sybase_query — Sends a Sybase query
- sybase_result — Get result data
- sybase_select_db — Selects a Sybase database
- sybase_set_message_handler — Sets the handler called when a server message is raised
- sybase_unbuffered_query — Send a Sybase query and do not block
tokyo_tyrant
Wstęp
tokyo_tyrant extension provides a wrapper for Tokyo Tyrant client libraries. The extension contains the normal key-value API and the table API.
"Tokyo Tyrant is a package of network interface to the DBM called Tokyo Cabinet. Though the DBM has high performance, you might bother in case that multiple processes share the same database, or remote processes access the database. Thus, Tokyo Tyrant is provided for concurrent and remote connections to Tokyo Cabinet. It is composed of the server process managing a database and its access library for client applications." --Tokyo Tyrant documentation
Tokyo Tyrant is written by Mikio Hirabayashi and is licensed under GNU Lesser General Public License.
Instalacja/Konfiguracja
Spis treści
Wymagania
Before using this extension Tokyo Cabinet and Tokyo Tyrant must be installed.
Instalacja
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/tokyo_tyrant
Configure options
- --with-tokyo-tyrant[=DIR] DIR is the prefix to the Tokyo Tyrant installation
- --with-tokyo-cabinet-dir[=DIR] DIR is the prefix to the Tokyo Cabinet installation
- --disable-tokyo-tyrant-session Disable Tokyo Tyrant session handler support
Enabling the extension
The extension can be enabled by adding extension=tokyo_tyrant.so to the INI-configuration
Running Tokyo Tyrant for the session handler
ttserver -port 2000 -ext /path/to/expire.lua -extpc expire 30.0 '/tmp/sessions.tct#idx=ts:dec'
Informacja: expire.lua is included in the tokyo_tyrant extension source distribution
Configuring session handler
- tokyo_tyrant.session_salt="randomlongstring"
- session.save_handler=tokyo_tyrant
- session.save_path="tcp://hostname1:2000,tcp://hostname2:2000"
Informacja: It is important to make sure that tokyo_tyrant.session_salt matches on all servers.
How it works?
The session handler creates a session id like the following: 8b0e27a823fa4a6cf7246945b82c1d51-a5eadbbed1f2075952900628456bfd6830541629-0-5460
The parts from left to right:
- Session id - Generated session id
- Checksum - Checksum of session salt, session id, node id and primary key
- Node id - The id of the node where the session maps to
- Primary key - The primary key of the row where the session is stored
The checksum contains SHA1 sum of the node id, primary key, session id and the salt which is known only on the server side. This allows quick mapping of session id to node and primary key since there is no need to do an additional search. During session id regeneration only the parts 1 and 2 change but the mapping to the node and primary key stays constant.
In case some of the nodes fail tokyo_tyrant.allow_failover, tokyo_tyrant.fail_threshold and tokyo_tyrant.health_check_divisor INI-settings control the behavior during failover. If failover is allowed the session handler will map the session to a healthy node and creates a new empty session.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| tokyo_tyrant.default_timeout | 2.0 | PHP_INI_ALL | |
| tokyo_tyrant.session_salt | NULL |
PHP_INI_ALL | |
| tokyo_tyrant.key_prefix | NULL |
PHP_INI_ALL | |
| tokyo_tyrant.allow_failover | 1 | PHP_INI_ALL | |
| tokyo_tyrant.fail_threshold | 5 | PHP_INI_ALL | |
| tokyo_tyrant.health_check_divisor | 1000 | PHP_INI_ALL | |
| tokyo_tyrant.php_expiration | 0 | PHP_INI_ALL |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
tokyo_tyrant.default_timeoutinteger -
Default timeout when connecting to databases
-
tokyo_tyrant.session_saltstring -
The secret that is used to salt session id
-
tokyo_tyrant.key_prefixstring -
Prefix all keys with this string. The prefix is transparent to the developer but helps making sure that keys won't collide if multiple applications are using the same database.
-
tokyo_tyrant.allow_failoverinteger -
Whether to allow session failover in case a server dies.
-
tokyo_tyrant.fail_thresholdinteger -
How many read/write or connection failures is allowed before server is marked as failed.
-
tokyo_tyrant.health_check_divisorinteger -
Defines the divisor for the health check probability. If there are failed servers and the probability matches, the servers are health checked and in case the server seems healthy, it will be added back to the pool.
-
tokyo_tyrant.php_expirationinteger -
Whether to use built in session expiration mechanism or delegate the expiration to a lua-script on the server-side.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Przykłady
Basic usage
Przykład #1 Putting and getting a key-value pair
<?php
$tt = new TokyoTyrant("localhost");
$tt->put("key", "value");
echo $tt->get("key");
?>
Powyższy przykład wyświetli:
value
The TokyoTyrant class
(No version information available, might only be in SVN)
Wstęp
The main Tokyo Tyrant class
Krótki opis klasy
Stałe predefiniowane
TokyoTyrant Constants
-
TokyoTyrant::RDBDEF_PORT -
The default port of the Tokyo Tyrant database
-
TokyoTyrant::RDBQC_STREQ -
string is equal to
-
TokyoTyrant::RDBQC_STRINC -
string is included in
-
TokyoTyrant::RDBQC_STRBW -
string begins with
-
TokyoTyrant::RDBQC_STREW -
string ends with
-
TokyoTyrant::RDBQC_STRAND -
string includes all tokens in
-
TokyoTyrant::RDBQC_STROR -
string includes at least one token in
-
TokyoTyrant::RDBQC_STROREQ -
string is equal to at least one token in
-
TokyoTyrant::RDBQC_STRRX -
string matches regular expressions of
-
TokyoTyrant::RDBQC_NUMEQ -
number is equal to
-
TokyoTyrant::RDBQC_NUMGT -
number is greater than
-
TokyoTyrant::RDBQC_NUMGE -
number is greater than or equal to
-
TokyoTyrant::RDBQC_NUMLT -
number is less than
-
TokyoTyrant::RDBQC_NUMLE -
number is less than or equal to
-
TokyoTyrant::RDBQC_NUMBT -
number is between two tokens of
-
TokyoTyrant::RDBQC_NUMOREQ -
number is equal to at least one token in
-
TokyoTyrant::RDBQC_NEGATE -
negation flag
-
TokyoTyrant::RDBQC_NOIDX -
no index flag
-
TokyoTyrant::RDBQO_STRASC -
string ascending
-
TokyoTyrant::RDBQO_STRDESC -
string descending
-
TokyoTyrant::RDBQO_NUMASC -
number ascending
-
TokyoTyrant::RDBQO_NUMDESC -
number descending
-
TokyoTyrant::RDBIT_LEXICAL -
lexical string
-
TokyoTyrant::RDBIT_DECIMAL -
decimal string
-
TokyoTyrant::RDBIT_TOKEN -
token inverted index (Tokyo Tyrant >= 1.1.29)
-
TokyoTyrant::RDBIT_QGRAM -
QGRAM inverted index (Tokyo Tyrant >= 1.1.29)
-
TokyoTyrant::RDBIT_OPT -
optimize
-
TokyoTyrant::RDBIT_VOID -
void
-
TokyoTyrant::RDBIT_KEEP -
keep existing index
-
TokyoTyrant::RDBQCFTS_PH -
full-text search with the phrase of (Tokyo Tyrant >= 1.1.29)
-
TokyoTyrant::RDBQCFTS_AND -
full-text search with all tokens in (Tokyo Tyrant >= 1.1.29)
-
TokyoTyrant::RDBQCFTS_OR -
full-text search with at least one token in (Tokyo Tyrant >= 1.1.29)
-
TokyoTyrant::RDBQCFTS_EX -
full-text search with the compound expression of (Tokyo Tyrant >= 1.1.29)
-
TokyoTyrant::RDBQCFTS_AND -
Metasearch union between records (Tokyo Tyrant >= 1.1.33)
-
TokyoTyrant::RDBQCFTS_OR -
Metasearch intersection between records (Tokyo Tyrant >= 1.1.33)
-
TokyoTyrant::RDBQCFTS_EX -
Metasearch difference between records (Tokyo Tyrant >= 1.1.33)
-
TokyoTyrant::RDBT_RECON -
Whether to reconnect on connection failure. It is recommended to have this parameter on for persistent connections
-
TokyoTyrant::RDBXOLCK_REC -
record locking
-
TokyoTyrant::RDBXOLCK_GLB -
global locking
-
TokyoTyrant::RDBREC_INT -
record type int
-
TokyoTyrant::RDBREC_DBL -
record type float (double)
-
TokyoTyrant::TTE_SUCCESS -
success
-
TokyoTyrant::TTE_INVALID -
invalid operation
-
TokyoTyrant::TTE_NOHOST -
host not found
-
TokyoTyrant::TTE_REFUSED -
connection refused
-
TokyoTyrant::TTE_SEND -
send error
-
TokyoTyrant::TTE_RECV -
recv error
-
TokyoTyrant::TTE_KEEP -
record exist
-
TokyoTyrant::TTE_NOREC -
no record found
-
TokyoTyrant::TTE_MISC -
miscellaneous error
TokyoTyrant::add
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrant::add — Adds to a numeric key
Opis
Adds to an int or double value. This increments the value by the given amount and returns the new value. If the key does not exist a new key is created with initial value of the increment parameter.
Parametry
-
key -
The string key
-
increment -
The amount to increment
-
type -
TokyoTyrant::RDBREC_INTorTokyoTyrant::RDBREC_DBLconstant. If this parameter is omitted the type is guessed from theincrementparameters type.
Zwracane wartości
Returns the new value on success
Przykłady
Przykład #1 TokyoTyrant::add() example
<?php
$tt = new TokyoTyrant("localhost", TokyoTyrant::RDBDEF_PORT);
/* Adds integer 3 to key and creates a new key */
$tt->add("test", 3);
/* String value is converted to double */
echo $tt->add("test", "3.5", TokyoTyrant::RDBREC_DBL);
?>
Powyższy przykład wyświetli coś podobnego do:
6.5
Zobacz też:
- TokyoTyrant::put() - Puts values
- TokyoTyrant::putcat() - Concatenates to a record
- TokyoTyrant::putkeep() - Puts a record
TokyoTyrant::connect
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrant::connect — Connect to a database
Opis
$host
[, int $port = TokyoTyrant::RDBDEF_PORT
[, array $options
]] )Connects to a remote database
Parametry
-
host -
The hostname
-
port -
The port. Default: 1978
-
options -
Connection options: timeout (default: 5.0), reconnect (default:
TRUE) and persistent (default:TRUE)
Zwracane wartości
This method returns the current object and throws TokyoTyrantException on failure.
Przykłady
Przykład #1 TokyoTyrant::connect() example
<?php
$tt = new TokyoTyrant();
$tt->connect("localhost", TokyoTyrant::RDBDEF_PORT)->put("test", "value");
?>
TokyoTyrant::connectUri
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrant::connectUri — Connects to a database
Parametry
-
uri -
An URI to the database. For example tcp://localhost:1979/
Zwracane wartości
This method returns the current object and throws TokyoTyrantException on failure.
Przykłady
Przykład #1 TokyoTyrant::connectUri() example
<?php
$tt = new TokyoTyrant();
$tt->connectUri("tcp://localhost:1978/")->put("test", "hi");
?>
TokyoTyrant::__construct
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrant::__construct — Construct a new TokyoTyrant object
Opis
$host
[, int $port = TokyoTyrant::RDBDEF_PORT
[, array $options
]]] )Constructs a new TokyoTyrant object and optionally connects to the database
Parametry
-
host -
The hostname. Default:
NULL -
port -
port number. Default: 1978
-
options -
Connection options: timeout (default: 5.0), reconnect (default:
TRUE) and persistent (default:TRUE)
Zwracane wartości
Throws TokyoTyrantException if connection to database fails
Zobacz też:
- TokyoTyrant::connect() - Connect to a database
- TokyoTyrant::connectUri() - Connects to a database
TokyoTyrant::copy
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrant::copy — Copies the database
Parametry
-
path -
Path to where to copy the database. The user running the remote database must have a write access to the directory.
Zwracane wartości
This method returns the current object and throws TokyoTyrantException on failure.
Przykłady
Przykład #1 TokyoTyrant::copy() example
<?php
$tt = new TokyoTyrant("localhost", 1978);
$tt->copy("/tmp/foobar.tct");
?>
TokyoTyrant::ext
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrant::ext — Execute a remote script
Opis
$name
, int $options
, string $key
, string $value
)Executes a remote script extension.
Parametry
-
name -
Name of the function to execute
-
options -
Either
TokyoTyrant::RDBXO_LCKRECfor record locking andTokyoTyrant::RDBXO_LCKGLBfor global locking. -
key -
The key to pass to the function
-
value -
The value to pass to the function
Zwracane wartości
Returns the result of the script function
Przykłady
Przykład #1 TokyoTyrant::ext() example
<?php
$tt = new TokyoTyrant("localhost", 1978);
echo $tt->ext("somefunc", TokyoTyrant::RDBXO_LCKREC, "some_key", "some_value");
?>
TokyoTyrant::fwmKeys
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrant::fwmKeys — Returns the forward matching keys
Opis
$prefix
, int $max_recs
)Returns the forward matching keys from the database
Parametry
-
prefix -
Prefix of the keys
-
max_recs -
Maximum records to return
Zwracane wartości
Returns an array of matching keys. The values are not returned
Przykłady
Przykład #1 TokyoTyrant::fwmKeys() example
<?php
$tt = new TokyoTyrant("localhost");
/* Create 20 macthing keys */
for ($i = 0; $i < 20; $i++) {
$tt->put("key_" . $i, "value_" . $i);
}
/* Create 20 non-macthing keys */
for ($i = 0; $i < 20; $i++) {
$tt->put("something_" . $i, "data_" . $i);
}
/* Get five matching keys */
var_dump($tt->fwmKeys("key_", 5));
?>
Powyższy przykład wyświetli coś podobnego do:
array(5) {
[0]=>
string(5) "key_5"
[1]=>
string(6) "key_14"
[2]=>
string(5) "key_6"
[3]=>
string(6) "key_15"
[4]=>
string(5) "key_7"
}
TokyoTyrant::get
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrant::get — The get purpose
Opis
This method is used to return a value or multiple values. This method accepts a string or an array as a value.
Zwracane wartości
Returns a string or an array based on the given parameters. Throws a TokyoTyrantException on error. If string is passed null is returned if the key is not found. In case an array is given as an parameter only existing keys will be returned. It is not an error to pass a key that does not exist.
Przykłady
Przykład #1 TokyoTyrant::get() example
<?php
$tt = new TokyoTyrant("localhost", 1978);
$tt->put("key1", "value1");
$tt->put("key2", "value2");
var_dump($tt->get(array("key1", "key2")));
var_dump($tt->get("key1"));
?>
Powyższy przykład wyświetli:
array(2) {
["key1"]=>
string(6) "value1"
["key2"]=>
string(6) "value2"
}
string(6) "value1"
TokyoTyrant::getIterator
(No version information available, might only be in SVN)
TokyoTyrant::getIterator — Get an iterator
Opis
Gets an iterator for iterating all keys / values in the database.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
This method returns TokyoTyrantIterator object and throws TokyoTyrantException on failure.
Przykłady
Przykład #1 TokyoTyrant::getIterator() example
<?php
$tt = new TokyoTyrant("localhost");
$it = $tt->getIterator();
foreach ($it as $k => $v) {
}
?>
Zobacz też:
- TokyoTyrantTable::getQuery() - Get a query object
- TokyoTyrantTable::getIterator() - Get an iterator
TokyoTyrant::num
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrant::num — Number of records in the database
Opis
Returns the number of records in the database
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns number of records in the database
Przykłady
Przykład #1 TokyoTyrant::num() example
<?php
/* Connect to a database on default port */
$tt = new TokyoTyrant("localhost");
/* Echo the number of records */
echo $tt->num();
?>
Powyższy przykład wyświetli coś podobnego do:
1234
TokyoTyrant::out
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrant::out — Removes records
Opis
Removes a record or multiple records. This method accepts a string for a single key or an array of keys for multiple records.
Zwracane wartości
This method returns the current object and throws TokyoTyrantException on failure.
Przykłady
Przykład #1 TokyoTyrant::out() example
<?php
/* Connect to a database on default port */
$tt = new TokyoTyrant("localhost");
$tt->put("test1", "value1");
$tt->put("test2", "value2");
$tt->out(array("test1", "test2"));
?>
TokyoTyrant::put
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrant::put — Puts values
Opis
Puts a key-value pair into the database or multiple key-value pairs. If keys is
string then the second parameter value defines the value.
The second parameter is mandatory if keys is a string. If the key exists the value
will be replaced with new value.
Parametry
-
keys -
A string key or an array of key-value pairs
-
value -
The value in case a string key is used
Zwracane wartości
This method returns a reference to the current object and throws TokyoTyrantException on failure.
Przykłady
Przykład #1 TokyoTyrant::put() example
<?php
/* Connect to a database on default port */
$tt = new TokyoTyrant("localhost");
/* Put single key-value pair */
$tt->put("key", "value");
/* Put key-value pairs, new value overwrites the old */
$tt->put(array("key1" => "value1", "key" => "value2"));
/* Get back one key */
echo $tt->get("key");
?>
Powyższy przykład wyświetli:
value2
TokyoTyrant::putCat
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrant::putCat — Concatenates to a record
Opis
Appends a value into existing key or multiple values if keys is an array.
The second parameter is mandatory if keys is a string. If the record does
not exist a new record is created.
Parametry
Zwracane wartości
This method returns a reference to the current object and throws TokyoTyrantException on failure.
Przykłady
Przykład #1 TokyoTyrant::putCat() example
<?php
/* Connect to a database on default port */
$tt = new TokyoTyrant("localhost");
/* Create a new key */
$tt->put("key", "value");
/* Concatenate single key-value pair */
$tt->putCat("key", " has more data");
/* Echo the key */
echo $tt->get("key");
?>
Powyższy przykład wyświetli:
value has more data
TokyoTyrant::putKeep
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrant::putKeep — Puts a record
Opis
Puts a key-value pair into the database or multiple key-value pairs. If keys is
string then the second parameter value defines the value.
The second parameter is mandatory if keys is a string. If the key already
exists this method throws an exception indicating that the records exists.
Zwracane wartości
This method returns a reference to the current object and throws TokyoTyrantException on failure.
Przykłady
Przykład #1 tokyotyrant::putKeep() example
<?php
/* Connect to a database on default port */
$tt = new TokyoTyrant("localhost");
/* Create a new key */
$tt->put("key", "value");
try {
$tt->putKeep("key", "new value");
} catch (TokyoTyrantException $e) {
if ($e->getCode() === TokyoTyrant::TTE_KEEP) {
echo "Existing record! Not modified\n";
} else {
echo "Error: " , $e->getMessage() , "\n";
}
}
echo $tt->get("key");
?>
Powyższy przykład wyświetli:
Existing record! Not modified value
TokyoTyrant::putNr
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrant::putNr — Puts value
Opis
Puts a key-value pair into the database or multiple key-value pairs. If keys is
string then the second parameter value defines the value.
The second parameter is mandatory if keys is a string. This method does not wait
for the response from the server.
Parametry
-
keys -
A string key or an array of key-value pairs
-
value -
The value in case a string key is used
Zwracane wartości
This method returns a reference to the current object and throws TokyoTyrantException on failure.
Przykłady
Przykład #1 TokyoTyrant::putNr() example
<?php
/* Connect to a database on default port */
$tt = new TokyoTyrant("localhost");
/* Put single key-value pair */
$tt->putNr("key", "value");
/* Put key-value pairs */
$tt->putNr(array("key1" => "value1", "key2" => "value2"));
/* Get back one key */
echo $tt->get("key1");
?>
Powyższy przykład wyświetli:
value1
Zobacz też:
- TokyoTyrant::putNr()
- TokyoTyrant::putKeep() - Puts a record
- TokyoTyrant::putCat() - Concatenates to a record
TokyoTyrant::putShl
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrant::putShl — Concatenates to a record
Opis
Concatenate to a record and shift to left.
Parametry
-
key -
A string key
-
value -
The value to concatenate
-
width -
The width of the record
Zwracane wartości
This method returns a reference to the current object and throws TokyoTyrantException on failure.
Przykłady
Przykład #1 TokyoTyrant::putShl() example
<?php
/* Connect to a database on default port */
$tt = new TokyoTyrant("localhost");
/* Create a new key */
$tt->put("key", "just a long piece of data");
/* Concatenate and shift to left */
$tt->putShl("key", " and string", 15);
/* Echo the key */
echo $tt->get("key");
?>
Powyższy przykład wyświetli:
data and string
Zobacz też:
- TokyoTyrant::put() - Puts values
- TokyoTyrant::putKeep() - Puts a record
- TokyoTyrant::putCat() - Concatenates to a record
TokyoTyrant::restore
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrant::restore — Restore the database
Opis
$log_dir
, int $timestamp
[, bool $check_consistency = true
] )Restore the database from the update log.
This method is not supported on 32bit platforms.
Parametry
-
log_dir -
Directory where the log is
-
timestamp -
Beginning timestamp with microseconds
-
check_consistency -
Whether to check consistency: Default:
TRUE
Zwracane wartości
This method returns the current object and throws TokyoTyrantException on failure.
TokyoTyrant::setMaster
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrant::setMaster — Set the replication master
Opis
$host
, int $port
, int $timestamp
[, bool $check_consistency = true
] )Sets the replication master of the database
This method is not supported on 32bit platforms.
Parametry
-
host -
Hostname of the replication master. If
NULLthe replication is disabled. -
port -
Port of the replication master
-
timestamp -
Beginning timestamp with microseconds
-
check_consistency -
Whether to check consistency.
Zwracane wartości
This method returns the current object and throws TokyoTyrantException on failure.
Przykłady
Przykład #1 TokyoTyrant::setMaster() example
<?php
/* Connect to a database */
$tt = new TokyoTyrant("tokyotyrant.example.com");
/* Disable the replication */
$tt->setMaster(NULL, 0, 0);
?>
Zobacz też:
- Classname::Method()
TokyoTyrant::size
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrant::size — Returns the size of the value
Opis
$key
)Returns the size of a value by key
Parametry
-
key -
The key of which size to fetch
Zwracane wartości
Returns the size of the key or throw TokyoTyrantException on error
Przykłady
Przykład #1 TokyoTyrant::size() example
<?php
$tt = new TokyoTyrant("localhost");
$tt->put("test_key", "12345");
echo $tt->size("test_key");
?>
Powyższy przykład wyświetli:
5
TokyoTyrant::stat
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrant::stat — Get statistics
Opis
Returns statistics of the remote database
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns an array of key value pairs describing the statistics
Przykłady
Przykład #1 TokyoTyrant::stat() example
<?php
$tt = new TokyoTyrant("localhost");
var_dump($tt->stat());
?>
Powyższy przykład wyświetli coś podobnego do:
array(19) {
["version"]=>
string(6) "1.1.28"
["libver"]=>
string(3) "311"
["protver"]=>
string(4) "0.91"
["os"]=>
string(5) "Linux"
["time"]=>
string(17) "1247358357.665630"
["pid"]=>
string(5) "14348"
["sid"]=>
string(8) "59025947"
["type"]=>
string(9) "on-memory"
["path"]=>
string(1) "*"
["rnum"]=>
string(1) "4"
["size"]=>
string(6) "262856"
["bigend"]=>
string(1) "0"
["fd"]=>
string(1) "5"
["loadavg"]=>
string(8) "0.000000"
["memsize"]=>
string(8) "77328384"
["memrss"]=>
string(7) "1183744"
["ru_real"]=>
string(13) "162776.042152"
["ru_user"]=>
string(8) "0.476029"
["ru_sys"]=>
string(8) "8.652540"
}
Zobacz też:
- Classname::Method()
TokyoTyrant::sync
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrant::sync — Synchronize the database
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
This method returns the current object and throws TokyoTyrantException on failure.
TokyoTyrant::tune
(PECL tokyo_tyrant >= 0.2.0)
TokyoTyrant::tune — Tunes connection values
Opis
Tunes database connection options.
Parametry
-
timeout -
The objects timeout value (default: 5.0)
-
options -
Bitmask of options to tune. This can be either 0 or
TokyoTyrant::RDBT_RECON. It is recommended not to change the second parameter.
Zwracane wartości
This method returns a reference to the current object and throws TokyoTyrantException on failure.
TokyoTyrant::vanish
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrant::vanish — Empties the database
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
This method returns the current object and throws TokyoTyrantException on failure.
Przykłady
Przykład #1 TokyoTyrant::vanish() example
<?php
$tt = new TokyoTyrant("localhost");
$tt->vanish();
?>
Spis treści
- TokyoTyrant::add — Adds to a numeric key
- TokyoTyrant::connect — Connect to a database
- TokyoTyrant::connectUri — Connects to a database
- TokyoTyrant::__construct — Construct a new TokyoTyrant object
- TokyoTyrant::copy — Copies the database
- TokyoTyrant::ext — Execute a remote script
- TokyoTyrant::fwmKeys — Returns the forward matching keys
- TokyoTyrant::get — The get purpose
- TokyoTyrant::getIterator — Get an iterator
- TokyoTyrant::num — Number of records in the database
- TokyoTyrant::out — Removes records
- TokyoTyrant::put — Puts values
- TokyoTyrant::putCat — Concatenates to a record
- TokyoTyrant::putKeep — Puts a record
- TokyoTyrant::putNr — Puts value
- TokyoTyrant::putShl — Concatenates to a record
- TokyoTyrant::restore — Restore the database
- TokyoTyrant::setMaster — Set the replication master
- TokyoTyrant::size — Returns the size of the value
- TokyoTyrant::stat — Get statistics
- TokyoTyrant::sync — Synchronize the database
- TokyoTyrant::tune — Tunes connection values
- TokyoTyrant::vanish — Empties the database
The TokyoTyrantTable class
(No version information available, might only be in SVN)
Wstęp
Provides an API to the table databases. A table database can be create using the following command: ttserver -port 1979 /tmp/tt_table.tct. In Tokyo Tyrant the table API is a schemaless database which can store arbitrary amount of key-value pairs under a single primary key.
Krótki opis klasy
$host
[, int $port = TokyoTyrant::RDBDEF_PORT
[, array $options
]] )$host
[, int $port = TokyoTyrant::RDBDEF_PORT
[, array $options
]]] )$log_dir
, int $timestamp
[, bool $check_consistency = true
] )$host
, int $port
, int $timestamp
[, bool $check_consistency = true
] )TokyoTyrantTable::add
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrantTable::add — Adds a record
Opis
This method is not supported with table databases.
Parametry
-
key -
The string key
-
increment -
The amount to increment
-
type -
TokyoTyrant::RDB_RECINTorTokyoTyrant::RDB_RECDBLconstant. If this parameter is omitted the type is guessed from theincrementparameters type.
Zwracane wartości
This method throws an TokyoTyrantException if used through this class.
TokyoTyrantTable::genUid
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrantTable::genUid — Generate unique id
Opis
Generates an unique id inside the table database. In table databases rows are referenced using a numeric primary key.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns an unique id or throws TokyoTyrantException on error
Przykłady
Przykład #1 TokyoTyrantTable::genUid() example
<?php
$tt = new TokyoTyrantTable("localhost", 1122);
echo $tt->genUid();
?>
Powyższy przykład wyświetli coś podobnego do:
4
TokyoTyrantTable::get
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrantTable::get — Get a row
Opis
Gets a row from table database. keys is a single integer for
the primary key of the row or an array of integers for multiple rows.
Parametry
-
keys -
The primary key, can be a string or an integer
Zwracane wartości
Returns the row as an array
Przykłady
Przykład #1 TokyoTyrantTable::get() example
<?php
/* Connect to a table database */
$tt = new TokyoTyrantTable("localhost", 1979);
/* Passing null to put generates a new uid */
$index = $tt->put(null, array("column1" => "some data", "column2" => "more data"));
/* Get the row back */
var_dump($tt->get($index));
?>
Powyższy przykład wyświetli:
array(2) {
["column1"]=>
string(9) "some data"
["column2"]=>
string(9) "more data"
}
Notatki
Informacja:
Starting from version 0.3.0 this method accepts array as parameter. Please note that multi-get on tables is not binary-safe.
TokyoTyrantTable::getIterator
(No version information available, might only be in SVN)
TokyoTyrantTable::getIterator — Get an iterator
Opis
Gets an iterator for iterating all keys / values in the database.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
This method returns TokyoTyrantIterator object and throws TokyoTyrantException on failure.
Przykłady
Przykład #1 TokyoTyrantTable::getIterator() example
<?php
$tt = new TokyoTyrantTable("localhost");
$it = $tt->getIterator();
foreach ($it as $k => $v) {
var_dump($k, $v);
}
?>
Zobacz też:
- TokyoTyrantTable::getQuery() - Get a query object
- TokyoTyrant::getIterator() - Get an iterator
TokyoTyrantTable::getQuery
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrantTable::getQuery — Get a query object
Opis
Get a query object to execute searches on the database
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns TokyoTyrantQuery on success and throws TokyoTyrantException on error
Przykłady
Przykład #1 TokyoTyrantTable::getQuery() example
<?php
/* Connect to a table database */
$table = new TokyoTyrantTable("localhost", 1979);
/* Put a few rows */
$table->put(null, array("column1" => "some data", "column2" => "more data"));
$table->put(null, array("something" => "value", "data" => "good data"));
/* Get query object */
$query = $table->getQuery();
/* Add condition to query */
$query->addCond('data', TokyoTyrant::RDBQC_STREQ, 'good data');
/* Get matching rows */
var_dump($query->search());
?>
Powyższy przykład wyświetli coś podobnego do:
array(1) {
[11]=>
array(2) {
["something"]=>
string(5) "value"
["data"]=>
string(9) "good data"
}
}
Zobacz też:
- TokyoTyrantQuery::search() - Searches records
- TokyoTyrantQuery::out() - Removes records based on query
TokyoTyrantTable::out
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrantTable::out — Remove records
Parametry
-
keys -
A single integer key or an array of integers
Zwracane wartości
This method returns the current object and throws TokyoTyrantException on failure.
Przykłady
Przykład #1 TokyoTyrantTable::out() example
<?php
/* Connect to a table database */
$tt = new TokyoTyrantTable("localhost", 1979);
/* Passing null to put generates a new uid */
$index = $tt->put(null, array("column1" => "some data", "column2" => "more data"));
/* Delete the row */
$tt->out($index);
?>
TokyoTyrantTable::put
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrantTable::put — Store a row
Opis
$key
, array $columns
)
Puts a new row into the database. This method parameters are key which is
the primary key of the row, passing NULL will generate a new unique id. value
is an array containing the row contents which is usually key value pairs.
Parametry
-
key -
The primary key of the row
-
columns -
The row contents
Zwracane wartości
Returns the primary key on success and throws TokyoTyrantException on error
Przykłady
Przykład #1 TokyoTyrantTable::put() example
<?php
/* Connect to a table database */
$tt = new TokyoTyrantTable("localhost", 1979);
/* Passing null to put generates a new uid */
$index = $tt->put(null, array("column1" => "some data", "column2" => "more data"));
/* Get the row back */
var_dump($tt->get($index));
/* Modify an existing row */
$tt->put($index, array("column1" => "other data", "column2" => "better data"));
/* Get the row back */
var_dump($tt->get($index));
?>
Powyższy przykład wyświetli:
array(2) {
["column1"]=>
string(9) "some data"
["column2"]=>
string(9) "more data"
}
array(2) {
["column1"]=>
string(10) "other data"
["column2"]=>
string(11) "better data"
}
TokyoTyrantTable::putCat
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrantTable::putCat — Concatenates to a row
Opis
$key
, array $columns
)This method can be used to add new columns to existing records. Existing keys will be left unmodified but any new columns will be appended to the row. Passing null as key will generate a new row.
Parametry
-
key -
The primary key of the row or
NULL -
columns -
Array of row contents
Zwracane wartości
Returns the primary key and throws TokyoTyrantException on error.
Przykłady
Przykład #1 TokyoTyrantTable::putCat() example
<?php
/* Connect to a table database */
$tt = new TokyoTyrantTable("localhost", 1979);
/* Passing null to put generates a new uid */
$index = $tt->put(null, array("column1" => "some data", "column2" => "more data"));
/* Get the row back */
var_dump($tt->get($index));
/* Modify an existing row */
$tt->putcat($index, array("column1" => "something new", "new_column" => "other data"));
/* Get the row back */
var_dump($tt->get($index));
?>
Powyższy przykład wyświetli:
array(2) {
["column1"]=>
string(9) "some data"
["column2"]=>
string(9) "more data"
}
array(3) {
["column1"]=>
string(9) "some data"
["column2"]=>
string(9) "more data"
["new_column"]=>
string(10) "other data"
}
TokyoTyrantTable::putKeep
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrantTable::putKeep — Put a new record
Opis
$key
, array $columns
)Puts a new record into the database. If the key already exists this method throws an exception indicating that the records exists.
Parametry
-
key -
The primary key of the row or
NULL -
columns -
Array of the row contents
Zwracane wartości
Returns the primary key and throws TokyoTyrantException on error.
Przykłady
Przykład #1 TokyoTyrantTable::putKeep() example
<?php
/* Connect to a table database */
$tt = new TokyoTyrantTable("localhost", 1979);
/* Passing null to put generates a new uid */
$index = $tt->put(null, array("column1" => "some data", "column2" => "more data"));
/* Get the row back */
var_dump($tt->get($index));
try {
$tt->putKeep($index, array("column1" => "something new", "new_column" => "other data"));
} catch (TokyoTyrantException $e) {
if ($e->getCode() === TokyoTyrant::TTE_KEEP) {
echo "Existing record! Not modified\n";
} else {
echo "Error: " , $e->getMessage() , "\n";
}
}
/* Get the row back */
var_dump($tt->get($index));
?>
Powyższy przykład wyświetli coś podobnego do:
array(2) {
["column1"]=>
string(9) "some data"
["column2"]=>
string(9) "more data"
}
Existing record! Not modified
array(2) {
["column1"]=>
string(9) "some data"
["column2"]=>
string(9) "more data"
}
TokyoTyrantTable::putNr
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrantTable::putNr — Puts value
Opis
This method is not supported on table databases. Calling this method through TokyoTyrantTable is considered an error and an TokyoTyrantException will be thrown.
Parametry
-
keys -
A string key or an array of key-value pairs
-
value -
The value in case a string key is used
Zwracane wartości
This method is not supported on table databases. Calling this method through TokyoTyrantTable is considered an error and an TokyoTyrantException will be thrown.
Zobacz też:
- TokyoTyrant::putNr() - Puts value
- TokyoTyrant::putKeep() - Puts a record
- TokyoTyrant::putCat() - Concatenates to a record
TokyoTyrantTable::putShl
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrantTable::putShl — Concatenates to a record
Opis
$key
, string $value
, int $width
)This method is not supported on table databases. Calling this method through TokyoTyrantTable is considered an error and an TokyoTyrantException will be thrown.
Parametry
-
key -
A string key
-
value -
The value to concatenate
-
width -
The width of the record
Zwracane wartości
This method is not supported on table databases.
Zobacz też:
- TokyoTyrant::put() - Puts values
- TokyoTyrant::putKeep() - Puts a record
- TokyoTyrant::putCat() - Concatenates to a record
- TokyoTyrantTable::put() - Store a row
- TokyoTyrantTable::putKeep() - Put a new record
- TokyoTyrantTable::putCat() - Concatenates to a row
TokyoTyrantTable::setIndex
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrantTable::setIndex — Sets index
Opis
Sets an index on a specified column. The index type is one of the TokyoTyrant::RDBIT_* constants.
Passing TokyoTyrant::RDBIT_VOID removes the index.
Parametry
-
column -
The name of the column
-
type -
The index type
Zwracane wartości
This method returns the current object and throws TokyoTyrantException on failure.
Spis treści
- TokyoTyrantTable::add — Adds a record
- TokyoTyrantTable::genUid — Generate unique id
- TokyoTyrantTable::get — Get a row
- TokyoTyrantTable::getIterator — Get an iterator
- TokyoTyrantTable::getQuery — Get a query object
- TokyoTyrantTable::out — Remove records
- TokyoTyrantTable::put — Store a row
- TokyoTyrantTable::putCat — Concatenates to a row
- TokyoTyrantTable::putKeep — Put a new record
- TokyoTyrantTable::putNr — Puts value
- TokyoTyrantTable::putShl — Concatenates to a record
- TokyoTyrantTable::setIndex — Sets index
The TokyoTyrantQuery class
(No version information available, might only be in SVN)
Wstęp
This class is used to query the table databases
Krótki opis klasy
TokyoTyrantQuery::addCond
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrantQuery::addCond — Adds a condition to the query
Opis
Adds a condition to the query. Condition can be something like: get all keys which value matches expr.
Parametry
-
name -
Name of the column in the condition
-
op -
The operator. One of the
TokyoTyrant::RDBQC_*constants -
expr -
The expression
Zwracane wartości
This method returns the current object and throws TokyoTyrantException on failure.
Przykłady
Przykład #1 TokyoTyrantQuery::addCond() example
<?php
/* Connect to a table database */
$tt = new TokyoTyrantTable("localhost", 1979);
/* Add rows */
$tt->put(null, array("column1" => "some data", "column2" => "something here"));
$tt->put(null, array("column1" => "more data", "column2" => "best data this far"));
$tt->put(null, array("column1" => "again data", "column3" => "not here"));
$tt->put(null, array("column45" => "random data", "column2" => "something along the lines"));
$tt->put(null, array("column21" => "test data", "column2" => "generating.."));
$tt->put(null, array("column1" => "foobar data", "column2" => "value here"));
/* Get a new query object */
$query = $tt->getQuery();
/* Add a search condition */
$query->addCond("column2", TokyoTyrant::RDBQC_STROR, "something");
/* Dump the search results */
var_dump($query->search());
?>
Powyższy przykład wyświetli:
array(2) {
[1]=>
array(2) {
["column1"]=>
string(9) "some data"
["column2"]=>
string(14) "something here"
}
[4]=>
array(2) {
["column45"]=>
string(11) "random data"
["column2"]=>
string(25) "something along the lines"
}
}
Zobacz też:
- Classname::Method()
TokyoTyrantQuery::__construct
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrantQuery::__construct — Construct a new query
Parametry
-
table -
TokyoTyrantTable object with active database connection
Zwracane wartości
Returns a new TokyoTyrantQuery object and throws TokyoTyrantException on error
Przykłady
Przykład #1 TokyoTyrantQuery::__construct() example
<?php
$tt = new TokyoTyrantTable("localhost", 1979);
$query = new TokyoTyrantQuery($tt);
/* Work with $query */
?>
TokyoTyrantQuery::count
(No version information available, might only be in SVN)
TokyoTyrantQuery::count — Counts records
Opis
Returns a count of how many records a query returns.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns a count of matching rows and throws TokyoTyrantException on error
Przykłady
Przykład #1 TokyoTyrantQuery::count() example
<?php
/* Connect to a table database */
$tt = new TokyoTyrantTable("localhost", 1979);
/* Add rows */
$tt->put(null, array("column1" => "some data", "column2" => "something here"));
$tt->put(null, array("column1" => "more data", "column2" => "best data this far"));
$tt->put(null, array("column1" => "again data", "column3" => "not here"));
$tt->put(null, array("column45" => "random data", "column2" => "something along the lines"));
$tt->put(null, array("column21" => "test data", "column2" => "generating.."));
$tt->put(null, array("column1" => "foobar data", "column2" => "value here"));
/* Get a new query object */
$query = $tt->getQuery();
/* Add a search condition */
$query->addCond("column2", TokyoTyrant::RDBQC_STROR, "something");
/* Count the results */
var_dump($query->count());
?>
Powyższy przykład wyświetli:
int(2)
Zobacz też:
- TokyoTyrantQuery::out() - Removes records based on query
- TokyoTyrantQuery::search() - Searches records
- TokyoTyrantQuery::metaSearch() - Retrieve records with multiple queries
TokyoTyrantQuery::current
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrantQuery::current — Returns the current element
Opis
Returns the current element. Part of Iterator interface
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the current row
Przykłady
Przykład #1 TokyoTyrantQuery iterator example
<?php
/* Connect to a table database */
$tt = new TokyoTyrantTable("localhost", 1979);
/* Add rows */
$tt->put(null, array("column1" => "some data", "column2" => "something here"));
$tt->put(null, array("column1" => "more data", "column2" => "best data this far"));
$tt->put(null, array("column1" => "again data", "column3" => "foobar here"));
$tt->put(null, array("column45" => "random data", "column2" => "something along the lines"));
$tt->put(null, array("column21" => "test data", "column2" => "generating.."));
$tt->put(null, array("column1" => "foobar data", "column2" => "value here"));
/* Get a new query object */
$query = $tt->getQuery();
/* Add a search condition */
$query->addCond("column2", TokyoTyrant::RDBQC_STROR, "something");
/* Iterate the results */
foreach ($query as $key => $value) {
echo "pk: $key, columns: ", count($value) ,"\n";
}
?>
Powyższy przykład wyświetli coś podobnego do:
pk: 1, columns: 2 pk: 4, columns: 2
TokyoTyrantQuery::hint
(No version information available, might only be in SVN)
TokyoTyrantQuery::hint — Get the hint string of the query
Opis
Get the hint string of the query. The hint string contains information about an executed query and it could be compared to for example MySQL EXPLAIN statement.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
This method always returns a string
Przykłady
Przykład #1 TokyoTyrantQuery::hint example
<?php
$tt = new TokyoTyrantTable("localhost", 1979);
$tt->vanish();
for ($i = 0; $i < 11; $i++) {
$tt->put(null, array('a_col' => 'a' . $i, 'b_col' => 'b' . $i));
}
$query = $tt->getQuery();
$query->addCond('a_col', TokyoTyrant::RDBQC_STRBW, 'a');
$query->search();
var_dump($query->hint());
?>
Powyższy przykład wyświetli coś podobnego do:
string(72) " scanning the whole table result set size: 11 leaving the natural order "
TokyoTyrantQuery::key
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrantQuery::key — Returns the current key
Opis
Returns the current key. Part of the Iterator interface
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the current key and throws TokyoTyrantException on error
Przykłady
Przykład #1 TokyoTyrantQuery iterator example
<?php
/* Connect to a table database */
$tt = new TokyoTyrantTable("localhost", 1979);
/* Add rows */
$tt->put(null, array("column1" => "some data", "column2" => "something here"));
$tt->put(null, array("column1" => "more data", "column2" => "best data this far"));
$tt->put(null, array("column1" => "again data", "column3" => "foobar here"));
$tt->put(null, array("column45" => "random data", "column2" => "something along the lines"));
$tt->put(null, array("column21" => "test data", "column2" => "generating.."));
$tt->put(null, array("column1" => "foobar data", "column2" => "value here"));
/* Get a new query object */
$query = $tt->getQuery();
/* Add a search condition */
$query->addCond("column2", TokyoTyrant::RDBQC_STROR, "something");
/* Iterate the results */
foreach ($query as $key => $value) {
echo "pk: $key, columns: ", count($value) ,"\n";
}
?>
Powyższy przykład wyświetli coś podobnego do:
pk: 1, columns: 2 pk: 4, columns: 2
TokyoTyrantQuery::metaSearch
(No version information available, might only be in SVN)
TokyoTyrantQuery::metaSearch — Retrieve records with multiple queries
Opis
$queries
, int $type
)Executes multiple queries on a database and returns matching records. The current object is always the left most object in the search.
Parametry
-
queries -
Array of TokyoTyrantQuery objects
-
type -
One of the
TokyoTyrant::RDBMS_*constants
Zwracane wartości
Returns the matching rows and throws TokyoTyrantException on error
Przykłady
Przykład #1 TokyoTyrantQuery::metaSearch() example
<?php
/* Connect to a table database */
$tt = new TokyoTyrantTable("localhost", 1979);
/* Add test data */
$tt->put('cherry', array('color' => 'red'));
$tt->put('strawberry', array('color' => 'red'));
$tt->put('apple', array('color' => 'green'));
$tt->put('lemon', array('color' => 'yellow'));
/* First query */
$query = $tt->getQuery();
$query->addCond('color', TokyoTyrant::RDBQC_STREQ, 'red')->setOrder('color', TokyoTyrant::RDBQO_STRASC);
/* Second query */
$query1 = $tt->getQuery();
$query1->addCond('color', TokyoTyrant::RDBQC_STREQ, 'yellow');
/* Get union between the queries */
var_dump($query->metaSearch(array($query1), TokyoTyrant::RDBMS_UNION));
?>
Powyższy przykład wyświetli:
array(3) {
["cherry"]=>
array(1) {
["color"]=>
string(3) "red"
}
["strawberry"]=>
array(1) {
["color"]=>
string(3) "red"
}
["lemon"]=>
array(1) {
["color"]=>
string(6) "yellow"
}
}
TokyoTyrantQuery::next
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrantQuery::next — Moves the iterator to next entry
Opis
Returns the next result in the resultset. Part of the Iterator interface.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the next row and throws TokyoTyrantException on error.
Przykłady
Przykład #1 TokyoTyrantQuery iterator example
<?php
/* Connect to a table database */
$tt = new TokyoTyrantTable("localhost", 1979);
/* Add rows */
$tt->put(null, array("column1" => "some data", "column2" => "something here"));
$tt->put(null, array("column1" => "more data", "column2" => "best data this far"));
$tt->put(null, array("column1" => "again data", "column3" => "foobar here"));
$tt->put(null, array("column45" => "random data", "column2" => "something along the lines"));
$tt->put(null, array("column21" => "test data", "column2" => "generating.."));
$tt->put(null, array("column1" => "foobar data", "column2" => "value here"));
/* Get a new query object */
$query = $tt->getQuery();
/* Add a search condition */
$query->addCond("column2", TokyoTyrant::RDBQC_STROR, "something");
/* Iterate the results */
foreach ($query as $key => $value) {
echo "pk: $key, columns: ", count($value) ,"\n";
}
?>
Powyższy przykład wyświetli coś podobnego do:
pk: 1, columns: 2 pk: 4, columns: 2
TokyoTyrantQuery::out
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrantQuery::out — Removes records based on query
Opis
Removes all records that match the query. Works exactly like search but removes the records instead of returning them.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
This method returns the current object and throws TokyoTyrantException on failure.
Przykłady
Przykład #1 TokyoTyrantQuery::out() example
<?php
/* Connect to a table database */
$tt = new TokyoTyrantTable("localhost", 1979);
/* Add rows */
$tt->put(null, array("column1" => "some data", "column2" => "something here"));
$tt->put(null, array("column1" => "more data", "column2" => "best data this far"));
$tt->put(null, array("column1" => "again data", "column3" => "foobar here"));
$tt->put(null, array("column45" => "random data", "column2" => "something along the lines"));
$tt->put(null, array("column21" => "test data", "column2" => "generating.."));
$tt->put(null, array("column1" => "foobar data", "column2" => "value here"));
/* Get a new query object */
$query = $tt->getQuery();
/* Add a search condition */
$query->addCond("column2", TokyoTyrant::RDBQC_STROR, "something");
/* Remove matching records */
$query->out();
?>
TokyoTyrantQuery::rewind
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrantQuery::rewind — Rewinds the iterator
Opis
Rewind the resultset and executes the query if it has not been executed. Part of the Iterator interface.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns TRUE
Przykłady
Przykład #1 TokyoTyrantQuery iterator example
<?php
/* Connect to a table database */
$tt = new TokyoTyrantTable("localhost", 1979);
/* Add rows */
$tt->put(null, array("column1" => "some data", "column2" => "something here"));
$tt->put(null, array("column1" => "more data", "column2" => "best data this far"));
$tt->put(null, array("column1" => "again data", "column3" => "foobar here"));
$tt->put(null, array("column45" => "random data", "column2" => "something along the lines"));
$tt->put(null, array("column21" => "test data", "column2" => "generating.."));
$tt->put(null, array("column1" => "foobar data", "column2" => "value here"));
/* Get a new query object */
$query = $tt->getQuery();
/* Add a search condition */
$query->addCond("column2", TokyoTyrant::RDBQC_STROR, "something");
/* Iterate the results */
foreach ($query as $key => $value) {
echo "pk: $key, columns: ", count($value) ,"\n";
}
?>
Powyższy przykład wyświetli coś podobnego do:
pk: 1, columns: 2 pk: 4, columns: 2
TokyoTyrantQuery::search
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrantQuery::search — Searches records
Opis
Executes a search on the table database. Returns an array of arrays containing the matching records. In the returned array the first level is the primary key of the data and the second level is the row data.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the matching rows and throws TokyoTyrantException on error
Przykłady
Przykład #1 TokyoTyrantQuery::search() example
<?php
/* Connect to a table database */
$tt = new TokyoTyrantTable("localhost", 1979);
/* Add rows */
$tt->put(null, array("column1" => "some data", "column2" => "something here"));
$tt->put(null, array("column1" => "more data", "column2" => "best data this far"));
$tt->put(null, array("column1" => "again data", "column3" => "not here"));
$tt->put(null, array("column45" => "random data", "column2" => "something along the lines"));
$tt->put(null, array("column21" => "test data", "column2" => "generating.."));
$tt->put(null, array("column1" => "foobar data", "column2" => "value here"));
/* Get a new query object */
$query = $tt->getQuery();
/* Add a search condition */
$query->addCond("column2", TokyoTyrant::RDBQC_STROR, "something");
/* Dump the search results */
var_dump($query->search());
?>
Powyższy przykład wyświetli:
array(2) {
[1]=>
array(2) {
["column1"]=>
string(9) "some data"
["column2"]=>
string(14) "something here"
}
[4]=>
array(2) {
["column45"]=>
string(11) "random data"
["column2"]=>
string(25) "something along the lines"
}
}
Zobacz też:
- TokyoTyrantQuery::out() - Removes records based on query
- TokyoTyrantQuery::metaSearch() - Retrieve records with multiple queries
TokyoTyrantQuery::setLimit
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrantQuery::setLimit — Limit results
Opis
Set the maximum amount of records to return on a query.
Parametry
-
max -
Maximum amount of records. Default: -1
-
skip -
How many records to skip from the start. Default: -1
Zwracane wartości
This method returns the current object and throws TokyoTyrantException on failure.
TokyoTyrantQuery::setOrder
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrantQuery::setOrder — Orders results
Parametry
-
name -
The column name to apply the ordering on.
-
type -
The
typecan be one of the following constants:-
TokyoTyrant::RDBQO_STRASC- String ascending -
TokyoTyrant::RDBQO_STRDESC- String descending -
TokyoTyrant::RDBQO_NUMASC- Numberic ascending -
TokyoTyrant::RDBQO_NUMDESC- String descending
-
Zwracane wartości
This method returns the current object.
TokyoTyrantQuery::valid
(PECL tokyo_tyrant >= 0.1.0)
TokyoTyrantQuery::valid — Checks the validity of current item
Opis
Checks if the current item is valid. Part of the Iterator interface
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns TRUE if the current item is valid and FALSE if not.
Przykłady
Przykład #1 TokyoTyrantQuery iterator example
<?php
/* Connect to a table database */
$tt = new TokyoTyrantTable("localhost", 1979);
/* Add rows */
$tt->put(null, array("column1" => "some data", "column2" => "something here"));
$tt->put(null, array("column1" => "more data", "column2" => "best data this far"));
$tt->put(null, array("column1" => "again data", "column3" => "foobar here"));
$tt->put(null, array("column45" => "random data", "column2" => "something along the lines"));
$tt->put(null, array("column21" => "test data", "column2" => "generating.."));
$tt->put(null, array("column1" => "foobar data", "column2" => "value here"));
/* Get a new query object */
$query = $tt->getQuery();
/* Add a search condition */
$query->addCond("column2", TokyoTyrant::RDBQC_STROR, "something");
/* Iterate the results */
foreach ($query as $key => $value) {
echo "pk: $key, columns: ", count($value) ,"\n";
}
?>
Powyższy przykład wyświetli coś podobnego do:
pk: 1, columns: 2 pk: 4, columns: 2
Spis treści
- TokyoTyrantQuery::addCond — Adds a condition to the query
- TokyoTyrantQuery::__construct — Construct a new query
- TokyoTyrantQuery::count — Counts records
- TokyoTyrantQuery::current — Returns the current element
- TokyoTyrantQuery::hint — Get the hint string of the query
- TokyoTyrantQuery::key — Returns the current key
- TokyoTyrantQuery::metaSearch — Retrieve records with multiple queries
- TokyoTyrantQuery::next — Moves the iterator to next entry
- TokyoTyrantQuery::out — Removes records based on query
- TokyoTyrantQuery::rewind — Rewinds the iterator
- TokyoTyrantQuery::search — Searches records
- TokyoTyrantQuery::setLimit — Limit results
- TokyoTyrantQuery::setOrder — Orders results
- TokyoTyrantQuery::valid — Checks the validity of current item
The TokyoTyrantIterator class
(No version information available, might only be in SVN)
Wstęp
Provides an iterator for TokyoTyrant and TokyoTyrantTable objects. The iterator iterates over all keys and values in the database. TokyoTyrantIterator was added in version 0.2.0.
Krótki opis klasy
$host
[, int $port = TokyoTyrant::RDBDEF_PORT
[, array $options
]] )$host
[, int $port = TokyoTyrant::RDBDEF_PORT
[, array $options
]]] )$log_dir
, int $timestamp
[, bool $check_consistency = true
] )$host
, int $port
, int $timestamp
[, bool $check_consistency = true
] )TokyoTyrantIterator::__construct
(PECL tokyo_tyrant >= 0.2.0)
TokyoTyrantIterator::__construct — Construct an iterator
Opis
Construct a new TokyoTyrantIterator object. One connection can have multiple iterators but it is not quaranteed
that all items are traversed in that case. object parameter can be either an of instance
TokyoTyrant or TokyoTyrantTable.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Throws an exception if iterator initialization fails.
Przykłady
Przykład #1 TokyoTyrantIterator::__construct() example
<?php
/* Connect to a table database */
$tt = new TokyoTyrantTable("localhost", 1979);
/* Passing null to put generates a new uid */
$index = $tt->put(null, array("column1" => "some data", "column2" => "more data"));
/* Construct an iterator */
$it = new TokyoTyrantIterator($tt);
foreach ($it as $value) {
var_dump($value);
}
?>
Powyższy przykład wyświetli:
array(2) {
["column1"]=>
string(9) "some data"
["column2"]=>
string(9) "more data"
}
Zobacz też:
- TokyoTyrantIterator::key() - Returns the current key
- TokyoTyrantIterator::current() - Get the current value
- TokyoTyrantIterator::next() - Move to next key
- TokyoTyrantIterator::rewind() - Rewinds the iterator
- TokyoTyrantIterator::key() - Returns the current key
TokyoTyrantIterator::current
(PECL tokyo_tyrant >= 0.2.0)
TokyoTyrantIterator::current — Get the current value
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the current value on success and false on failure.
Zobacz też:
- TokyoTyrantIterator::valid() - Rewinds the iterator
- TokyoTyrantIterator::key() - Returns the current key
- TokyoTyrantIterator::next() - Move to next key
- TokyoTyrantIterator::rewind() - Rewinds the iterator
TokyoTyrantIterator::key
(PECL tokyo_tyrant >= 0.2.0)
TokyoTyrantIterator::key — Returns the current key
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the current key on success and false on failure.
Zobacz też:
- TokyoTyrantIterator::valid() - Rewinds the iterator
- TokyoTyrantIterator::current() - Get the current value
- TokyoTyrantIterator::next() - Move to next key
- TokyoTyrantIterator::rewind() - Rewinds the iterator
TokyoTyrantIterator::next
(PECL tokyo_tyrant >= 0.2.0)
TokyoTyrantIterator::next — Move to next key
Opis
Move to next key during iteration and return it's value.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns the next value on success and false on failure.
Zobacz też:
- TokyoTyrantIterator::valid() - Rewinds the iterator
- TokyoTyrantIterator::key() - Returns the current key
- TokyoTyrantIterator::current() - Get the current value
- TokyoTyrantIterator::rewind() - Rewinds the iterator
TokyoTyrantIterator::rewind
(PECL tokyo_tyrant >= 0.2.0)
TokyoTyrantIterator::rewind — Rewinds the iterator
Opis
Rewinds the iterator for new iteration. Called automatically at the beginning of foreach.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Throws TokyoTyrantException if iterator initialization fails.
Zobacz też:
- TokyoTyrantIterator::valid() - Rewinds the iterator
- TokyoTyrantIterator::current() - Get the current value
- TokyoTyrantIterator::next() - Move to next key
- TokyoTyrantIterator::rewind()
TokyoTyrantIterator::valid
(PECL tokyo_tyrant >= 0.2.0)
TokyoTyrantIterator::valid — Rewinds the iterator
Opis
Checks whether the internal pointer points to valid element.
Parametry
Ta funkcja nie posiada parametrów.
Zwracane wartości
Returns TRUE if the current item is valid and FALSE if not.
Zobacz też:
- TokyoTyrantIterator::key() - Returns the current key
- TokyoTyrantIterator::current() - Get the current value
- TokyoTyrantIterator::next() - Move to next key
- TokyoTyrantIterator::rewind() - Rewinds the iterator
Spis treści
- TokyoTyrantIterator::__construct — Construct an iterator
- TokyoTyrantIterator::current — Get the current value
- TokyoTyrantIterator::key — Returns the current key
- TokyoTyrantIterator::next — Move to next key
- TokyoTyrantIterator::rewind — Rewinds the iterator
- TokyoTyrantIterator::valid — Rewinds the iterator
The TokyoTyrantException class
(No version information available, might only be in SVN)
Wstęp
TokyoTyrantException
Krótki opis klasy
Właściwości
- code
-
The exception code. This can be compared to
TokyoTyrant::TTE_*constants
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Przykłady
- TokyoTyrant — The TokyoTyrant class
- TokyoTyrant::add — Adds to a numeric key
- TokyoTyrant::connect — Connect to a database
- TokyoTyrant::connectUri — Connects to a database
- TokyoTyrant::__construct — Construct a new TokyoTyrant object
- TokyoTyrant::copy — Copies the database
- TokyoTyrant::ext — Execute a remote script
- TokyoTyrant::fwmKeys — Returns the forward matching keys
- TokyoTyrant::get — The get purpose
- TokyoTyrant::getIterator — Get an iterator
- TokyoTyrant::num — Number of records in the database
- TokyoTyrant::out — Removes records
- TokyoTyrant::put — Puts values
- TokyoTyrant::putCat — Concatenates to a record
- TokyoTyrant::putKeep — Puts a record
- TokyoTyrant::putNr — Puts value
- TokyoTyrant::putShl — Concatenates to a record
- TokyoTyrant::restore — Restore the database
- TokyoTyrant::setMaster — Set the replication master
- TokyoTyrant::size — Returns the size of the value
- TokyoTyrant::stat — Get statistics
- TokyoTyrant::sync — Synchronize the database
- TokyoTyrant::tune — Tunes connection values
- TokyoTyrant::vanish — Empties the database
- TokyoTyrantTable — The TokyoTyrantTable class
- TokyoTyrantTable::add — Adds a record
- TokyoTyrantTable::genUid — Generate unique id
- TokyoTyrantTable::get — Get a row
- TokyoTyrantTable::getIterator — Get an iterator
- TokyoTyrantTable::getQuery — Get a query object
- TokyoTyrantTable::out — Remove records
- TokyoTyrantTable::put — Store a row
- TokyoTyrantTable::putCat — Concatenates to a row
- TokyoTyrantTable::putKeep — Put a new record
- TokyoTyrantTable::putNr — Puts value
- TokyoTyrantTable::putShl — Concatenates to a record
- TokyoTyrantTable::setIndex — Sets index
- TokyoTyrantQuery — The TokyoTyrantQuery class
- TokyoTyrantQuery::addCond — Adds a condition to the query
- TokyoTyrantQuery::__construct — Construct a new query
- TokyoTyrantQuery::count — Counts records
- TokyoTyrantQuery::current — Returns the current element
- TokyoTyrantQuery::hint — Get the hint string of the query
- TokyoTyrantQuery::key — Returns the current key
- TokyoTyrantQuery::metaSearch — Retrieve records with multiple queries
- TokyoTyrantQuery::next — Moves the iterator to next entry
- TokyoTyrantQuery::out — Removes records based on query
- TokyoTyrantQuery::rewind — Rewinds the iterator
- TokyoTyrantQuery::search — Searches records
- TokyoTyrantQuery::setLimit — Limit results
- TokyoTyrantQuery::setOrder — Orders results
- TokyoTyrantQuery::valid — Checks the validity of current item
- TokyoTyrantIterator — The TokyoTyrantIterator class
- TokyoTyrantIterator::__construct — Construct an iterator
- TokyoTyrantIterator::current — Get the current value
- TokyoTyrantIterator::key — Returns the current key
- TokyoTyrantIterator::next — Move to next key
- TokyoTyrantIterator::rewind — Rewinds the iterator
- TokyoTyrantIterator::valid — Rewinds the iterator
- TokyoTyrantException — The TokyoTyrantException class
- CUBRID
- DB++
- dBase
- filePro
- Firebird/InterBase
- FrontBase
- IBM DB2 — IBM DB2, Cloudscape and Apache Derby
- Informix
- Ingres — Ingres DBMS, EDBC, i Enterprise Access Gateways
- MaxDB
- Mongo — MongoDB Native Driver
- mSQL
- Mssql — Microsoft SQL Server
- MySQL — MySQL Drivers and Plugins
- Overview of the MySQL PHP drivers
- Mysql — Oryginalne API MySQL
- Mysqli — MySQL Improved Extension
- Mysqlnd — MySQL Native Driver
- mysqlnd_ms — Mysqlnd replication and load balancing plugin
- mysqlnd_qc — Mysqlnd query result cache plugin
- mysqlnd_uh — Mysqlnd user handler plugin
- OCI8 — Oracle OCI8
- Ovrimos SQL
- Paradox — Paradox File Access
- PostgreSQL
- SQLite
- SQLite3
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- SQLite3 — The SQLite3 class
- SQLite3Stmt — The SQLite3Stmt class
- SQLite3Result — The SQLite3Result class
- SQLSRV — Microsoft SQL Server Driver for PHP
- Sybase
- tokyo_tyrant
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Przykłady
- TokyoTyrant — The TokyoTyrant class
- TokyoTyrantTable — The TokyoTyrantTable class
- TokyoTyrantQuery — The TokyoTyrantQuery class
- TokyoTyrantIterator — The TokyoTyrantIterator class
- TokyoTyrantException — The TokyoTyrantException class
- Warstwy abstrakcji
- Rozszerzenia producentów baz danych
- CUBRID
- DB++
- dBase
- filePro
- Firebird/InterBase
- FrontBase
- IBM DB2 — IBM DB2, Cloudscape and Apache Derby
- Informix
- Ingres — Ingres DBMS, EDBC, i Enterprise Access Gateways
- MaxDB
- Mongo — MongoDB Native Driver
- mSQL
- Mssql — Microsoft SQL Server
- MySQL — MySQL Drivers and Plugins
- OCI8 — Oracle OCI8
- Ovrimos SQL
- Paradox — Paradox File Access
- PostgreSQL
- SQLite
- SQLite3
- SQLSRV — Microsoft SQL Server Driver for PHP
- Sybase
- tokyo_tyrant
Rozszerzenia powiązane z systemem plików
Direct IO
Wstęp
PHP supports the direct io functions as described in the Posix Standard (Section 6) for performing I/O functions at a lower level than the C-Language stream I/O functions (fopen(), fread(),..). The use of the DIO functions should be considered only when direct control of a device is needed. In all other cases, the standard filesystem functions are more than adequate.
Informacja:
To rozszerzenie zostało przeniesione do repozytorium » PECL i nie jest rozprowadzane z PHP od wersji 5.1.0.
This extension is only available on Windows Platforms as of PHP 5.0.0
Instalacja/Konfiguracja
Spis treści
Wymagania
Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.
Instalacja
To rozszerzenie » PECL nie jest dołączane do PHP.
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/dio.
DLL z tym rozszerzeniem PECL można pobrać zarówno ze strony » PHP Downloads lub z » http://pecl4win.php.net/
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
One resource type is defined by this extension: a file descriptor returned by dio_open().
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
-
F_DUPFD(integer) -
F_GETFD(integer) -
F_GETFL(integer) -
F_GETLK(integer) -
F_GETOWN(integer) -
F_RDLCK(integer) -
F_SETFL(integer) -
F_SETLK(integer) -
F_SETLKW(integer) -
F_SETOWN(integer) -
F_UNLCK(integer) -
F_WRLCK(integer) -
O_APPEND(integer) -
O_ASYNC(integer) -
O_CREAT(integer) -
O_EXCL(integer) -
O_NDELAY(integer) -
O_NOCTTY(integer) -
O_NONBLOCK(integer) -
O_RDONLY(integer) -
O_RDWR(integer) -
O_SYNC(integer) -
O_TRUNC(integer) -
O_WRONLY(integer) -
S_IRGRP(integer) -
S_IROTH(integer) -
S_IRUSR(integer) -
S_IRWXG(integer) -
S_IRWXO(integer) -
S_IRWXU(integer) -
S_IWGRP(integer) -
S_IWOTH(integer) -
S_IWUSR(integer) -
S_IXGRP(integer) -
S_IXOTH(integer) -
S_IXUSR(integer)
Direct IO Funkcje
dio_close
(PHP 4 >= 4.2.0, PHP 5 <= 5.0.5)
dio_close — Closes the file descriptor given by fd
Opis
$fd
)
The function dio_close() closes the file descriptor
fd.
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 Closing an open file descriptor
<?php
$fd = dio_open('/dev/ttyS0', O_RDWR);
dio_close($fd);
?>
Zobacz też:
- dio_open() - Opens a file (creating it if necessary) at a lower level than the C library input/ouput stream functions allow.
dio_fcntl
(PHP 4 >= 4.2.0, PHP 5 <= 5.0.5)
dio_fcntl — Performs a c library fcntl on fd
Opis
The dio_fcntl() function performs the
operation specified by cmd on the file
descriptor fd. Some commands require
additional arguments args to be supplied.
Parametry
-
fd -
The file descriptor returned by dio_open().
-
cmd -
Can be one of the following operations:
-
F_SETLK- Lock is set or cleared. If the lock is held by someone else dio_fcntl() returns -1. -
F_SETLKW- likeF_SETLK, but in case the lock is held by someone else, dio_fcntl() waits until the lock is released. -
F_GETLK- dio_fcntl() returns an associative array (as described above) if someone else prevents lock. If there is no obstruction key "type" will set toF_UNLCK. -
F_DUPFD- finds the lowest numbered available file descriptor greater than or equal toargsand returns them. -
F_SETFL- Sets the file descriptors flags to the value specified byargs, which can beO_APPEND,O_NONBLOCKorO_ASYNC. To useO_ASYNCyou will need to use the PCNTL extension.
-
-
args -
argsis an associative array, whencmdisF_SETLKorF_SETLLW, with the following keys:-
"start" - offset where lock begins
-
"length" - size of locked area. zero means to end of file
-
"wenth" - Where l_start is relative to: can be
SEEK_SET,SEEK_ENDandSEEK_CUR -
"type" - type of lock: can be
F_RDLCK(read lock),F_WRLCK(write lock) orF_UNLCK(unlock)
-
Zwracane wartości
Returns the result of the C call.
Przykłady
Przykład #1 Setting and clearing a lock
<?php
$fd = dio_open('/dev/ttyS0', O_RDWR);
if (dio_fcntl($fd, F_SETLK, Array("type"=>F_WRLCK)) == -1) {
// the file descriptor appears locked
echo "The lock can not be cleared. It is held by someone else.";
} else {
echo "Lock succesfully set/cleared";
}
dio_close($fd);
?>
Notatki
Informacja: Ta funkcja nie jest dostępna na platformie Windows.
dio_open
(PHP 4 >= 4.2.0, PHP 5 <= 5.0.5)
dio_open — Opens a file (creating it if necessary) at a lower level than the C library input/ouput stream functions allow.
Opis
$filename
, int $flags
[, int $mode = 0
] )dio_open() opens a file and returns a new file descriptor for it.
Parametry
-
filename -
The pathname of the file to open.
-
flags -
The
flagsparameter is a bitwise-ORed value comprising flags from the following list. This value must include one ofO_RDONLY,O_WRONLY, orO_RDWR. Additionally, it may include any combination of the other flags from this list.-
O_RDONLY- opens the file for read access. -
O_WRONLY- opens the file for write access. -
O_RDWR- opens the file for both reading and writing. -
O_CREAT- creates the file, if it doesn't already exist. -
O_EXCL- if bothO_CREATandO_EXCLare set and the file already exists, causes dio_open() to fail. -
O_TRUNC- if the file exists and is opened for write access, the file will be truncated to zero length. -
O_APPEND- write operations write data at the end of the file. -
O_NONBLOCK- sets non blocking mode. -
O_NOCTTY- prevent the OS from assigning the opened file as the process's controlling terminal when opening a TTY device file.
-
-
mode -
If
flagscontainsO_CREAT,modewill set the permissions of the file (creation permissions).Modeis required for correct operation whenO_CREATis specified inmodeand is ignored otherwise.The actual permissions assigned to the created file will be affected by the process's umask setting as per usual.
Zwracane wartości
A file descriptor or FALSE on error.
Przykłady
Przykład #1 Opening a file descriptor
<?php
$fd = dio_open('/dev/ttyS0', O_RDWR | O_NOCTTY | O_NONBLOCK);
dio_close($fd);
?>
dio_read
(PHP 4 >= 4.2.0, PHP 5 <= 5.0.5)
dio_read — Reads bytes from a file descriptor
Opis
$fd
[, int $len = 1024
] )
The function dio_read() reads and returns
len bytes from file with descriptor
fd.
Parametry
-
fd -
The file descriptor returned by dio_open().
-
len -
The number of bytes to read. If not specified, dio_read() reads 1K sized block.
Zwracane wartości
The bytes read from fd.
dio_seek
(PHP 4 >= 4.2.0, PHP 5 <= 5.0.5)
dio_seek — Seeks to pos on fd from whence
Opis
$fd
, int $pos
[, int $whence = SEEK_SET
] )The function dio_seek() is used to change the file position of the given file descriptor.
Parametry
-
fd -
The file descriptor returned by dio_open().
-
pos -
The new position.
-
whence -
Specifies how the position
posshould be interpreted:-
SEEK_SET(default) - specifies thatposis specified from the beginning of the file. -
SEEK_CUR- Specifies thatposis a count of characters from the current file position. This count may be positive or negative. -
SEEK_END- Specifies thatposis a count of characters from the end of the file. A negative count specifies a position within the current extent of the file; a positive count specifies a position past the current end. If you set the position past the current end, and actually write data, you will extend the file with zeros up to that position.
-
Zwracane wartości
Przykłady
Przykład #1 Positioning in a file
<?php
$fd = dio_open('/dev/ttyS0', O_RDWR);
dio_seek($fd, 10, SEEK_SET);
// position is now at 10 characters from the start of the file
dio_seek($fd, -2, SEEK_CUR);
// position is now at 8 characters from the start of the file
dio_seek($fd, -5, SEEK_END);
// position is now at 5 characters from the end of the file
dio_seek($fd, 10, SEEK_END);
// position is now at 10 characters past the end of the file.
// The 10 characters between the end of the file and the current
// position are filled with zeros.
dio_close($fd);
?>
dio_stat
(PHP 4 >= 4.2.0, PHP 5 <= 5.0.5)
dio_stat — Gets stat information about the file descriptor fd
Opis
$fd
)dio_stat() returns information about the given file descriptor.
Zwracane wartości
Returns an associative array with the following keys:
-
"device" - device
-
"inode" - inode
-
"mode" - mode
-
"nlink" - number of hard links
-
"uid" - user id
-
"gid" - group id
-
"device_type" - device type (if inode device)
-
"size" - total size in bytes
-
"blocksize" - blocksize
-
"blocks" - number of blocks allocated
-
"atime" - time of last access
-
"mtime" - time of last modification
-
"ctime" - time of last change
NULL.
dio_tcsetattr
(PHP 4 >= 4.3.0, PHP 5 <= 5.0.5)
dio_tcsetattr — Sets terminal attributes and baud rate for a serial port
Opis
$fd
, array $options
)
dio_tcsetattr() sets the terminal attributes and baud
rate of the open fd.
Parametry
-
fd -
The file descriptor returned by dio_open().
-
options -
The currently available options are:
-
'baud' - baud rate of the port - can be 38400,19200,9600,4800,2400,1800, 1200,600,300,200,150,134,110,75 or 50, default value is 9600.
-
'bits' - data bits - can be 8,7,6 or 5. Default value is 8.
-
'stop' - stop bits - can be 1 or 2. Default value is 1.
-
'parity' - can be 0,1 or 2. Default value is 0.
-
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 Setting the baud rate on a serial port
<?php
$fd = dio_open('/dev/ttyS0', O_RDWR | O_NOCTTY | O_NONBLOCK);
dio_fcntl($fd, F_SETFL, O_SYNC);
dio_tcsetattr($fd, array(
'baud' => 9600,
'bits' => 8,
'stop' => 1,
'parity' => 0
));
while (1) {
$data = dio_read($fd, 256);
if ($data) {
echo $data;
}
}
?>
Notatki
Informacja: Ta funkcja nie jest dostępna na platformie Windows.
dio_truncate
(PHP 4 >= 4.2.0, PHP 5 <= 5.0.5)
dio_truncate — Truncates file descriptor fd to offset bytes
Opis
$fd
, int $offset
)
dio_truncate() truncates a file to at most
offset bytes in size.
If the file previously was larger than this size, the extra data is lost. If the file previously was shorter, it is unspecified whether the file is left unchanged or is extended. In the latter case the extended part reads as zero bytes.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Notatki
Informacja: Ta funkcja nie jest dostępna na platformie Windows.
dio_write
(PHP 4 >= 4.2.0, PHP 5 <= 5.0.5)
dio_write — Writes data to fd with optional truncation at length
Opis
$fd
, string $data
[, int $len = 0
] )
dio_write() writes up to len
bytes from data to file fd.
Parametry
-
fd -
The file descriptor returned by dio_open().
-
data -
The written data.
-
len -
The length of data to write in bytes. If not specified, the function writes all the data to the specified file.
Zwracane wartości
Returns the number of bytes written to fd.
Spis treści
- dio_close — Closes the file descriptor given by fd
- dio_fcntl — Performs a c library fcntl on fd
- dio_open — Opens a file (creating it if necessary) at a lower level than the C library input/ouput stream functions allow.
- dio_read — Reads bytes from a file descriptor
- dio_seek — Seeks to pos on fd from whence
- dio_stat — Gets stat information about the file descriptor fd
- dio_tcsetattr — Sets terminal attributes and baud rate for a serial port
- dio_truncate — Truncates file descriptor fd to offset bytes
- dio_write — Writes data to fd with optional truncation at length
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Direct IO Funkcje
- dio_close — Closes the file descriptor given by fd
- dio_fcntl — Performs a c library fcntl on fd
- dio_open — Opens a file (creating it if necessary) at a lower level than the C library input/ouput stream functions allow.
- dio_read — Reads bytes from a file descriptor
- dio_seek — Seeks to pos on fd from whence
- dio_stat — Gets stat information about the file descriptor fd
- dio_tcsetattr — Sets terminal attributes and baud rate for a serial port
- dio_truncate — Truncates file descriptor fd to offset bytes
- dio_write — Writes data to fd with optional truncation at length
Directories
Instalacja/Konfiguracja
Spis treści
Wymagania
Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.
Instalacja
By używać tych funkcji, nie trzeba niczego instalować. Są one częścią jądra PHP.
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
The Directory class
(No version information available, might only be in SVN)
Krótki opis klasy
Właściwości
- path
-
The directory that was opened.
- handle
-
Can be used with other directory functions such as readdir(), rewinddir() and closedir().
Directory::close
(No version information available, might only be in SVN)
Directory::close — Close directory handle
Opis
$dir_handle
] )
Same as closedir(), only
dir_handle defaults to $this.
Directory::read
(No version information available, might only be in SVN)
Directory::read — Read entry from directory handle
Opis
$dir_handle
] )
Same as readdir(), only
dir_handle defaults to $this.
Directory::rewind
(No version information available, might only be in SVN)
Directory::rewind — Rewind directory handle
Opis
$dir_handle
] )
Same as rewinddir(), only
dir_handle defaults to $this.
Spis treści
- Directory::close — Close directory handle
- Directory::read — Read entry from directory handle
- Directory::rewind — Rewind directory handle
Funkcje katalogów
Zobacz też:
Dla funkcji pokrewnych takich jak dirname(), is_dir(), mkdir(), oraz rmdir(), zobacz rozdział System plików.
chdir
(PHP 4, PHP 5)
chdir — Zmienia bieżący katalog
Opis
$katalog
)
Zmienia bieżący katalog roboczy na
katalog
Parametry
-
katalog -
Nowy bieżący katalog
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Przykład użycia chdir()
<?php
// bieżący katalog
echo getcwd() . "\n";
chdir('public_html');
// nowy bieżący katalog
echo getcwd() . "\n";
?>
Powyższy przykład wyświetli coś podobnego do:
/home/vincent /home/vincent/public_html
Notatki
Informacja: Gdy włączony jest tryb bezpieczny, PHP sprawdza czy katalog, na którym zostaną wykonane operacje, ma takie same UID (owner) jak skrypt, który jest aktualnie wykonywany.
chroot
(PHP 4 >= 4.0.5, PHP 5)
chroot — Zmienia główny katalog
Opis
$katalog
)
Zmienia główny katalog wykonywanego procesu na
katalog
Ta funkcja jest dostępna tylko gdy system ją obsługuje i jest używany CLI, CGI lub Embed SAPI. Również, ta funkcja wymaga praw superużytkownika.
Parametry
-
katalog -
Nowy katalog
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Notatki
Informacja: Ta funkcja nie jest dostępna na platformie Windows.
closedir
(PHP 4, PHP 5)
closedir — Zamyka wskaźnik katalogu
Opis
$uchwyt_katalogu
] )
Zamyka wskaźnik katalogu identyfikowany przez
uchwyt_katalogu. Wskaźnik katalogu musi być wcześniej
otwarty przez opendir().
Parametry
Przykłady
Przykład #1 Przykład closedir()
<?php
$dir = "/etc/php5/";
// Otworzenie podanego katalogu, przeczytanie katalogu do zmiennej i zamknięcie
if (is_dir($dir)) {
if ($dh = opendir($dir)) {
$directory = readdir($dh);
closedir($dh);
}
}
?>
dir
(PHP 4, PHP 5)
dir — Return an instance of the Directory class
Opis
A pseudo-object oriented mechanism for reading a directory. The
given directory is opened.
Parametry
-
directory -
Directory to open
-
context -
Informacja: Obsługa kontekstów została dodana w PHP 5.0.0. Opis kontekstów znajduje się w rozdziale Stream Funkcje.
Zwracane wartości
Returns an instance of Directory, or NULL with
wrong parameters, or FALSE in case of another error.
Przykłady
Przykład #1 dir() example
Please note the fashion in which Directory::read()'s
return value is checked in the example below. We are explicitly
testing whether the return value is identical to (equal to and of
the same type as - see
Comparison Operators for more information) FALSE since
otherwise, any directory entry whose name evaluates to FALSE will
stop the loop.
<?php
$d = dir("/etc/php5");
echo "Handle: " . $d->handle . "\n";
echo "Path: " . $d->path . "\n";
while (false !== ($entry = $d->read())) {
echo $entry."\n";
}
$d->close();
?>
Powyższy przykład wyświetli coś podobnego do:
Handle: Resource id #2 Path: /etc/php5 . .. apache cgi cli
Notatki
Informacja:
The order in which directory entries are returned by the read method is system-dependent.
getcwd
(PHP 4, PHP 5)
getcwd — Wskazuje bieżący katalog roboczy
Opis
Pobiera aktualny katalog roboczy.
Zwracane wartości
Zwraca aktualny katalog roboczy, lub FALSE w przypadku błędu.
W niektórych przypadkach w systemie Uniksowym, getcwd() zwróci
FALSE jeśli którykolwiek z katalogów w ścieżce nie posiada
praw do odczytu lub wykonywania, nawet jeśli bieżący katalog roboczy
posiada takie prawa. Więcej informacji na temat praw można przeczytać w
opisie funckji chmod().
Przykłady
Przykład #1 Przykład użycia getcwd()
<?php
// bieżący katalog roboczy
echo getcwd() . "\n";
chdir('cvs');
// nowy bieżący katalog roboczy
echo getcwd() . "\n";
?>
Powyższy przykład wyświetli coś podobnego do:
/home/didou /home/didou/cvs
opendir
(PHP 4, PHP 5)
opendir — Otwiera katalog
Opis
$path
[, resource $context
] )Zwraca wskaźnik do otwartego katalogu, który może być następnie wykorzystany przez closedir(), readdir(), and rewinddir() calls.
Parametry
-
path -
Ścieżka do katalogu który ma zostać otwarty
-
context -
Po opis parametru
context, sięgnij do the streams section
Zwracane wartości
W przypadku sukcesu zwraca wskaźnik do katalogu resource, w
przypadku niepowodzenia zwraca
FALSE.
Jeśli path nie jest katalogiem lub jeśli katalog nie
posiada odpowiednich praw dostępu, lub gdy system plików zawiódł
opendir() zwróci FALSE i
wygeneruje błąd PHP
E_WARNING. Można wyłączyć wyświetlanie błędów
opendir() poprzez postawienie znaku
'@' przed
wywołaniem funkcji.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.0.0 |
path wspiera ftp://
URL wrapper.
|
| 4.3.0 |
path może być również
URL-em odnoszącym się do katalogu, jednak tylko file://
URL wrapper jest wspierany w wersji PHP 4.3.
|
Przykłady
Przykład #1 opendir() example
<?php
$dir = "/etc/php5/";
// Otwarcie prawidłowego katalogu i pobranie jego zawartości
if (is_dir($dir)) {
if ($dh = opendir($dir)) {
while (($file = readdir($dh)) !== false) {
echo "filename: $file : filetype: " . filetype($dir . $file) . "\n";
}
closedir($dh);
}
}
?>
Powyższy przykład wyświetli coś podobnego do:
filename: . : filetype: dir filename: .. : filetype: dir filename: apache : filetype: dir filename: cgi : filetype: dir filename: cli : filetype: dir
readdir
(PHP 4, PHP 5)
readdir — Czyta zawartość katalogu
Opis
$uchwyt_katalogu
] )Zwraca nazwę kolejnego pliku z katalogu. Nazwy plików są zwracane w kolejności posortowanej przez system plików.
Parametry
Zwracane wartości
Zwraca nazwę pliku w przypadku powodzenia lub FALSE w przypadku niepowodzenia.
Ta funkcja może
zwrócić Boolean FALSE, ale może też zwrócić wartość innego typu niż Boolean, która oznacza
wartość FALSE, takie jak 0 lub
"". Aby uzyskać więcej informacji proszę zapoznać się z rozdziałem Typy logiczne.
Można używać operatora ===
do testowania zwracanych wartości przez tę
funkcję.
Przykłady
Przykład #1 Lista wszystkich plików w katalogu
Sposób w jaki zwrócona przez readdir() wartość powinna
być sprawdzona, obrazuje poniższy przykład. Należy sprawdzić czy zwrócona
wartość jest równa (jest tego samego typu -- zobacz również
Comparison
Operators) FALSE. W przeciwnym razie plik o nazwie FALSE (jak
również "0")
znajdujący się w czytanym katalogu zatrzymałby pętle.
<?php
// !== nie istniał w wersji wcześniejszej niż 4.0.0-RC2
if ($handle = opendir('/path/to/files')) {
echo "Directory handle: $handle\n";
echo "Files:\n";
/* To jest poprawna metoda */
while (false !== ($file = readdir($handle))) {
echo "$file\n";
}
/* To jest ZŁA metoda */
while ($file = readdir($handle)) {
echo "$file\n";
}
closedir($handle);
}
?>
Przykład #2 Lista wszystkich plików w wskazanym katalogu oprócz . i ..
<?php
if ($handle = opendir('.')) {
while (false !== ($file = readdir($handle))) {
if ($file != "." && $file != "..") {
echo "$file\n";
}
}
closedir($handle);
}
?>
rewinddir
(PHP 4, PHP 5)
rewinddir — Ustawia wskaźnik katalogu na początek
Opis
$uchwyt_katalogu
] )
Ustawia wskaźnik strumienia katalogu
uchwyt_katalogu na początek
katalogu.
scandir
(PHP 5)
scandir — Wypisze wszystkie pliki i katalogi z określonej lokalizacji
Opis
$katalog
[, int $sorting_order = 0
[, resource $context
]] )
Zwraca tablicę z wszystkimi plikami i katalogami znajdującymi się w
katalog.
Parametry
-
katalog -
Katalog, który ma być przeskanowany.
-
sorting_order -
Domyślnie, kolejność w zwróconej tablicy jest alfabetyczna w porządku rosnącym. Jeżeli opcjonalny parametr
sorting_orderjest ustawiony (nie na wartość 0), wówczas kolejność jest alfabetyczna w porządku malejącym. -
context -
Po opis parametru
context, odsyłamy do sekcji strumienii podręcznika PHP.
Zwracane wartości
Zwraca tablicę z nazwami plików w przypadku powodzenia lub FALSE w przypadku
błędu. Jeżeli katalog nie jest w rzeczywistości katalogiem, wtedy
zwracany jest FALSE, oraz generowane jest ostrzeżenie
E_WARNING.
Przykłady
Przykład #1 Przykład użycia scandir()e
<?php
$dir = '/tmp';
$files1 = scandir($dir);
$files2 = scandir($dir, 1);
print_r($files1);
print_r($files2);
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[0] => .
[1] => ..
[2] => bar.php
[3] => foo.txt
[4] => jakiśkatalog
)
Array
(
[0] => jakiśkatalog
[1] => foo.txt
[2] => bar.php
[3] => ..
[4] => .
)
Przykład #2 Alternatywa dla scandir() w PHP 4
<?php
$dir = "/tmp";
$dh = opendir($dir);
while (false !== ($filename = readdir($dh))) {
$files[] = $filename;
}
sort($files);
print_r($files);
rsort($files);
print_r($files);
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[0] => .
[1] => ..
[2] => bar.php
[3] => foo.txt
[4] => jakiśkatalog
)
Array
(
[0] => jakiśkatalog
[1] => foo.txt
[2] => bar.php
[3] => ..
[4] => .
)
Notatki
Jeśli włączona jest dyrektywa konfiguracyjna fopen wrappers, możliwe jest podanie jako nazwy pliku adresu URL. Zobacz opis funkcji fopen() aby dowiedzieć się jak przekazać nazwę pliku, oraz fopen wrappers aby uzyskać listę obsługiwanych protokołów.
Spis treści
- chdir — Zmienia bieżący katalog
- chroot — Zmienia główny katalog
- closedir — Zamyka wskaźnik katalogu
- dir — Return an instance of the Directory class
- getcwd — Wskazuje bieżący katalog roboczy
- opendir — Otwiera katalog
- readdir — Czyta zawartość katalogu
- rewinddir — Ustawia wskaźnik katalogu na początek
- scandir — Wypisze wszystkie pliki i katalogi z określonej lokalizacji
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Directory — The Directory class
- Directory::close — Close directory handle
- Directory::read — Read entry from directory handle
- Directory::rewind — Rewind directory handle
- Funkcje katalogów
- chdir — Zmienia bieżący katalog
- chroot — Zmienia główny katalog
- closedir — Zamyka wskaźnik katalogu
- dir — Return an instance of the Directory class
- getcwd — Wskazuje bieżący katalog roboczy
- opendir — Otwiera katalog
- readdir — Czyta zawartość katalogu
- rewinddir — Ustawia wskaźnik katalogu na początek
- scandir — Wypisze wszystkie pliki i katalogi z określonej lokalizacji
File Information
Wstęp
The functions in this module try to guess the content type and encoding of a file by looking for certain magic byte sequences at specific positions within the file. While this is not a bullet proof approach the heuristics used do a very good job.
Instalacja/Konfiguracja
Spis treści
Wymagania
Before PHP 5.3.0, the magic_open library is needed to build this extension.
Instalacja
This extension is enabled by default as of PHP 5.3.0. Before this time, fileinfo was a PECL extension but is no longer maintained there. However, versions prior to 5.3+ may use the » discontinued PECL extension.
Windows users must include the bundled php_fileinfo.dll DLL file in php.ini to enable this extension.
The libmagic library is bundled with PHP, but includes PHP specific changes. A patch against libmagic named libmagic.patch is maintained and may be found within the PHP fileinfo extensions source.
| PHP Wersja | Updated libmagic Wersja | Notes |
|---|---|---|
| 5.3.2 | 5.03 | |
| 5.3.0 | 5.02 |
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
There is one resource used in Fileinfo extension: a magic database descriptor returned by finfo_open().
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
-
FILEINFO_NONE(integer) - No special handling.
-
FILEINFO_SYMLINK(integer) - Follow symlinks.
-
FILEINFO_MIME_TYPE(integer) - Return the mime type. Available since PHP 5.3.0.
-
FILEINFO_MIME_ENCODING(integer) - Return the mime encoding of the file. Available since PHP 5.3.0.
-
FILEINFO_MIME(integer) - Return the mime type and mime encoding as defined by RFC 2045.
-
FILEINFO_COMPRESS(integer) - Decompress compressed files. Disabled since PHP 5.3.0 due to thread safety issues.
-
FILEINFO_DEVICES(integer) - Look at the contents of blocks or character special devices.
-
FILEINFO_CONTINUE(integer) - Return all matches, not just the first.
-
FILEINFO_PRESERVE_ATIME(integer) - If possible preserve the original access time.
-
FILEINFO_RAW(integer) - Don't translate unprintable characters to a \ooo octal representation.
Fileinfo Funkcje
finfo_buffer
finfo::buffer
(PHP 5 >= 5.3.0, PECL fileinfo >= 0.1.0)
finfo_buffer -- finfo::buffer — Return information about a string buffer
Opis
Styl proceduralny
$finfo
, string $string = NULL
[, int $options = FILEINFO_NONE
[, resource $context = NULL
]] )Styl obiektowy
$string = NULL
[, int $options = FILEINFO_NONE
[, resource $context = NULL
]] )This function is used to get information about binary data in a string.
Parametry
-
finfo -
Fileinfo resource returned by finfo_open().
-
string -
Content of a file to be checked.
-
options -
One or disjunction of more Fileinfo constants.
-
context -
Zwracane wartości
Returns a textual description of the string
argument, or FALSE if an error occurred.
Przykłady
Przykład #1 A finfo_buffer() example
<?php
$finfo = new finfo(FILEINFO_MIME);
echo $finfo->buffer($_POST["script"]) . "\n";
?>
Powyższy przykład wyświetli coś podobnego do:
application/x-sh; charset=us-ascii
finfo_close
(PHP >= 5.3.0, PECL fileinfo >= 0.1.0)
finfo_close — Close fileinfo resource
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
finfo_file
finfo::file
(PHP >= 5.3.0, PECL fileinfo >= 0.1.0)
finfo_file -- finfo::file — Return information about a file
Opis
Styl proceduralny
$finfo
, string $file_name = NULL
[, int $options = FILEINFO_NONE
[, resource $context = NULL
]] )Styl obiektowy
$file_name = NULL
[, int $options = FILEINFO_NONE
[, resource $context = NULL
]] )This function is used to get information about a file.
Parametry
-
finfo -
Fileinfo resource returned by finfo_open().
-
file_name -
Name of a file to be checked.
-
options -
One or disjunction of more Fileinfo constants.
-
context -
For a description of contexts, refer to Stream Funkcje.
Zwracane wartości
Returns a textual description of the contents of the
filename argument, or FALSE if an error occurred.
Przykłady
Przykład #1 A finfo_file() example
<?php
$finfo = finfo_open(FILEINFO_MIME_TYPE); // return mime type ala mimetype extension
foreach (glob("*") as $filename) {
echo finfo_file($finfo, $filename) . "\n";
}
finfo_close($finfo);
?>
Powyższy przykład wyświetli coś podobnego do:
text/html image/gif application/vnd.ms-excel
finfo_open
finfo::__construct
(PHP >= 5.3.0, PECL fileinfo >= 0.1.0)
finfo_open -- finfo::__construct — Create a new fileinfo resource
Opis
Styl proceduralny
$options = FILEINFO_NONE
[, string $magic_file = NULL
]] )Styl obiektowy (constructor):
$options = FILEINFO_NONE
[, string $magic_file = NULL
]] )This function opens a magic database and returns its resource.
Parametry
-
options -
One or disjunction of more Fileinfo constants.
-
magic_file -
Name of a magic database file, usually something like /path/to/magic.mime. If not specified, the MAGIC environment variable is used. If this variable is not set either, /usr/share/misc/magic is used by default. A .mime and/or .mgc suffix is added if needed.
Passing NULL or an empty string will be equivalent to the default value.
Zwracane wartości
(Procedural style only)
Returns a magic database resource on success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 Styl obiektowy
<?php
$finfo = new finfo(FILEINFO_MIME, "/usr/share/misc/magic"); // return mime type ala mimetype extension
/* get mime-type for a specific file */
$filename = "/usr/local/something.txt";
echo $finfo->file($filename);
?>
Przykład #2 Styl proceduralny
<?php
$finfo = finfo_open(FILEINFO_MIME, "/usr/share/misc/magic"); // return mime type ala mimetype extension
if (!$finfo) {
echo "Opening fileinfo database failed";
exit();
}
/* get mime-type for a specific file */
$filename = "/usr/local/something.txt";
echo finfo_file($finfo, $filename);
/* close connection */
finfo_close($finfo);
?>
Powyższy przykład wyświetli:
text/plain; charset=us-ascii
finfo_set_flags
finfo::set_flags
(PHP >= 5.3.0, PECL fileinfo >= 0.1.0)
finfo_set_flags -- finfo::set_flags — Set libmagic configuration options
Opis
Styl proceduralny
$finfo
, int $options
)Styl obiektowy
$options
)This function sets various Fileinfo options. Options can be set also directly in finfo_open() or other Fileinfo functions.
Parametry
-
finfo -
Fileinfo resource returned by finfo_open().
-
options -
One or disjunction of more Fileinfo constants.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
mime_content_type
(PHP 4 >= 4.3.0, PHP 5)
mime_content_type — Detect MIME Content-type for a file (deprecated)
Opis
$filename
)Returns the MIME content type for a file as determined by using information from the magic.mime file.
Parametry
-
filename -
Path to the tested file.
Zwracane wartości
Returns the content type in MIME format, like text/plain or application/octet-stream.
Notatki
This function has been deprecated as the PECL extension Fileinfo provides the same functionality (and more) in a much cleaner way.
Przykłady
Przykład #1 mime_content_type() Example
<?php
echo mime_content_type('php.gif') . "\n";
echo mime_content_type('test.php');
?>
Powyższy przykład wyświetli:
image/gif text/plain
Spis treści
- finfo_buffer — Return information about a string buffer
- finfo_close — Close fileinfo resource
- finfo_file — Return information about a file
- finfo_open — Create a new fileinfo resource
- finfo_set_flags — Set libmagic configuration options
- mime_content_type — Detect MIME Content-type for a file (deprecated)
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Fileinfo Funkcje
- finfo_buffer — Return information about a string buffer
- finfo_close — Close fileinfo resource
- finfo_file — Return information about a file
- finfo_open — Create a new fileinfo resource
- finfo_set_flags — Set libmagic configuration options
- mime_content_type — Detect MIME Content-type for a file (deprecated)
Filesystem
Wstęp
No external libraries are needed to build this extension, but if you want PHP to support LFS (large files) on Linux, then you need to have a recent glibc and you need compile PHP with the following compiler flags: -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64.
Instalacja/Konfiguracja
Spis treści
Wymagania
Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.
Instalacja
By używać tych funkcji, nie trzeba niczego instalować. Są one częścią jądra PHP.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| allow_url_fopen | "1" | PHP_INI_SYSTEM | PHP_INI_ALL in PHP <= 4.3.4. Available since PHP 4.0.4. |
| allow_url_include | "0" | PHP_INI_ALL | PHP_INI_SYSTEM in PHP 5. Available since PHP 5.2.0. |
| user_agent | NULL | PHP_INI_ALL | Available since PHP 4.3.0. |
| default_socket_timeout | "60" | PHP_INI_ALL | Available since PHP 4.3.0. |
| from | "" | PHP_INI_ALL | |
| auto_detect_line_endings | "0" | PHP_INI_ALL | Available since PHP 4.3.0. |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
allow_url_fopenboolean -
This option enables the URL-aware fopen wrappers that enable accessing URL object like files. Default wrappers are provided for the access of remote files using the ftp or http protocol, some extensions like zlib may register additional wrappers.
Informacja:
This option was introduced immediately after the release of version 4.0.3. For versions up to and including 4.0.3 you can only disable this feature at compile time by using the configuration switch
--disable-url-fopen-wrapper.OstrzeżenieOn Windows versions prior to PHP 4.3.0, the following functions do not support remote file accessing: include(), include_once(), require(), require_once() and the imagecreatefromXXX functions in the GD and Image Funkcje extension.
-
allow_url_includeboolean -
This option allows the use of URL-aware fopen wrappers with the following functions: include(), include_once(), require(), require_once().
Informacja:
This setting requires allow_url_fopen to be on.
-
user_agentstring -
Define the user agent for PHP to send.
-
default_socket_timeoutinteger -
Default timeout (in seconds) for socket based streams.
Informacja: This configuration option was introduced in PHP 4.3.0
-
fromstring -
The email address to be used on unauthenticated FTP connections and as the value of From header for HTTP connections, when using the ftp and http wrappers, respectively.
-
auto_detect_line_endingsboolean -
When turned on, PHP will examine the data read by fgets() and file() to see if it is using Unix, MS-Dos or Macintosh line-ending conventions.
This enables PHP to interoperate with Macintosh systems, but defaults to Off, as there is a very small performance penalty when detecting the EOL conventions for the first line, and also because people using carriage-returns as item separators under Unix systems would experience non-backwards-compatible behaviour.
Informacja: This configuration option was introduced in PHP 4.3.0
Typy zasobów
The file system uses streams as their resource type. Streams are documented in its own reference chapter, Streams.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
-
GLOB_BRACE(integer) -
GLOB_ONLYDIR(integer) -
GLOB_MARK(integer) -
GLOB_NOSORT(integer) -
GLOB_NOCHECK(integer) -
GLOB_NOESCAPE(integer) -
GLOB_AVAILABLE_FLAGS(integer) -
PATHINFO_DIRNAME(integer) -
PATHINFO_BASENAME(integer) -
PATHINFO_EXTENSION(integer) -
PATHINFO_FILENAME(integer) - Od PHP 5.2.0.
-
FILE_USE_INCLUDE_PATH(integer) -
Poszukuje
nazwy_plikuw include_path (od PHP 5). -
FILE_NO_DEFAULT_CONTEXT(integer) -
FILE_APPEND(integer) - Dodaje treść do istniejącego pliku.
-
FILE_IGNORE_NEW_LINES(integer) - Usuwa znaki końca lini (EOL) (od PHP 5).
-
FILE_SKIP_EMPTY_LINES(integer) - Pomija puste linie (od PHP 5).
-
FILE_BINARY(integer) -
Tryb binarny (od PHP 5.2.7).
Informacja:
Ta stała niczego nie zmienia. Jest ona dostępna tylko w celu zgodności z poprzednimi wersjami.
-
FILE_TEXT(integer) -
Tryb tekstowy (od PHP 5.2.7).
Informacja:
Ta stała niczego nie zmienia. Jest ona dostępna tylko w celu zgodności z poprzednimi wersjami.
-
INI_SCANNER_NORMAL(integer) - Standardowy tryb skanowania INI (od PHP 5.3).
-
INI_SCANNER_RAW(integer) - Surowy tryb skanowania INI (od PHP 5.3).
-
FNM_NOESCAPE(integer) - Wyłączenie sekwencji unikowych odwrotnym ukośnikiem.
-
FNM_PATHNAME(integer) - Ukośnik w łańcuchu znaków jedynie pasuje do ukośnika z podanego wzorca.
-
FNM_PERIOD(integer) - Poprzedzająca kropka w łańcuchu znaków musi dokładnie pasować do kropki w podanym wzorcu.
-
FNM_CASEFOLD(integer) - Dopasowanie bez rozróżniania znaków. Część rozszeżenia GNU.
Funkcje Systemu plików
Zobacz też:
Związane z tym działem funkcje, znajdziesz w rozdziale Katalog i Wykonywanie programów.
Listę wraz z opisem różnych wrapperów URL, które mogą zostać użyte jako zdalne pliki, znajdziesz tu Supported Protocols and Wrappers.
basename
(PHP 4, PHP 5)
basename — Zwraca nazwę pliku, będącego składową ścieżki
Opis
$ścieżka
[, string $przyrostek
] )Z podanego łańcucha zawierającego ścieżkę do pliku, funkcja zwraca samą nazwę pliku.
Parametry
-
ścieżka -
Ścieżka
W Windows jako separator katalogów używany jest znak slash (/) i backslash (\). W innych środowiskach jest to slash (/).
-
przyrostek -
Jeśli plik kończy się
przyrostkiemto także zostanie on obcięty.
Zwracane wartości
Zwraca nazwę pliku z podanej ścieżki.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.1.0 |
Został dodany Parametr przyrostek
|
Przykłady
Przykład #1 Przykład basename()
<?php
echo "1) ".basename("/etc/sudoers.d", ".d").PHP_EOL;
echo "2) ".basename("/etc/passwd").PHP_EOL;
echo "3) ".basename("/etc/").PHP_EOL;
echo "4) ".basename(".").PHP_EOL;
echo "5) ".basename("/");
?>
Powyższy przykład wyświetli:
1) sudoers 2) passwd 3) etc 4) . 5)
Notatki
Informacja:
basename() działa naiwnie na wejściowym łańcuchu znaków i nie jest świadoma bieżącego systemu plików lub składników ścieżki takich jak "..".
Informacja:
basename() jest świadoma locale, aby widzieć prawidłowe basename ze ścieżek z wielobajtowymi znakami, musi zostać ustawione pasujące locale za pomocą funkcji setlocale().
Zobacz też:
- dirname() - Zwraca nazwę katalogu, będącego składową ścieżki
- pathinfo() - Zwraca informacje o ścieżce do pliku
chgrp
(PHP 4, PHP 5)
chgrp — Zmienia grupę pliku
Opis
Próbuje zmienić grupę pliku podanego w parametrze nazwa_pliku
na wybraną parametrem grupa
Tylko super użytkownik może zmienić dowolnie grupę pliku; inni użytkownicy mogą zmienić grupę pliku na dowolną grupę, której członkiem jest ten użytkownik.
Parametry
-
nazwa_pliku -
Ścieżka do pliku.
-
grupa -
Numer lub nazwa grupy.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Zmiana grupy pliku
<?php
$nazwa_pliku = 'wspoldzielony_plik.txt';
$format = "%s's Identyfikator grupy @ %s: %d\n";
printf($format, $nazwa_pliku, date('r'), filegroup($nazwa_pliku));
chgrp($filename, 8);
clearstatcache(); // nie buforuj wyników filegroup()
printf($format, $nazwa_pliku, date('r'), filegroup($nazwa_pliku));
?>
Notatki
Informacja: Ta funkcja nie będzie działać na zdalnych plikach, ponieważ przetwarzany plik musi być dostępny w systemie plików serwera.
Informacja: Gdy włączony jest tryb bezpieczny, PHP sprawdza, czy pliki lub katalogi, na których zostaną wykonane operacje mają takie same UID (owner) jak skrypt, który jest aktualnie wykonywany.
chmod
(PHP 4, PHP 5)
chmod — Zmienia prawa dostępu do pliku
Opis
$nazwa_pliku
, int $prawa
)
Próbuje dokonać zmiany praw pliku na podane w
prawa.
Parametry
-
nazwa_pliku -
Ścieżka do pliku.
-
prawa -
Pamiętaj, że parametr
prawanie jest automatycznie zastępowany wartością oktalną (ósemkową), więc łańcuchy (takie jak "g+w") nie będą poprawnie interpretowane. Aby, zapewnić poprawność operacji musisz parametrprawapoprzedzić prefixem zero (0):<?php
chmod("/somedir/somefile", 755); // dziesiętnie; prawdopodobnie nieprawidłowo
chmod("/somedir/somefile", "u+rwx,go+rx"); // łańcuch; nieprawidłowo
chmod("/somedir/somefile", 0755); // ósemkowo; poprawna wartość dla praw
?>Parametr
prawazawiera trzy cyfry w systemie ósemkowym określające prawa dostępu dla właściciela, grupy do której on należy oraz wszystkich innych. Jedna cyfra może zostać obliczona poprzez dodanie do siebie potrzebnych uprawnień. Cyfra 1 oznacza nadanie praw do wykonania, cyfra 2 oznacza, że plik będzie zapisywalny, cyfra 4 oznacza, że plik będzie można odczytać. Dodając te cyfry określamy potrzebne uprawnienia. Więcej o prawach w systemie Unix można przeczytać w 'man 1 chmod' i 'man 2 chmod'.<?php
// Odczyt i zapis dla właściciela, żadnych praw dla innych
chmod("/katalog/plik", 0600);
// Odczyt i zapis dla właściciela, odczyt dla wszystkich
chmod("/katalog/plik", 0644);
// Wszystkie prawa dla właściciela, odczyt i wykonanie dla innych
chmod("/katalog/plik", 0755);
// Wszystkie prawa dla właściciela, odczyt i wykonanie dla grupy właściciela
chmod("/katalog/plik", 0750);
?>
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Notatki
Informacja:
Bieżący użytkownik to użytkownik pod którym działa PHP. Prawdpodobnie nie jest to ten sam użytkownik, którego używasz normalnie przy dostępie do shell'a lub FTP. W większości systemów, prawa mogą być zmienione jedynie przez właściciela pliku.
Informacja: Ta funkcja nie będzie działać na zdalnych plikach, ponieważ przetwarzany plik musi być dostępny w systemie plików serwera.
Informacja:
Kiedy włączony jest tryb bezpieczny, PHP sprawdza czy pliki lub katalogi na których mają zostać wykonane operacje posiadają taki sam UID (właściciela) jak skrypt, który jest wykonywany. W dodatku, nie możesz ustawić SUI, SGID i bitów lepkości (sticky bits).
Zobacz też:
- chown() - Zmienia właściciela pliku
- chgrp() - Zmienia grupę pliku
- fileperms() - Pobiera prawa dostępu pliku
- stat() - Gives information about a file
chown
(PHP 4, PHP 5)
chown — Zmienia właściciela pliku
Opis
Próbuje dokonać zmiany właściciela pliku nazwa_pliku na użytkownika
podanego w parametrze użytkownik.
Tylko superużytkownik może zmienić właściciela pliku.
Parametry
-
nazwa_pliku -
Ścieżka do pliku.
-
użytkownik -
Numer ID lub nazwa użytkownika.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Proste użycie chown()
<?php
// Nazwa pliku i użytkownika
$file_name= "foo.php";
$path = "/home/sites/php.net/public_html/sandbox/" . $file_name ;
$user_name = "root";
// Ustaw właściciela pliku
chown($path, $user_name);
// Check the result
$stat = stat($path);
print_r(posix_getpwuid($stat['uid']));
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[name] => root
[passwd] => x
[uid] => 0
[gid] => 0
[gecos] => root
[dir] => /root
[shell] => /bin/bash
)
Notatki
Informacja: Ta funkcja nie będzie działać na zdalnych plikach, ponieważ przetwarzany plik musi być dostępny w systemie plików serwera.
Informacja: Gdy włączony jest tryb bezpieczny, PHP sprawdza, czy pliki lub katalogi, na których zostaną wykonane operacje mają takie same UID (owner) jak skrypt, który jest aktualnie wykonywany.
clearstatcache
(PHP 4, PHP 5)
clearstatcache — Czyści bufor statusu pliku
Opis
$clear_realpath_cache = false
[, string $nazwa_pliku
]] )Kiedy używasz stat(), lstat() lub dowolnej z funkcji wymienionej niżej, PHP buforuje informacje, zwrócone przez te funkcje w celu zapewnienia większej wydajności. Jednakże, w kilku przypadkach, możesz chcieć wyczyścić zbuforowane informacje. W przypadku, gdy ten sam plik jest sprawdzany wiele razy w tym samym skrypcie i istnieje obawa, że plik ten zostanie zmieniony lub usunięty podczas pracy skryptu, możesz wywołać czyszczenie bufora stanu. W takim przypadku, możesz użyć funkcji clearstatcache() do wyczyszczenia informacji o pliku zbuforowanej przez PHP.
Weź pod uwagę, że PHP nie buforuje informacji o nie istniejących plikach.
Jeśli wywołasz file_exists() na pliku, który nie istnieje
zostanie zwrócone FALSE dopóki nie stworzysz tego pliku. Jeśli go utworzysz
funkcja zwróci TRUE nawet jeśli go później skasujesz.
Jednakże unlink() czyści automatycznie bufor.
Informacja:
Ta funkcja buforuje informacje o podanych nazwach plików, więc potrzebujesz wywoływać clearstatcache() jeśli wykonujesz wiele operacji na tym samym pliku i potrzebujesz, aby informacje o tym pliku nie były buforowane.
Dotyczy funkcji stat(), lstat(), file_exists(), is_writable(), is_readable(), is_executable(), is_file(), is_dir(), is_link(), filectime(), fileatime(), filemtime(), fileinode(), filegroup(), fileowner(), filesize(), filetype() i fileperms().
Parametry
-
clear_realpath_cache -
Czy czyścić bufor o prawdziej ścieżce, czy nie.
-
nazwa_pliku -
Czyści bufor o prawdziwej ścieżce dla podanego pliku; tylko jeśli
clear_realpath_cachejestTRUE.
Zwracane wartości
Nie jest zwracana żadna wartość.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.0 |
Dodano opcjonalne parametry clear_realpath_cache
i filename.
|
Przykłady
Przykład #1 Przykład clearstatcache()
<?php
$file = 'output_log.txt';
function get_owner($file)
{
$stat = stat($file);
$user = posix_getpwuid($stat['uid']);
return $user['name'];
}
$format = "UID @ %s: %s\n";
printf($format, date('r'), get_owner($file));
chown($file, 'ross');
printf($format, date('r'), get_owner($file));
clearstatcache();
printf($format, date('r'), get_owner($file));
?>
Powyższy przykład wyświetli coś podobnego do:
UID @ Sun, 12 Oct 2008 20:48:28 +0100: root UID @ Sun, 12 Oct 2008 20:48:28 +0100: root UID @ Sun, 12 Oct 2008 20:48:28 +0100: ross
copy
(PHP 4, PHP 5)
copy — Kopiuje plik
Opis
$źródło
, string $przeznaczenie
[, resource $kontekst
] )
Kopiuje plik z źródło do
przeznaczenie.
Jeśli chcesz przenieść plik, użyj funkcji rename().
Parametry
-
źródło -
Ścieżka do pliku źródłowego.
-
przeznaczenie -
Ścieżka docelowa. Jeśli
przeznaczeniejest URLem, operacja kopiowania może się niepowieść, jeśli wrapper nie obsługuje nadpisywania istniejących plików.OstrzeżenieJeśli, docelowy plik istnieje to zostanie nadpisany.
-
kontekst -
Prawidłowo utworzony zasób kontekstowy za pomocą stream_context_create().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.0 | Dodano obsługę kontekstu. |
| 4.3.0 |
Zarówno źródło i przeznaczenie
mogą być URLami jeśli "wrappery fopen" zostały włączone.
Zobacz fopen() w celu poznania więcej szczegółów.
|
Przykłady
Przykład #1 copy() przykład
<?php
$file = 'example.txt';
$newfile = 'example.txt.bak';
if (!copy($file, $newfile)) {
echo "kopiowanie pliku $file, nie powiodło się\n";
}
?>
Zobacz też:
- move_uploaded_file() - Przenieś uploadowany plik do innej lokalizacji
- rename() - Renames a file or directory
- Rozdział podręcznika dotyczącyobsługi wgrywania plików
Opis
To jest ślepy wpis aby zadowolić ludzi którzy szukają unlink() lub unset() w nie właściwym miejscu.
Zwracane wartości
Nie jest zwracana żadna wartość.
dirname
(PHP 4, PHP 5)
dirname — Zwraca nazwę katalogu, będącego składową ścieżki
Opis
$ścieżka
)Z podanego łańcucha zawierającego ścieżkę do pliku, funkcja ta zwróci nazwę nadrzędnego katalogu.
Parametry
-
path -
A path.
W Windows jako separator katalogu używany jest znak slash (/) i backslash (\). W innych środowiskach jest to slash (/).
Zwracane wartości
Zwraca nazwę katalogu. Jeśli, w ścieżce nie znajdują się
ukośniki to zwracana jest kropka ('.'), oznaczająca
bieżący katalog. W innym przypadku, zwracany jest łańcuch znaków
ścieżka z usuniętymi wszystkimi koncowymi
/komponentami.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.0.0 | dirname() od teraz jest binarnie bezpieczna |
| 4.0.3 | dirname() poprawiono kompatybilność z POSIX. |
Przykłady
Przykład #1 Przykład dirname()
<?php
echo "1) " . dirname("/etc/passwd") . PHP_EOL; // 1) /etc
echo "2) " . dirname("/etc/") . PHP_EOL; // 2) / (lub \ pod Windows)
echo "3) " . dirname("."); // 3) .
?>
Notatki
Informacja:
dirname() działa naiwnie na wejściowym łańcuchu znaków i nie jest świadoma bieżącego systemu plików lub składników ścieżki takich jak "..".
Informacja:
dirname() jest świadoma locale, aby widzieć prawidłową nazwę katalogu z ścieżek z wielobajtowymi znakami, musi zostać ustawione pasujące locale za pomocą funkcji setlocale().
Informacja:
Od PHP 4.3.0, często otrzymasz ukośnik lub kropkę z dirname() w sytuacjach gdzie starsza funkcjonalność mogła dać pusty łańcuch znaków.
Sprawdź poniższy przykład zmian:
<?php
//przed PHP 4.3.0
dirname('c:/'); // zwraca '.'
//po PHP 4.3.0
dirname('c:/x'); // zwraca 'c:\'
dirname('c:/Temp/x'); // zwraca 'c:/Temp'
dirname('/x'); // zwraca '\'
?>
Zobacz też:
- basename() - Zwraca nazwę pliku, będącego składową ścieżki
- pathinfo() - Zwraca informacje o ścieżce do pliku
- realpath() - Returns canonicalized absolute pathname
disk_free_space
(PHP 4 >= 4.1.0, PHP 5)
disk_free_space — Zwraca ilość wolnego miejsca w systemie plików lub partycji dysku
Opis
$katalog
)Podając łańcuch zawierający katalog, funkcja zwróci liczbę dostępnych bajtów w odpowiadającym mu systemie plików lub partycji dysku.
Parametry
-
katalog -
Katalog w systemie plików lub partycji dysku.
Informacja:
Po podaniu nazwy pliku zamiast katalogu zachowanie funkcji jest nieprzewidywalne i może się różnić w zależności od systemu operacyjnego i wersji PHP.
Zwracane wartości
Zwraca liczbę dostępnych bajtów jako liczbę zmiennoprzecinkową.
lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 Przykład disk_free_space()
<?php
// $df zawiera liczbę dostępnych bajtów w "/"
$df = disk_free_space("/");
// Pod Windows:
$df_c = disk_free_space("C:");
$df_d = disk_free_space("D:");
?>
Notatki
Informacja: Ta funkcja nie będzie działać na zdalnych plikach, ponieważ przetwarzany plik musi być dostępny w systemie plików serwera.
disk_total_space
(PHP 4 >= 4.1.0, PHP 5)
disk_total_space — Zwraca całkowity rozmiar systemu plików lub partycji dysku
Opis
$katalog
)Podając łańcuch zawierający katalog, funkcja ta zwróci całkowitą liczbę bajtów w odpowiadającym mu systemie plików lub partycji dysku.
Parametry
-
katalog -
Katalog w systemie plików lub partycji dysku.
Zwracane wartości
Zwraca całkowitą liczbę bajtów jako liczbę zmiennoprzecinkową
lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 Przykład disk_total_space()
<?php
// $ds zawiera całkowita liczbę dostepnych bajtów on "/"
$ds = disk_total_space("/");
// Pod Windows:
$ds = disk_total_space("C:");
$ds = disk_total_space("D:");
?>
Notatki
Informacja: Ta funkcja nie będzie działać na zdalnych plikach, ponieważ przetwarzany plik musi być dostępny w systemie plików serwera.
Opis
Ta funkcja jest aliasem dla: disk_free_space().
fclose
(PHP 4, PHP 5)
fclose — Zamyka otwarty wskaźnik pliku
Opis
$uchwyt
)
Zamyka wskaźnik pliku uchwyt.
Parametry
-
uchwyt -
Wskaźnik pliku musi byc prawidłowy i musi wskazywać na plik poprawnie otworzony przez fopen() lub fsockopen().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Prosty przykład fclose()
<?php
$uchwyt = fopen('jakis_plik.txt', 'r');
fclose($uchwyt);
?>
Zobacz też:
- fopen() - Otwiera plik lub URL
- fsockopen() - Open Internet or Unix domain socket connection
feof
(PHP 4, PHP 5)
feof — Sprawdza czy wskaźnik pliku jest na końcu pliku (EOF)
Opis
$uchwyt
)Sprawdza czy wskaźnik pliku jest na końcu pliku (EOF).
Parametry
-
uchwyt -
Wskaźnik na plik musi być poprawny i musi wskazywać na plik pomyślnie otwarty przez funkcję fopen() lub fsockopen() (a jednocześnie nie zamknięty jeszcze przez fclose()).
Zwracane wartości
Zwraca TRUE jeśli wskaźnik pliku jest na EOF lub gdy zdarzy się błąd
(także timeout połączenia socket'owego); w przeciwnym wypadku zwraca FALSE.
Notatki
Jeśli połączenie otworzone za pomocą fsockopen() nie zostanie zamknięte przez serwer, feof() zawiesi się. Aby to obejść zobacz poniższy przykład:
Przykład #1 Obsługa limitu czasu w feof()
<?php
function safe_feof($fp, &$start = NULL) {
$start = microtime(true);
return feof($fp);
}
/* Zakładając, że $fp jest wcześniej otworzone przez fsockopen() */
$start = NULL;
$timeout = ini_get('default_socket_timeout');
while(!safe_feof($fp, $start) && (microtime(true) - $start) < $timeout)
{
/* Uchwyt */
}
?>
Jeśli podano nieprawidłowy wskaźnik pliku to możesz uzyskać nieskończoną pętle,
ponieważ feof() w przypadku błędu zwraca TRUE..
Przykład #2 feof() przykład z nieprawidłowym wskaźnikiem pliku
<?php
// jeśli plik nie może zostać odczytany lub nie istnieje funkcja fopen zwróci FALSE
$file = @fopen("nie_isniejacy_plik", "r");
// FALSE z fopen spowoduje ostrzeżenie oraz wystąpi tu nieskończona pętla
while (!feof($file)) {
}
fclose($file);
?>
fflush
(PHP 4 >= 4.0.1, PHP 5)
fflush — Przekierowuje wyjście do pliku
Opis
$uchwyt
)
Ta funkcja wymusza zapis całego zbuforowanego wyjścia do zasobu wskazywanego
przez plik uchwyt.
Parametry
-
uchwyt -
Wskaźnik na plik musi być poprawny i musi wskazywać na plik pomyślnie otwarty przez funkcję fopen() lub fsockopen() (a jednocześnie nie zamknięty jeszcze przez fclose()).
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Przykład zapisu do pliku używając fflush()
<?php
$nazwa_pliku = 'bar.txt';
$plik = fopen($nazwa_pliku, 'r+');
rewind($plik);
fwrite($plik, 'Foo');
fflush($plik);
ftruncate($plik, ftell($plik));
fclose($plik);
?>
Zobacz też:
- clearstatcache() - Czyści bufor statusu pliku
- fwrite() - Zapis pliku binarnie bezpieczny
fgetc
(PHP 4, PHP 5)
fgetc — Pobiera znak ze wskaźnika pliku
Opis
$uchwyt
)Pobiera znak ze wskaźnika pliku.
Parametry
-
uchwyt -
Wskaźnik na plik musi być poprawny i musi wskazywać na plik pomyślnie otwarty przez funkcję fopen() lub fsockopen() (a jednocześnie nie zamknięty jeszcze przez fclose()).
Zwracane wartości
Zwraca łańcuch znaków zawierający pojedynczy znak odczytany z pliku wskazanego
przez uchwyt. Zwraca FALSE lub EOF.
Ta funkcja może
zwrócić Boolean FALSE, ale może też zwrócić wartość innego typu niż Boolean, która oznacza
wartość FALSE, takie jak 0 lub
"". Aby uzyskać więcej informacji proszę zapoznać się z rozdziałem Typy logiczne.
Można używać operatora ===
do testowania zwracanych wartości przez tę
funkcję.
Przykłady
Przykład #1 Przykład fgetc()
<?php
$fp = fopen('plik.txt', 'r');
if (!$fp) {
echo 'Nie można otworzyć plik.txt';
}
while (false !== ($char = fgetc($fp))) {
echo "$char\n";
}
?>
Notatki
Informacja: Ta funkcja jest bezpieczna dla danych binarnych.
Zobacz też:
- fread() - Odczyt pliku binarnie bezpieczy
- fopen() - Otwiera plik lub URL
- popen() - Otwiera wskaźnik pliku do procesu
- fsockopen() - Open Internet or Unix domain socket connection
- fgets() - Pobiera linię ze wskaźnika pliku
fgetcsv
(PHP 4, PHP 5)
fgetcsv — Pobiera linię ze wskanika pliku i przetwarza na pola CSV
Opis
$uchwyt
[, int $długość = 0
[, string $delimiter = ','
[, string $ogranicznik = '"'
[, string $ucieczka = '\\'
]]]] )Działa podobnie do fgets() tylko, że fgetcsv() przetwarza odczytaną linię na pola w formacie CSV i zwraca tablicę zawierającą odczytane pola.
Parametry
-
uchwyt -
Ważny uchwyt pliku, poprawnie otwartego za pomocą fopen(), popen() lub fsockopen().
-
długość -
Musi być większy niż najdłuższa linia (w znakach), która znajduje się w pliku CSV (wliczając znaki końca lini). Stał się opcjonalny w PHP 5. Opuszczenie tego parametru (lub ustawienie go na 0 w PHP 5.0.4 lub późniejszym) spowoduje, że maksymalna długość lini nie jest limitowana, co jest nieznacznie wolniejsze.
-
delimiter -
Ustawia delimeter (tylko jeden znak) pól.
-
ogranicznik -
Ustawia znak ograniczający pole.
-
ucieczka -
Ustawia znak ucieczki (tylko jeden znak). Domyślnie jest to odwrotny ukośnik.
Zwracane wartości
Zwraca indeksowaną tablicę zawierającą odczytane pola.
Informacja:
Pusta linia w pliku CSV zostanie zwrócona jako tablica składająca się z pojedynczego pola null i nie zostanie potraktowana jako błąd.
Informacja: Jeśli PHP niewłaściwie rozpoznaje znaki końca linii podczas odczytu plików stworzonych lub znajdujących się na komputerach Macintosh, problem może rozwiązać włączenie dyrektywy konfiguracyjnej auto_detect_line_endings .
fgetcsv() zwraca NULL jeśli dostarczono
niewłaściwy uchwyt lub FALSE w przypadku innego błędu,
włączając w to koniec pliku.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.0 |
Dodano parametr ucieczka
|
| 4.3.5 | fgetcsv() stał się bezpiecznym dla danych binarnych |
| 4.3.0 |
Dodano parametr ogranicznik
|
Przykłady
Przykład #1 fgetcsv() przykład - Odczyt i wyświetlenie całej zawartości pliku CSV
<?php
$row = 1;
if (($uchwyt = fopen ("test.csv","r")) !== FALSE) {
while (($data = fgetcsv($uchwyt, 1000, ",")) !== FALSE) {
$num = count($data);
echo "<p> $num pól w lini $row: <br /></p>\n";
$row++;
for ($c=0; $c < $num; $c++) {
echo $data[$c] . "<br />\n";
}
}
fclose ($uchwyt);
}
?>
Notatki
Informacja:
Ustawienia lokale są brane pod uwagę przez tę funkcję. Jeśli LANG jest ustawione na np. en_US.UTF-8, pliki z jedno bajtowym kodowaniem zostaną nieprawidłowo odczytane przez funkcję.
Zobacz też:
- str_getcsv() - Parse a CSV string into an array
- explode() - Split a string by string
- file() - Czyta całą zawartość pliku do tablicy
- pack() - Pack data into binary string
- fputcsv() - Format line as CSV and write to file pointer
fgets
(PHP 4, PHP 5)
fgets — Pobiera linię ze wskaźnika pliku
Opis
$uchwyt
[, int $długość
] )Pobiera linię ze wskaźnika pliku.
Parametry
-
uchwyt -
Wskaźnik na plik musi być poprawny i musi wskazywać na plik pomyślnie otwarty przez funkcję fopen() lub fsockopen() (a jednocześnie nie zamknięty jeszcze przez fclose()).
-
długość -
Kończy czytanie gdy przeczytano
długość- 1 bajtów, na znaku nowej linii (który jest dołączony do zwracanej wartości), lub na końcu pliku (EOF) (cokolwiek wystąpi wcześniej). Jeśli, nie określono długości, czytanie ze strumienia będzie kontynuowane do czasu osiągnięcia końca linii.Informacja:
Do wersji PHP 4.3.0, pominięcie powodowało ustawienie długości na 1024. Jeśli większość linii w pliku jest dłuższa od 8KB, dużo efektywniejsze jest podanie maksymalnej długości linii.
Zwracane wartości
Zwraca łańcuch znaków o długości - 1 bajtów odczytanych ze
wskaźnika pliku wskazanego przez uchwyt. Jeśli nie ma więcej danych
do przeczytania ze wskaźnika pliku to zwraca FALSE
W przypadku błędu zwraca FALSE.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.3.0 | fgets() stał się bezpieczny dla danych binarnych |
| 4.2.0 |
Parametr długość stał się opcjonalny.
|
Przykłady
Przykład #1 Oczyt pliku linia po linii
<?php
$uchwyt = @fopen("/tmp/plik_wejsciowy.txt", "r");
if ($uchwyt) {
while (($bufor = fgets($uchwyt, 4096)) !== false) {
echo $bufor;
}
if (!feof($uchwyt)) {
echo "Błąd: niespodziewany błąd fgets()\n";
}
fclose($uchwyt);
}
?>
Notatki
Informacja: Jeśli PHP niewłaściwie rozpoznaje znaki końca linii podczas odczytu plików stworzonych lub znajdujących się na komputerach Macintosh, problem może rozwiązać włączenie dyrektywy konfiguracyjnej auto_detect_line_endings .
Informacja:
Osoby przyzwyczajone do semantyki 'C' powinny zauważyć różnicę w sposobie zwracania EOF przez fgets().
Zobacz też:
- fgetss() - Pobiera linię ze wskaźnika pliku i usuwa znaczniki HTML
- fread() - Odczyt pliku binarnie bezpieczy
- fgetc() - Pobiera znak ze wskaźnika pliku
- stream_get_line() - Gets line from stream resource up to a given delimiter
- fopen() - Otwiera plik lub URL
- popen() - Otwiera wskaźnik pliku do procesu
- fsockopen() - Open Internet or Unix domain socket connection
- stream_set_timeout() - Set timeout period on a stream
fgetss
(PHP 4, PHP 5)
fgetss — Pobiera linię ze wskaźnika pliku i usuwa znaczniki HTML
Opis
$uchwyt
[, int $długość
[, string $dozwolone_tagi
]] )Działa identycznie jak fgets(), oprócz tego że fgetss() próbuje usunąć wszystkie bajty NUL, znaczniki HTML i PHP z tekstu, który przeczyta.
Parametry
-
uchwyt -
Wskaźnik na plik musi być poprawny i musi wskazywać na plik pomyślnie otwarty przez funkcję fopen() lub fsockopen() (a jednocześnie nie zamknięty jeszcze przez fclose()).
-
długość -
Długość danych do pobrania.
-
dozwolone_tagi -
Możesz użyć opcjonalnego trzeciego parametru do określenia które znaczniki nie powinny być usunięte.
Zwracane wartości
Zwraca łańcuch znaków o długości - 1 bajtów odczytanych ze
wskaźnika pliku wskazanego przez uchwyt, pozbawionego całego
kodu HTML i PHP.
W przypadku błędu zwraca FALSE.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.0.0 |
Parametr długość jest opcjonalny.
|
Przykład #1 Czytanie pliku PHP linia po linii
<?php
$str = <<<EOD
<html><body>
<p>Witaj! Dziś jest <?php echo(date('jS')); ?> z <?= date('F'); ?>.</p>
</body></html>
Tekst po za blokiem HTML.
EOD;
file_put_contents('przyklad.php', $str);
$uchwyt = @fopen("przyklad.php", "r");
if ($uchwyt) {
while (!feof($uchwyt)) {
$bufor = fgetss($uchwyt, 4096);
echo $bufor;
}
fclose($uchwyt);
}
?>
Powyższy przykład wyświetli coś podobnego do:
Witaj! Dziś jest z . Tekst po za blokiem HTML.
Notatki
Informacja: Jeśli PHP niewłaściwie rozpoznaje znaki końca linii podczas odczytu plików stworzonych lub znajdujących się na komputerach Macintosh, problem może rozwiązać włączenie dyrektywy konfiguracyjnej auto_detect_line_endings .
Zobacz też:
- fgets() - Pobiera linię ze wskaźnika pliku
- fopen() - Otwiera plik lub URL
- popen() - Otwiera wskaźnik pliku do procesu
- fsockopen() - Open Internet or Unix domain socket connection
- strip_tags() - Strip HTML and PHP tags from a string
file_exists
(PHP 4, PHP 5)
file_exists — Sprawdza czy plik lub katalog istnieje
Opis
$nazwa_pliku
)Sprawdza czy plik lub katalog istnieje.
Parametry
-
nazwa_pliku -
Ścieżka do pliku lub katalogu.
Pod Windows, użyj //nazwa_komputera/udział/nazwa_pliku lub \\nazwa_komputera\udział\nazwa_pliku aby sprawdzić pliki dla sieciowych udziałów.
Zwracane wartości
Zwraca TRUE jeśli plik lub katalog określony w
nazwa_pliku istnieje; FALSE w przeciwnym wypadku.
Informacja:
Ta funkcja zwróci
FALSEdla linków symbolicznych wskazujących na nie istniejące pliki.
Funkcja zwraca FALSE dla plików niedostępnych z powodu restrykcji trybu bezpiecznego. Jednak te pliki
ciągle mogą być inkludowane jeśli
znajdują się w safe_mode_include_dir.
Informacja:
Sprawdzanie dokonywane jest na prawdziwych UID/GID, a nie efektywnych.
Informacja: Because PHP's integer type is signed and many platforms use 32bit integers, some filesystem functions may return unexpected results for files which are larger than 2GB.
Przykłady
Przykład #1 Sprawdzanie czy plik istnieje
<?php
$nazwa_pliku = '/sciezka/do/pliku.txt';
if (file_exists($nazwa_pliku)) {
echo "Plik $nazwa_pliku istnieje";
} else {
echo "Plik $nazwa_pliku nie istnieje";
}
?>
Błędy/Wyjątki
W przypadku niepowodzenia jest emitowany E_WARNING.
Notatki
Informacja: Wyniki działania tej funkcji są buforowane. Zobacz opis funkcji clearstatcache() aby uzyskać więcej informacji.
Od PHP 5.0.0 ta funkcja może być użyta także z niektórymi nakładkami URL. Zobacz Supported Protocols and Wrappers aby uzyskać listę nakładek, które obsługują funkcjonalność z rodziny stat().
Zobacz też:
- is_readable() - Tells whether a file exists and is readable
- is_writable() - Tells whether the filename is writable
- is_file() - Mówi czy nazwa_pliku jest zwykłym plikiem
- file() - Czyta całą zawartość pliku do tablicy
file_get_contents
(PHP 4 >= 4.3.0, PHP 5)
file_get_contents — Reads entire file into a string
Opis
$filename
[, bool $use_include_path = false
[, resource $context
[, int $offset = -1
[, int $maxlen
]]]] )
This function is similar to file(), except that
file_get_contents() returns the file in a
string, starting at the specified offset
up to maxlen bytes. On failure,
file_get_contents() will return FALSE.
file_get_contents() is the preferred way to read the contents of a file into a string. It will use memory mapping techniques if supported by your OS to enhance performance.
Informacja:
If you're opening a URI with special characters, such as spaces, you need to encode the URI with urlencode().
Parametry
-
filename -
Name of the file to read.
-
use_include_path -
Informacja:
As of PHP 5 the
FILE_USE_INCLUDE_PATHcan be used to trigger include path search. -
context -
A valid context resource created with stream_context_create(). If you don't need to use a custom context, you can skip this parameter by
NULL. -
offset -
The offset where the reading starts on the original stream.
Seeking (
offset) is not supported with remote files. Attempting to seek on non-local files may work with small offsets, but this is unpredictable because it works on the buffered stream. -
maxlen -
Maximum length of data read. The default is to read until end of file is reached. Note that this parameter is applied to the stream processed by the filters.
Zwracane wartości
The function returns the read data lub FALSE w przypadku niepowodzenia.
Błędy/Wyjątki
An E_WARNING level error is generated if either maxlength
is less than zero, or if offset exceeds the length of the stream.
Przykłady
Przykład #1 Get and output the source of the homepage of a website
<?php
$homepage = file_get_contents('http://www.example.com/');
echo $homepage;
?>
Przykład #2 Searching within the include_path
<?php
// <= PHP 5
$file = file_get_contents('./people.txt', true);
// > PHP 5
$file = file_get_contents('./people.txt', FILE_USE_INCLUDE_PATH);
?>
Przykład #3 Reading a section of a file
<?php
// Read 14 characters starting from the 21st character
$section = file_get_contents('./people.txt', NULL, NULL, 20, 14);
var_dump($section);
?>
Powyższy przykład wyświetli coś podobnego do:
string(14) "lle Bjori Ro"
Przykład #4 Using stream contexts
<?php
// Create a stream
$opts = array(
'http'=>array(
'method'=>"GET",
'header'=>"Accept-language: en\r\n" .
"Cookie: foo=bar\r\n"
)
);
$context = stream_context_create($opts);
// Open the file using the HTTP headers set above
$file = file_get_contents('http://www.example.com/', false, $context);
?>
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.1.0 |
Added the offset and
maxlen parameters.
|
| 5.0.0 | Added context support. |
Notatki
Informacja: Ta funkcja jest bezpieczna dla danych binarnych.
Jeśli włączona jest dyrektywa konfiguracyjna fopen wrappers, możliwe jest podanie jako nazwy pliku adresu URL. Zobacz opis funkcji fopen() aby dowiedzieć się jak przekazać nazwę pliku, oraz fopen wrappers aby uzyskać listę obsługiwanych protokołów.
Nawiązując połączenie przez SSL, serwer Microsoft IIS narusza reguły protokołu przez zamknięcie połączenia bez wysłania wskaźnika close_notify. Po przesłaniu całości danych PHP zgłosi to jako "SSL: Fatal Protocol Error". Aby obejść ten błąd, wystarczy obniżyć poziom raportowania błędów error_reporting, tak aby nie były wyświetlane ostrzeżenia. PHP 4.3.7 i nowsze wersje same wykrywają błąd serwera IIS przy otwieraniu strumienia https:// i za pomocą nakładki i pomijają ostrzeżenia. Używając funkcji fsockopen() do otwarcia gniazda ssl:// programista sam musi zadbać o wyłączenie ostrzeżeń.
Zobacz też:
- file() - Czyta całą zawartość pliku do tablicy
- fgets() - Pobiera linię ze wskaźnika pliku
- fread() - Odczyt pliku binarnie bezpieczy
- readfile() - Wyświetla plik
- file_put_contents() - Write a string to a file
- stream_get_contents() - Reads remainder of a stream into a string
- stream_context_create() - Creates a stream context
- $http_response_header
file_put_contents
(PHP 5)
file_put_contents — Write a string to a file
Opis
This function is identical to calling fopen(), fwrite() and fclose() successively to write data to a file.
If filename does not exist, the file is created.
Otherwise, the existing file is overwritten, unless the
FILE_APPEND flag is set.
Parametry
-
filename -
Path to the file where to write the data.
-
data -
The data to write. Can be either a string, an array or a stream resource.
If
datais a stream resource, the remaining buffer of that stream will be copied to the specified file. This is similar with using stream_copy_to_stream().You can also specify the
dataparameter as a single dimension array. This is equivalent to file_put_contents($filename, implode('', $array)). -
flags -
The value of
flagscan be any combination of the following flags, joined with the binary OR (|) operator.Available flags Flag Description FILE_USE_INCLUDE_PATHSearch for filenamein the include directory. See include_path for more information.FILE_APPENDIf file filenamealready exists, append the data to the file instead of overwriting it.LOCK_EXAcquire an exclusive lock on the file while proceeding to the writing. -
context -
A valid context resource created with stream_context_create().
Zwracane wartości
The function returns the number of bytes that were written to the file, or
FALSE on failure.
Ta funkcja może
zwrócić Boolean FALSE, ale może też zwrócić wartość innego typu niż Boolean, która oznacza
wartość FALSE, takie jak 0 lub
"". Aby uzyskać więcej informacji proszę zapoznać się z rozdziałem Typy logiczne.
Można używać operatora ===
do testowania zwracanych wartości przez tę
funkcję.
Przykłady
Przykład #1 Simple usage example
<?php
$file = 'people.txt';
// Open the file to get existing content
$current = file_get_contents($file);
// Append a new person to the file
$current .= "John Smith\n";
// Write the contents back to the file
file_put_contents($file, $current);
?>
Przykład #2 Using flags
<?php
$file = 'people.txt';
// The new person to add to the file
$person = "John Smith\n";
// Write the contents to the file,
// using the FILE_APPEND flag to append the content to the end of the file
// and the LOCK_EX flag to prevent anyone else writing to the file at the same time
file_put_contents($file, $person, FILE_APPEND | LOCK_EX);
?>
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.0.0 | Added context support |
| 5.1.0 |
Added support for LOCK_EX and the ability to pass
a stream resource to the data parameter
|
Notatki
Informacja: Ta funkcja jest bezpieczna dla danych binarnych.
Jeśli włączona jest dyrektywa konfiguracyjna fopen wrappers, możliwe jest podanie jako nazwy pliku adresu URL. Zobacz opis funkcji fopen() aby dowiedzieć się jak przekazać nazwę pliku, oraz fopen wrappers aby uzyskać listę obsługiwanych protokołów.
Zobacz też:
- fopen() - Otwiera plik lub URL
- fwrite() - Zapis pliku binarnie bezpieczny
- file_get_contents() - Reads entire file into a string
- stream_context_create() - Creates a stream context
file
(PHP 4, PHP 5)
file — Czyta całą zawartość pliku do tablicy
Opis
$nazwa_pliku
[, int $flagi
[, resource $kontekst
]] )
Działa podobnie do file_get_contents(), tylko że
file() zwraca plik w tablicy. Każdy
element tablicy odpowiada linii w pliku. Elementy tablicy zawierają
znak nowej linii. W przypadku błędu, file()
zwraca FALSE.
Opcjonalny parametr flagi może być jedną lub więcej, z
następujących stałych:
-
FILE_USE_INCLUDE_PATH - Poszukuj pliku w include_path.
-
FILE_IGNORE_NEW_LINES - Nie dodawaj nowej lini na na końcu każdego elementu tablicy.
-
FILE_SKIP_EMPTY_LINES - Pomiń puste linie.
Informacja:
Przed PHP 5.0.0 parametr
flagijedynie ukrywał include_path i był włączany przez 1.
<?php
// Pobierz plik do tablicy. W tym przykładzie poprzez HTTP pobierzemy
// źródło HTML z URL
$lines = file('http://www.example.com/');
// Za pomocą pętli przeglądamy naszą tablicę i pokazujemy źródło strony w postaci
// źródła HTML oraz numery linii.
foreach ($lines as $line_num => $line) {
echo "Linia #<b>{$line_num}</b> : " . htmlspecialchars($line) . "<br />\n";
}
// Kolejny przyklad pozwala pobrać stronę i umieścić ją w łańcuchu znaków Zobacz także file_get_contents().
$html = implode ('', file ('http://www.example.com/'));
?>
Jeśli włączona jest dyrektywa konfiguracyjna fopen wrappers, możliwe jest podanie jako nazwy pliku adresu URL. Zobacz opis funkcji fopen() aby dowiedzieć się jak przekazać nazwę pliku, oraz fopen wrappers aby uzyskać listę obsługiwanych protokołów.
Informacja:
Każda linia w wynikowej tabeli będzie zawierać znak(i) końca linii chyba, że jest użyte FILE_IGNORE_NEW_LINES, jeśli nie chcesz ich musisz uzyć rtrim().
Informacja: Jeśli PHP niewłaściwie rozpoznaje znaki końca linii podczas odczytu plików stworzonych lub znajdujących się na komputerach Macintosh, problem może rozwiązać włączenie dyrektywy konfiguracyjnej auto_detect_line_endings .
Informacja:
W PHP 4.3.0 możesz użyć file_get_contents() aby zwrócić zawartość pliku do łańcucha.
W PHP 4.3.0 file() stał się binarnie bezpieczny.
Informacja: Obsługa kontekstów została dodana w PHP 5.0.0. Opis kontekstów znajduje się w rozdziale Stream Funkcje.
Nawiązując połączenie przez SSL, serwer Microsoft IIS narusza reguły protokołu przez zamknięcie połączenia bez wysłania wskaźnika close_notify. Po przesłaniu całości danych PHP zgłosi to jako "SSL: Fatal Protocol Error". Aby obejść ten błąd, wystarczy obniżyć poziom raportowania błędów error_reporting, tak aby nie były wyświetlane ostrzeżenia. PHP 4.3.7 i nowsze wersje same wykrywają błąd serwera IIS przy otwieraniu strumienia https:// i za pomocą nakładki i pomijają ostrzeżenia. Używając funkcji fsockopen() do otwarcia gniazda ssl:// programista sam musi zadbać o wyłączenie ostrzeżeń.
Patrz także: readfile(), fopen(), fsockopen(), popen(), file_get_contents(), include() i stream_context_create().
fileatime
(PHP 4, PHP 5)
fileatime — Pobiera ostatni czas dostępu do pliku
Opis
$nazwa_pliku
)
Zwraca czas, kiedy nastąpił ostatni dostęp do pliku lub FALSE w
przypadku błędu. Czas jest zwracany w postaci unix'owego znacznika
czasu.
Notka: Czas dostępu do pliku przypuszczalnie zmienia się zawsze kiedy bloki danych pliku są odczytywane. To może kosztować utratę wydajności aplikacji, które regularnie korzystają z wielu plików lub katalogów. Niektóre unix'owe systemy plików mogą być montowane z wyłączonym uaktualnianiem czasu dostępu, aby podnieść wydajność takich aplikacji; USENETowy katalog roboczy wiadomości jest dobrym przykładem. Na takich systemach plików ta funkcja będzie bezużyteczna.
Informacja: Wyniki działania tej funkcji są buforowane. Zobacz opis funkcji clearstatcache() aby uzyskać więcej informacji.
Od PHP 5.0.0 ta funkcja może być użyta także z niektórymi nakładkami URL. Zobacz Supported Protocols and Wrappers aby uzyskać listę nakładek, które obsługują funkcjonalność z rodziny stat().
Przykład #1 fileatime() przykład
<?php
// przykładowy wynik: ostatni dostep do pliku: jakisplik.txt December 29 2002 22:16:23.
$filename = 'jakisplik.txt';
if (file_exists($filename)) {
echo "ostatni dostep do pliku: $filename " . date("F d Y H:i:s.", fileatime($filename));
}
?>
Ta funkcja nie działa na zdalnych plikach; sprawdzany plik musi być dostępny przez system plików serwera.
filectime
(PHP 4, PHP 5)
filectime — Pobiera i-węzłowy czas zmiany pliku
Opis
$nazwa_pliku
)
Zwraca czas, ostatniej zmiany pliku lub FALSE w
przypadku błędu. Czas jest zwracany w postaci unix'owego znacznika
czasu.
Uwaga: W większości Unixowych systemów plików, plik ulega zmianie wtedy kiedy dane jego i-węzła zmieniają się; tj. kiedy prawa dostępu, właściciel, grupa lub inne metadane z i-węzłą są nadpisywane. Patrz także: filemtime() (którą powinnieneś użyć, gdy chcesz stworzyć stopkę strony "Ostatnia Modyfikacja") i fileatime().
Zauważ także, że w niektórych tekstach Unixowych ctime pliku jest określany jako będący czasem stworzenia pliku. To jest nieprawidłowe. Nie ma pojęcia czasu stworzenia dla plików Unixowych większości Unixowych systemów plików.
Informacja: Wyniki działania tej funkcji są buforowane. Zobacz opis funkcji clearstatcache() aby uzyskać więcej informacji.
Od PHP 5.0.0 ta funkcja może być użyta także z niektórymi nakładkami URL. Zobacz Supported Protocols and Wrappers aby uzyskać listę nakładek, które obsługują funkcjonalność z rodziny stat().
Przykład #1 filectime() przykład
<?php
// wyświetli np. jakisplik.txt został ostatnio zmieniony : December 29 2002 22:16:23.
$filename = 'jakisplik.txt';
if (file_exists($filename)) {
echo "$filename został ostatnio zmieniony : " . date("F d Y H:i:s.", filectime($filename));
}
?>
Patrz także: filemtime()
filegroup
(PHP 4, PHP 5)
filegroup — Pobiera grupę pliku
Opis
$nazwa_pliku
)
Zwraca identyfikator grupy pliku lub
FALSE w przypadku błędu. Identyfikator grupy zwracany jest
w postaci numerycznej, użyj posix_getgrgid() aby rozwinąć
go w nazwę grupy.
W przypadku niepowodzenia zwracany jest FALSE przy ustawionym poziomie błędów na
E_WARNING.
Informacja: Wyniki działania tej funkcji są buforowane. Zobacz opis funkcji clearstatcache() aby uzyskać więcej informacji.
Od PHP 5.0.0 ta funkcja może być użyta także z niektórymi nakładkami URL. Zobacz Supported Protocols and Wrappers aby uzyskać listę nakładek, które obsługują funkcjonalność z rodziny stat().
Informacja: Patrz także fileowner() i safe_mode_gid.
fileinode
(PHP 4, PHP 5)
fileinode — Pobiera i-węzeł pliku
Opis
$nazwa_pliku
)
Zwraca numer i-węzła pliku lub FALSE w przypadku błędu.
Informacja: Wyniki działania tej funkcji są buforowane. Zobacz opis funkcji clearstatcache() aby uzyskać więcej informacji.
Od PHP 5.0.0 ta funkcja może być użyta także z niektórymi nakładkami URL. Zobacz Supported Protocols and Wrappers aby uzyskać listę nakładek, które obsługują funkcjonalność z rodziny stat().
Patrz także: stat().
filemtime
(PHP 4, PHP 5)
filemtime — Pobiera czas ostatniej modyfikacji pliku
Opis
$nazwa_pliku
)Ta funkcja zwraca czas kiedy bloki danych pliku zostały zapisane, to jest, czas kiedy zawartość pliku została zmieniona.
Parametry
-
nazwa_pliku -
Ścieżka do pliku.
Zwracane wartości
Zwraca czas, kiedy plik był ostatnio modyfikowany lub FALSE w przypadku niepowodzenia.
Czas jest zwracany w postaci unix'owego znacznika czasu, który
jest odpowiedni dla funkcji date().
Przykłady
Przykład #1 filemtime() przykład
<?php
// wyświetli np. jakisplik.txt został ostatnio zmodyfikowny : December 29 2002 22:16:23.
$filename = 'jakisplik.txt';
if (file_exists($filename)) {
echo "$filename został ostatnio zmodyfikowny : " . date ("F d Y H:i:s.", filemtime($filename));
}
?>
Błędy/Wyjątki
W przypadku niepowodzenia jest emitowany E_WARNING.
Notatki
Informacja:
Proszę zauważyć, że informacja o czasie dostępu może się różnić w zależności od systemu plików.
Informacja: Wyniki działania tej funkcji są buforowane. Zobacz opis funkcji clearstatcache() aby uzyskać więcej informacji.
Od PHP 5.0.0 ta funkcja może być użyta także z niektórymi nakładkami URL. Zobacz Supported Protocols and Wrappers aby uzyskać listę nakładek, które obsługują funkcjonalność z rodziny stat().
Zobacz też:
- filectime() - Pobiera i-węzłowy czas zmiany pliku
- stat() - Gives information about a file
- touch() - Ustawia czas modyfikacji pliku
- getlastmod() - Gets time of last page modification
fileowner
(PHP 4, PHP 5)
fileowner — Pobiera właściciela pliku
Opis
$nazwa_pliku
)
Zwraca identyfikator użytkownika, który jest właścicielem pliku, lub
FALSE w przypadku błędu. Identyfikator użytkownika zwracany jest
w postaci numerycznej, użyj
posix_getpwuid() aby rozwinąć go w nazwę użytkownika.
Informacja: Wyniki działania tej funkcji są buforowane. Zobacz opis funkcji clearstatcache() aby uzyskać więcej informacji.
Od PHP 5.0.0 ta funkcja może być użyta także z niektórymi nakładkami URL. Zobacz Supported Protocols and Wrappers aby uzyskać listę nakładek, które obsługują funkcjonalność z rodziny stat().
Patrz także: stat()
fileperms
(PHP 4, PHP 5)
fileperms — Pobiera prawa dostępu pliku
Opis
$nazwa_pliku
)
Zwraca prawa dostępu pliku, lub FALSE w przypadku błędu.
Informacja: Wyniki działania tej funkcji są buforowane. Zobacz opis funkcji clearstatcache() aby uzyskać więcej informacji.
Od PHP 5.0.0 ta funkcja może być użyta także z niektórymi nakładkami URL. Zobacz Supported Protocols and Wrappers aby uzyskać listę nakładek, które obsługują funkcjonalność z rodziny stat().
Przykład #1 Wyświetlanie uprawnień w postaci ósemkowej
<?php
echo substr(sprintf('%o', fileperms('/tmp')), -4);
echo substr(sprintf('%o', fileperms('/etc/passwd')), -4);
?>
To powino wyświetlić:
1777 0644
Przykład #2 Wyświetlanie wszystkich uprawnień
<?php
$perms = fileperms('/etc/passwd');
if (($perms & 0xC000) == 0xC000) {
// Gniazdo (socket)
$info = 's';
} elseif (($perms & 0xA000) == 0xA000) {
// Link symboliczny
$info = 'l';
} elseif (($perms & 0x8000) == 0x8000) {
// Zwykły plik
$info = '-';
} elseif (($perms & 0x6000) == 0x6000) {
// Urządzenie blokowe
$info = 'b';
} elseif (($perms & 0x4000) == 0x4000) {
// Katalog
$info = 'd';
} elseif (($perms & 0x2000) == 0x2000) {
// Urządzenie znakowe
$info = 'c';
} elseif (($perms & 0x1000) == 0x1000) {
// Potok (FIFO)
$info = 'p';
} else {
// Nieznane
$info = 'u';
}
// Właściciel
$info .= (($perms & 0x0100) ? 'r' : '-');
$info .= (($perms & 0x0080) ? 'w' : '-');
$info .= (($perms & 0x0040) ?
(($perms & 0x0800) ? 's' : 'x' ) :
(($perms & 0x0800) ? 'S' : '-'));
// Grupa
$info .= (($perms & 0x0020) ? 'r' : '-');
$info .= (($perms & 0x0010) ? 'w' : '-');
$info .= (($perms & 0x0008) ?
(($perms & 0x0400) ? 's' : 'x' ) :
(($perms & 0x0400) ? 'S' : '-'));
// Świat
$info .= (($perms & 0x0004) ? 'r' : '-');
$info .= (($perms & 0x0002) ? 'w' : '-');
$info .= (($perms & 0x0001) ?
(($perms & 0x0200) ? 't' : 'x' ) :
(($perms & 0x0200) ? 'T' : '-'));
echo $info;
?>
To powino wyświetlić:
-rw-r--r--
Patrz także: is_readable(), i stat()
filesize
(PHP 4, PHP 5)
filesize — Pobiera rozmiar pliku
Opis
$nazwa_pliku
)
Zwraca rozmiar pliku w bajtach, lub FALSE (oraz zostanie wygenerowany błąd na poziomie
E_WARNING) w przypadku błędu.
Informacja: Ponieważ PHPowy typ integer jest oznaczony (ang. signed, dopuszcza liczby ujemne i dodatnie) i wiele platform używa 32 bitowego integera, filesize() może zwrócić nieoczekiwane wyniki dla plików większych od 2 GB. Dla plików o rozmiarze pomiędzy 2 GB, a 4 GB można zwykle przezwyciężyć to używając sprintf("%u", filesize($plik)).
Informacja: Wyniki działania tej funkcji są buforowane. Zobacz opis funkcji clearstatcache() aby uzyskać więcej informacji.
Od PHP 5.0.0 ta funkcja może być użyta także z niektórymi nakładkami URL. Zobacz Supported Protocols and Wrappers aby uzyskać listę nakładek, które obsługują funkcjonalność z rodziny stat().
Przykład #1 filesize() przykład
<?php
// wyświetli np. jakisplik.txt: 1024 bajtów
$filename = 'jakisplik.txt';
echo $filename . ': ' . filesize($filename) . ' bajtów';
?>
Patrz także: file_exists()
filetype
(PHP 4, PHP 5)
filetype — Pobiera typ pliku
Opis
$nazwa_pliku
)Zwraca typ pliku. Możliwe wartości to fifo, char, dir, block, link, file i unknown.
Zwraca FALSE jeśli wystąpił błąd. filetype() również
utworzy wiadomość E_NOTICE jeśli wywołanie stat się
nie powiedzie lub gdy plik ma tym nieznany (unknown).
Informacja: Wyniki działania tej funkcji są buforowane. Zobacz opis funkcji clearstatcache() aby uzyskać więcej informacji.
Od PHP 5.0.0 ta funkcja może być użyta także z niektórymi nakładkami URL. Zobacz Supported Protocols and Wrappers aby uzyskać listę nakładek, które obsługują funkcjonalność z rodziny stat().
Przykład #1 filetype() przykład
<?php
echo filetype('/etc/passwd'); // plik
echo filetype('/etc/'); // katalog
?>
Patrz także: is_dir(), is_file(), is_link(), file_exists(), stat() i mime_content_type().
flock
(PHP 4, PHP 5)
flock — Portable advisory file locking
Opis
$handle
, int $operation
[, int &$wouldblock
] )flock() allows you to perform a simple reader/writer model which can be used on virtually every platform (including most Unix derivatives and even Windows).
On versions of PHP before 5.3.2, the lock is released also by fclose() (which is also called automatically when script finished).
PHP supports a portable way of locking complete files in an advisory way
(which means all accessing programs have to use the same way of locking
or it will not work). By default, this function will block until the
requested lock is acquired; this may be controlled (on non-Windows
platforms) with the LOCK_NB option documented below.
Parametry
-
handle -
Wskaźnik do systemu plików typu resource jest zazwyczaj tworzony poprzez funkcję fopen().
-
operation -
operationis one of the following:-
LOCK_SHto acquire a shared lock (reader). -
LOCK_EXto acquire an exclusive lock (writer). -
LOCK_UNto release a lock (shared or exclusive).
It is also possible to add
LOCK_NBas a bitmask to one of the above operations if you don't want flock() to block while locking. (not supported on Windows) -
-
wouldblock -
The optional third argument is set to
TRUEif the lock would block (EWOULDBLOCK errno condition). (not supported on Windows)
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.2 | The automatic unlocking when the file's resource handle is closed was removed. Unlocking now always has to be done manually. |
| 4.0.1 |
The LOCK_XXX constants were added. Prior to that
you must use 1 for LOCK_SH, 2 for
LOCK_EX, 3 for LOCK_UN and
4 for LOCK_NB
|
Przykłady
Przykład #1 flock() example
<?php
$fp = fopen("/tmp/lock.txt", "r+");
if (flock($fp, LOCK_EX)) { // acquire an exclusive lock
ftruncate($fp, 0); // truncate file
fwrite($fp, "Write something here\n");
fflush($fp); // flush output before releasing the lock
flock($fp, LOCK_UN); // release the lock
} else {
echo "Couldn't get the lock!";
}
fclose($fp);
?>
Przykład #2 flock() using the LOCK_NB option
<?php
$fp = fopen('/tmp/lock.txt', 'r+');
/* Activate the LOCK_NB option on an LOCK_EX operation */
if(!flock($fp, LOCK_EX | LOCK_NB)) {
echo 'Unable to obtain lock';
exit(-1);
}
/* ... */
fclose($fp);
?>
Notatki
Informacja:
flock() uses mandatory locking instead of advisory locking on Windows. Mandatory locking is also supported on Linux and System V based operating systems via the usual mechanism supported by the fcntl() system call: that is, if the file in question has the setgid permission bit set and the group execution bit cleared. On Linux, the file system will also need to be mounted with the mand option for this to work.
Informacja:
Because flock() requires a file pointer, you may have to use a special lock file to protect access to a file that you intend to truncate by opening it in write mode (with a "w" or "w+" argument to fopen()).
Informacja:
May only be used on file pointers returned by fopen() for local files, or file pointers pointing to userspace streams that implement the streamWrapper::stream_lock() method.
Assigning another value to handle argument in
subsequent code will release the lock.
On some operating systems flock() is implemented at the process level. When using a multithreaded server API like ISAPI you may not be able to rely on flock() to protect files against other PHP scripts running in parallel threads of the same server instance!
flock() is not supported on antiquated filesystems like
FAT and its derivates and will therefore always
return FALSE under this environments (this is especially true for
Windows 98 users).
fnmatch
(PHP 4 >= 4.3.0, PHP 5)
fnmatch — Match filename against a pattern
Opis
$pattern
, string $string
[, int $flags = 0
] )
fnmatch() checks if the passed string would
match the given shell wildcard pattern.
Parametry
-
pattern -
The shell wildcard pattern.
-
string -
The tested string. This function is especially useful for filenames, but may also be used on regular strings.
The average user may be used to shell patterns or at least in their simplest form to '?' and '*' wildcards so using fnmatch() instead of preg_match() for frontend search expression input may be way more convenient for non-programming users.
-
flags -
The value of
flagscan be any combination of the following flags, joined with the binary OR (|) operator.A list of possible flags for fnmatch() FlagDescription FNM_NOESCAPEDisable backslash escaping. FNM_PATHNAMESlash in string only matches slash in the given pattern. FNM_PERIODLeading period in string must be exactly matched by period in the given pattern. FNM_CASEFOLDCaseless match. Part of the GNU extension.
Zwracane wartości
Returns TRUE if there is a match, FALSE otherwise.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.0 | This function is now available on Windows platforms. |
Przykłady
Przykład #1 Checking a color name against a shell wildcard pattern
<?php
if (fnmatch("*gr[ae]y", $color)) {
echo "some form of gray ...";
}
?>
Notatki
For now this function is not available on non-POSIX compliant systems.
Zobacz też:
- glob() - Find pathnames matching a pattern
- preg_match() - Perform a regular expression match
- sscanf() - Parses input from a string according to a format
- printf() - Output a formatted string
- sprintf() - Return a formatted string
fopen
(PHP 4, PHP 5)
fopen — Otwiera plik lub URL
Opis
$nazwa_pliku
, string $tryb
[, bool $użyj_include_path
[, resource $kontekst
]] )
fopen() wiąże nazwany zasób, określony przez
nazwa_pliku, do strumienia.
Parametry
-
nazwa_pliku -
Jeśli
nazwa_plikujest w postaci "schemat://...", to przypuszczalnie jest to URL i PHP szuka protokołu obsługi (także zwanego wrapper'em) dla tego schematu. Jeśli nie zarejestrowano żadnego wrapper'a dla tego protokołu, PHP wyemituje notatkę, aby pomóc Tobie w wyśledzeniu potencajalnego problemu w Twoim skrypcie następnie będzie kontynuować z podanymnazwa_plikutraktując go jako zwykły plik.Jeśli PHP zdecyduje, że
nazwa_plikuokreśla lokalny plik, wtedy spróbuje otworzyć strumień na tym pliku. Plik musi być dostępny dla PHP, więc musisz zapewnić prawa dostępu do pliku pozwalające na taką operację. Jeśli masz włączone tryb bezpieczny lub open_basedir mogą mieć zastosowanie dodatkowe restrykcje.Jeśli PHP zdecyduje, że
nazwa_plikuokreśla zarejestrowany protokół i ten protokół jest zarejestowany jako sieciowy URL, PHP sprawdzi allow_url_fopen czy jest włączone. Jeśli jest wyłączone (off), PHP wyświetli ostrzeżenie i wywołanie fopen zakończy się niepowodzeniem.Informacja:
Listę obsługiwanych protokołów możesz znaleźć w Supported Protocols and Wrappers. Niektóre protokoły (również określane przez wrappery obsługują kontekst lub/i opcje php.ini. Odwołaj się do konkretnej strony protokołu aby uzyskać listę opcji jakie mogą zostać ustawione (np. php.ini wartość user_agent używana przez wrapper http).
Na platformie Windows, dbaj aby wstawiać znaki ucieczki (escape) przed wszystkimi lewymi ukośnikami (backslash) użytymi w ścieżce do pliku lub używać ukośników (slash).
<?php
$handle = fopen("c:\\data\\info.txt", "r");
?> -
tryb -
Parametr
trybokreśla rodzaj dostępu jaki wymagasz do strumienia. Może być dowolny z następujących:Lista możliwych trybów dla fopen() używając trybtrybOpis 'r' Otwiera tylko do odczytu; umieszcza wskaźnik pliku na jego początku. 'r+' Otwiera do odczytu i zapisu; umieszcza wskaźnik pliku na jego początku. 'w' Otwiera tylko do zapisu; umieszcza wskaźnik pliku na jego początku i obcina plik do zerowej długości. Jeśli plik nie istnieje to próbuje go utworzyć. 'w+' Otwiera do odczytu i zapisu; umieszcza wskaźnik pliku na jego początku i obcina plik do zerowej długości. Jeśli plik nie istnieje to próbuje go utworzyć. 'a' Otwiera tylko do zapisu; umieszcza wskaźnik pliku na jego końcu. Jeśli plik nie istnieje to próbuje go utworzyć. 'a+' Otwiera do odczytu i zapisu; umieszcza wskaźnik pliku na jego końcu. Jeśli plik nie istnieje to próbuje go utworzyć. 'x' Tworzy i otwiera plik tylko do zapisu; umieszcza wskaźnik pliku na jego początku. Jeśli plik juz istnieje, wywołanie fopen() nie powiedzie się, zwróci FALSEi wygeneruje błąd na poziomieE_WARNING. Jeśli plik nie istnieje, spróbuje go utworzyć. To jest równoważne z określeniem flag O_EXCL|O_CREAT stosowanym w wywołaniu systemowym open(2).'x+' Tworzy i otwiera plik odczytu i zapisu; umieszcza wskaźnik pliku na jego początku. Jeśli plik juz istnieje, wywołanie fopen() nie powiedzie się, zwróci FALSEi wygeneruje błąd na poziomieE_WARNING. Jeśli plik nie istnieje, spróbuje go utworzyć. To jest równoważne z okresleniem flag O_EXCL|O_CREAT stosowanym w wywołaniu systemowym open(2).Informacja:
Różne rodziny systemów operacyjnych stosuja rózne konwencje końca lini. Kiedy zapisujesz plik tekstowy i chcesz wstawić łamanie lini, musisz użyć poprawnych dla twojego systemu operacyjnego znak(ów) końca lini. Systemy bazujące na Uniksie używają \n jako znaku końca lini, systemy bazujące na Windowsie używają \r\n jako znaków końca lini, a systemy Macintosh używają \r jako znak końca lini.
Jeśli użyjesz nieprawidłowego końca lini do zapisu pliku, możesz zaobserwować, w innych aplikacjach otwierając ten plik, że "wygląda on zabawnie".
Windows oferuje flagę ('t') konwertującą tryb tekstowy, która przezroczyście przekłada \n na \r\n kiedy pracujesz z plikiem. Dla kontrastu, możesz także uzyć 'b' aby wymusić tryb binarny, wtedy nie będzie konwertować twoich danych. Aby użyć tych flag, wstaw 'b' lub 't' jako ostatni znak w parametrze
tryb.Domyślnie tryb konwersji zależy od SAPI i wersji PHP jakiej używasz, więc namawiamy aby zawsze podawać stosowną flage w celu przenośności. Powinieneś użyć trybu 't' jeśli pracujesz ze zwykłymi plikami tekstowymi (plain-text)i używasz \n do ograniczenia konców lini w twoim skrypcie, ale wymagasz aby twój plik był czytelny w aplikacjach takich jak notatnik. Powinieneś uzyć 'b' w każdym innym przypadku.
Jeśli nie podasz flagi 'b' kiedy pracujesz na binarnych plikach, możesz doświadczyć dziwnych problemów z twoimi danymi, włączając uszkodzone pliki graficzne i dziwne problemy ze znakami \r\n.
Informacja:
Dla przenośności, bardzo zalecane jest użycie zawsze flagi 'b' kiedy otwierasz pliki za pomocą fopen().
Informacja:
Ponownie, dla przenośności, jest również bardzo zalecane abyś, przepisał swój kod, który używa lub polega na trybie 't' tak aby używał poprawnego końca lini oraz trybu 'b'.
-
użyj_include_path -
Opcjonalny trzeci parametr
użyj_include_pathmoże być ustawiony na '1' lubTRUEjeśli chcesz szukać pliku także w include_path. -
kontekst -
Informacja: Obsługa kontekstów została dodana w PHP 5.0.0. Opis kontekstów znajduje się w rozdziale Stream Funkcje.
Zwracane wartości
Zwraca wskaźnik pliku do zasobu w przypadku sukcesu lub FALSE przy błędzie.
Błędy/Wyjątki
Jeśli otwieranie się nie powiedzie, funkcja wygeneruje błąd na poziomie
E_WARNING. Możesz użyć @ aby
zatuszować to ostrzeżenie.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.3.2 | Od PHP 4.3.2 domyślny tryb ustawiany jest na binarny, dla wszystkich platform, które rozróżniają tryby binarne i tekstowe. Jeśli masz problemy ze skryptem po aktualizacji, spróbuj użyć flagi 't' jako obejście dopóki nie uczynisz Twojego skryptu bardziej przenośnym jak opisano niżej. |
| 4.3.2 | Dodano opcje 'x' i 'x+' |
Przykłady
Przykład #1 fopen() przykłady
<?php
$handle = fopen("/home/rasmus/plik.txt", "r");
$handle = fopen("/home/rasmus/plik.gif", "wb");
$handle = fopen("http://www.przyklad.com/", "r");
$handle = fopen("ftp://uzytkownik:haslo@przyklad.com/jakisplik.txt", "w");
?>
Notatki
Nawiązując połączenie przez SSL, serwer Microsoft IIS narusza reguły protokołu przez zamknięcie połączenia bez wysłania wskaźnika close_notify. Po przesłaniu całości danych PHP zgłosi to jako "SSL: Fatal Protocol Error". Aby obejść ten błąd, wystarczy obniżyć poziom raportowania błędów error_reporting, tak aby nie były wyświetlane ostrzeżenia. PHP 4.3.7 i nowsze wersje same wykrywają błąd serwera IIS przy otwieraniu strumienia https:// i za pomocą nakładki i pomijają ostrzeżenia. Używając funkcji fsockopen() do otwarcia gniazda ssl:// programista sam musi zadbać o wyłączenie ostrzeżeń.
Informacja: Gdy włączony jest tryb bezpieczny, PHP sprawdza czy katalog, na którym zostaną wykonane operacje, ma takie same UID (owner) jak skrypt, który jest aktualnie wykonywany.
Jeśli doświadczasz problemów z odczytem lub zapisywaniem do plików i używasz PHP w postaci modułu serwera, pamiętaj, żeby się upewnić, że pliki i katalogi, których używasz są dostępne dla procesu serwera.
Zobacz też:
- Supported Protocols and Wrappers
- fclose() - Zamyka otwarty wskaźnik pliku
- fgets() - Pobiera linię ze wskaźnika pliku
- fread() - Odczyt pliku binarnie bezpieczy
- fwrite() - Zapis pliku binarnie bezpieczny
- fsockopen() - Open Internet or Unix domain socket connection
- file() - Czyta całą zawartość pliku do tablicy
- file_exists() - Sprawdza czy plik lub katalog istnieje
- is_readable() - Tells whether a file exists and is readable
- stream_set_timeout() - Set timeout period on a stream
- popen() - Otwiera wskaźnik pliku do procesu
- stream_context_create() - Creates a stream context
fpassthru
(PHP 4, PHP 5)
fpassthru — Output all remaining data on a file pointer
Opis
$handle
)Reads to EOF on the given file pointer from the current position and writes the results to the output buffer.
You may need to call rewind() to reset the file pointer to the beginning of the file if you have already written data to the file.
If you just want to dump the contents of a file to the output buffer, without first modifying it or seeking to a particular offset, you may want to use the readfile(), which saves you the fopen() call.
Parametry
-
handle -
Wskaźnik na plik musi być poprawny i musi wskazywać na plik pomyślnie otwarty przez funkcję fopen() lub fsockopen() (a jednocześnie nie zamknięty jeszcze przez fclose()).
Zwracane wartości
If an error occurs, fpassthru() returns
FALSE. Otherwise, fpassthru() returns
the number of characters read from handle
and passed through to the output.
Przykłady
Przykład #1 Using fpassthru() with binary files
<?php
// open the file in a binary mode
$name = './img/ok.png';
$fp = fopen($name, 'rb');
// send the right headers
header("Content-Type: image/png");
header("Content-Length: " . filesize($name));
// dump the picture and stop the script
fpassthru($fp);
exit;
?>
Notatki
Informacja:
When using fpassthru() on a binary file on Windows systems, you should make sure to open the file in binary mode by appending a b to the mode used in the call to fopen().
You are encouraged to use the b flag when dealing with binary files, even if your system does not require it, so that your scripts will be more portable.
Zobacz też:
- readfile() - Wyświetla plik
- fopen() - Otwiera plik lub URL
- popen() - Otwiera wskaźnik pliku do procesu
- fsockopen() - Open Internet or Unix domain socket connection
fputcsv
(PHP 5 >= 5.1.0)
fputcsv — Format line as CSV and write to file pointer
Opis
$handle
, array $fields
[, string $delimiter = ','
[, string $enclosure = '"'
]] )
fputcsv() formats a line (passed as a
fields array) as CSV and write it (terminated by a
newline) to the specified file handle.
Parametry
-
handle -
Wskaźnik na plik musi być poprawny i musi wskazywać na plik pomyślnie otwarty przez funkcję fopen() lub fsockopen() (a jednocześnie nie zamknięty jeszcze przez fclose()).
-
fields -
An array of values.
-
delimiter -
The optional
delimiterparameter sets the field delimiter (one character only). -
enclosure -
The optional
enclosureparameter sets the field enclosure (one character only).
Zwracane wartości
Returns the length of the written string lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 fputcsv() example
<?php
$list = array (
array('aaa', 'bbb', 'ccc', 'dddd'),
array('123', '456', '789'),
array('"aaa"', '"bbb"')
);
$fp = fopen('file.csv', 'w');
foreach ($list as $fields) {
fputcsv($fp, $fields);
}
fclose($fp);
?>
The above example will write the following to file.csv:
aaa,bbb,ccc,dddd 123,456,789 """aaa""","""bbb"""
Notatki
Informacja: Jeśli PHP niewłaściwie rozpoznaje znaki końca linii podczas odczytu plików stworzonych lub znajdujących się na komputerach Macintosh, problem może rozwiązać włączenie dyrektywy konfiguracyjnej auto_detect_line_endings .
fread
(PHP 4, PHP 5)
fread — Odczyt pliku binarnie bezpieczy
Opis
$uchwyt
, int $długość
)
fread() odczytuje do
długość bajtów ze wskaźnika pliku
określonego przez uchwyt. Czytanie kończy się
gdy odczytano długość bajtów, osiągnięty
został koniec pliku (EOF), (dla sieciowych strumieni), kiedy pakiet
stanie się dostępny lub (po otwarciu strumienia z przestrzeni użytkownika)
kiedy 8192 bajtów zostanie odczytanych, cokolwiek nastąpi pierwsze.
Zwraca łańcuch znaków lub FALSE w przypadku błędu.
<?php
// pobierz zawartość pliku do łańcucha
$nazwa_pliku = "/usr/local/jakis.txt";
$uchwyt = fopen($nazwa_pliku, "r");
$tresc = fread($uchwyt, filesize($nazwa_pliku));
fclose($uchwyt);
?>
W systemach, które rozróżniają pliki binarne i tekstowe (np. Windows) plik musi zostać otworzony z 'b' dołączonym do parametru tryb fopen().
<?php
$nazwa_pliku = "c:\\pliki\\jakisobrazek.gif";
$uchwyt = fopen($nazwa_pliku, "rb");
$tresc = fread($uchwyt, filesize($nazwa_pliku));
fclose($uchwyt);
?>
Kiedy następuje odczyt z czegokolwiek innego niż zwykłe lokalne pliki, takich jak strumienie zwrócone gdy odczytujesz zdalne pliki lub z popen() i fsockopen(), odczyt zakończy się po tym jak pakiet jest dostępny. To znaczy, że powinieneś gromadzić dane razem z kawałków jak pokazano na poniższych przykładach.
<?php
// dla PHP 5 i nowszych
$uchwyt = fopen("http://www.example.com/", "rb");
$tresc = stream_get_contents($uchwyt);
fclose($uchwyt);
?>
<?php
$uchwyt = fopen("http://www.przykladowy.com/", "rb");
$tresc = '';
while (!feof($uchwyt)) {
$tresc .= fread($uchwyt, 8192);
}
fclose($uchwyt);
?>
Informacja:
Jeśli po prostu chcesz otrzymać treść pliku w stringu, użyj file_get_contents() dlatego, że ma to dużo lepszą wydajność niż kod powyżej.
Patrz także: fwrite(), fopen(), fsockopen(), popen(), fgets(), fgetss(), fscanf(), file() i fpassthru().
fscanf
(PHP 4 >= 4.0.1, PHP 5)
fscanf — Przetwarza dane z pliku według formatu
Opis
Funkcja fscanf() jest podobna do
sscanf(), ale pobiera dane wejściowe z pliku
skojarzonego z uchwytem i interpretuje je
zgodnie z podanym formatem, który opisany jest
w dokumentacji do sprintf().
Jeśli tylko dwa parametry zostaną podane do funkcji, przetworzone
wartości zostaną zwrócone w tablicy.
W przeciwnym razie, jeśli opcjonalne parametry zostaną podane,
funkcja zwróci numer przypisany do wartości. Opcjonalny parametr
musi być podawany przez referencje.
Dowolny biały znak w łańcuchu formatującym pasuje do dowolnego białego znaku w strumieniu wejściowym. To znaczy, że nawet tabulacja \t w łańcuchu formatującym może być dopasowana do pojedynczego znaku spacji w strumieniu wejściowym.
Przykład #1 fscanf() Przykład
<?php
$uchwyt = fopen("users.txt", "r");
while ($userinfo = fscanf($uchwyt, "%s\t%s\t%s\n")) {
list ($name, $profession, $countrycode) = $userinfo;
//... zrób coś z wartościami
}
fclose($uchwyt);
?>
Przykład #2 Zawartość pliku users.txt
javier argonaut pe hiroshi sculptor jp robert slacker us luigi florist it
Informacja: Przed PHP 4.3.0, maksymalną liczbą znaków czytanych z pliku było 512 (lub do pierwszego wystąpienia \n, cokolwiek nastąpiło pierwsze). Od PHP 4.3.0 dowolnie długie linie są czytane i skanowane.
Patrz także: fread(), fgets(), fgetss(), sscanf(), printf() i sprintf().
fseek
(PHP 4, PHP 5)
fseek — Seeks on a file pointer
Opis
$handle
, int $offset
[, int $whence = SEEK_SET
] )
Sets the file position indicator for the file referenced by
handle. The new position, measured in bytes
from the beginning of the file, is obtained by adding
offset to the position specified by
whence.
In general, it is allowed to seek past the end-of-file; if data is then written, reads in any unwritten region between the end-of-file and the sought position will yield bytes with value 0. However, certain streams may not support this behavior, especially when they have an underlying fixed size storage.
Parametry
-
handle -
Wskaźnik do systemu plików typu resource jest zazwyczaj tworzony poprzez funkcję fopen().
-
offset -
The offset.
To move to a position before the end-of-file, you need to pass a negative value in
offsetand setwhencetoSEEK_END. -
whence -
whencevalues are:SEEK_SET- Set position equal tooffsetbytes.SEEK_CUR- Set position to current location plusoffset.SEEK_END- Set position to end-of-file plusoffset.
Zwracane wartości
Upon success, returns 0; otherwise, returns -1.
Przykłady
Przykład #1 fseek() example
<?php
$fp = fopen('somefile.txt', 'r');
// read some data
$data = fgets($fp, 4096);
// move back to the beginning of the file
// same as rewind($fp);
fseek($fp, 0);
?>
Notatki
Informacja:
If you have opened the file in append (a or a+) mode, any data you write to the file will always be appended, regardless of the file position, and the result of calling fseek() will be undefined.
Informacja:
Not all streams support seeking. For those that do not support seeking, forward seeking from the current position is accomplished by reading and discarding data; other forms of seeking will fail.
fstat
(PHP 4, PHP 5)
fstat — Pobiera informacje o pliku używając otwartego wskaźnika pliku
Opis
$uchwyt
)
Zbiera statystyki otwartego pliku przez wskaźnik pliku uchwyt.
Ta funkcja jest podobna do funkcji
stat() z wyjątkiem tego, że operuje na otwartym
wskaźniku pliku zamiast na nazwię pliku.
Zwraca tablicę ze statystykami pliku; format tablicy szczegółowo jest opisany na stronie stat() podręcznika.
Przykład #1 fstat() przykład
<?php
// otwarcie pliku
$fp = fopen("/etc/passwd", "r");
// zebranie statystyk
$fstat = fstat($fp);
// zamknięcie pliku
fclose($fp);
// wyświetlenie tylko części asocjacyjnej
print_r(array_slice($fstat, 13));
?>
Powyższy przykład wyświetli coś podobnego do:
Array ( [dev] => 771 [ino] => 488704 [mode] => 33188 [nlink] => 1 [uid] => 0 [gid] => 0 [rdev] => 0 [size] => 1114 [atime] => 1061067181 [mtime] => 1056136526 [ctime] => 1056136526 [blksize] => 4096 [blocks] => 8 )
Informacja: Ta funkcja nie będzie działać na zdalnych plikach, ponieważ przetwarzany plik musi być dostępny w systemie plików serwera.
ftell
(PHP 4, PHP 5)
ftell — Mówi o pozycji odczyt/zapis wskaźnika pliku
Opis
$uchwyt
)
Zwraca pozycję wskaźnika pliku wskazywanego przez uchwyt; np.
jego ofset w strumieniu pliku.
W przypadku błędu, zwraca FALSE.
Wskaźnik pliku musi być prawidłowy i musi wskazywać na poprawnie otworzony plik przez fopen() lub popen(). ftell() zwraca niezdefiniowane wyniki dla strumieni tylko do dopisywania (otwartych z flagą "a").
Przykład #1 ftell() przykład
<?php
// otwarcie pliku i odczytanie jakiś danych
$fp = fopen("/etc/passwd", "r");
$data = fgets($fp, 12);
// gdzie jesteśmy ?
echo ftell($fp); // 11
fclose($fp);
?>
ftruncate
(PHP 4, PHP 5)
ftruncate — Przycina plik do podanej długości
Opis
$uchwyt
, int $rozmiar
)
Pobiera wskaźnik pliku, uchwyt i przycina plik do długości,
rozmiar.
Parametry
-
uchwyt -
Wskaźnik pliku
Informacja:
uchwytmusi by otworzony do zapisu. -
rozmiar -
Rozmiar do którego przycinamy.
Informacja:
Jeśli
rozmiarjest większy niż rozmiar pliku to jest on rozszerzany bajtami null.Jeśli
rozmiarjest mniejszy niż rozmiar pliku to dalsze dane zostaną stracone.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Rejestr zmian
| Wersja | Opis |
|---|---|
| PHP 4.3.3 |
Przed tym wydaniem ftruncate() zwracała
integer o wartości 1 w przypadku sukcesu, zamiast
boolean TRUE.
|
Notatki
Informacja:
Wskaźnik pliku jest nie modyfikowany.
fwrite
(PHP 4, PHP 5)
fwrite — Zapis pliku binarnie bezpieczny
Opis
$uchwyt
, string $łańcuch
[, int $długość
] )
fwrite() zapisuje treść
łańcuch do strumienia pliku wskazanego przez
uchwyt.
Parametry
-
uchwyt -
Wskaźnik do systemu plików typu resource jest zazwyczaj tworzony poprzez funkcję fopen().
-
łańcuch -
Łańcuch znaków, który ma być zapisany.
-
długość -
Jeśli podany jest argument
długość, zapisywanie zakończy się po zapisaniudługościbajtów lub gdy osiagnięty zostanie koniecłańcucha, cokolwiek zdarzy się pierwsze.Zauważ, że jeśli argument
długośćzosta podany, to konfiguracja magic_quotes_runtime zostaje zignorowana i żadne slashe nie zostaną usunięte złańcucha.
Zwracane wartości
fwrite() zwraca liczbę zapisanych bajtów
lub FALSE w przypadku błędu.
Notatki
Informacja:
W systemach, które rozróżniają pliki na binarne i tekstowe (np. Windows) plik musi zostać otworzony z 'b' włączonym do parametru tryb funkcji fopen().
Informacja:
Jeśli
uchwytzostał utworzony za pomocą fopen() w trybie dopisywania, zapis do pliku jest niepodzielny (chyba, że rozmiarłańcucha przekracza blok systemu plików, na niektórych platformach, przy założeniu, że plik jest na lokalnym systemie plików). Jeśli tak, to nie ma potrzeby flock()owanie zasobu przed wywołaniem fwrite(); wszystkie dane zostaną zapisane bez przerywania.
Informacja:
Jeśli, zapiszemy dwukrotnie do wskaźnika pliku, dane zostaną dołączone na koncu treści pliku, oznacza to, że poniższy przykład nie zadziała jak się tego spodziewamy.
<?php
$fp = fopen('data.txt', 'w');
fwrite($fp, '1');
fwrite($fp, '23');
fclose($fp);
// plik 'data.txt' ma treść 123, a nie 23!
?>
Przykłady
Przykład #1 Prosty przykład fwrite()
<?php
$nazwapliku = 'test.txt';
$trochetresci = "Dodaj to do pliku\n";
// Najpierw przekonaj się czy plik istnieje i jest zapisywalny.
if (is_writable($nazwapliku)) {
// W naszym przykładzie otwieramy $nazwapliku w trybie dopisywania.
// Wskaźnik pliku jest ustawiony na końcu pliku gdzie znajdzie
// się zawartość $trochetresci po wykonaniu fwrite().
if (!$uchwyt = fopen($nazwapliku, 'a')) {
echo "Nie mogę otworzyć pliku ($nazwapliku)";
exit;
}
// Zapis $trochetresci do naszego otwartego pliku.
if (fwrite($uchwyt, $trochetresci) === FALSE) {
echo "Nie mogę zapisać do pliku ($nazwapliku)";
exit;
}
echo "Sukces, zapisano ($trochetresci) do pliku ($nazwapliku)";
fclose($uchwyt);
} else {
echo "Plik $nazwapliku nie jest zapisywalny";
}
?>
Zobacz też:
- fread() - Odczyt pliku binarnie bezpieczy
- fopen() - Otwiera plik lub URL
- fsockopen() - Open Internet or Unix domain socket connection
- popen() - Otwiera wskaźnik pliku do procesu
- file_get_contents() - Reads entire file into a string
glob
(PHP 4 >= 4.3.0, PHP 5)
glob — Find pathnames matching a pattern
Opis
$pattern
[, int $flags = 0
] )
The glob() function searches for all the pathnames
matching pattern according to the rules used by
the libc glob() function, which is similar to the rules used by common
shells.
Parametry
-
pattern -
The pattern. No tilde expansion or parameter substitution is done.
-
flags -
Valid flags:
-
GLOB_MARK- Adds a slash to each directory returned -
GLOB_NOSORT- Return files as they appear in the directory (no sorting) -
GLOB_NOCHECK- Return the search pattern if no files matching it were found -
GLOB_NOESCAPE- Backslashes do not quote metacharacters -
GLOB_BRACE- Expands {a,b,c} to match 'a', 'b', or 'c' -
GLOB_ONLYDIR- Return only directory entries which match the pattern -
GLOB_ERR- Stop on read errors (like unreadable directories), by default errors are ignored.
-
Zwracane wartości
Returns an array containing the matched files/directories, an empty array
if no file matched or FALSE on error.
Informacja:
On some systems it is impossible to distinguish between empty match and an error.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.1.0 |
GLOB_ERR was added
|
| 4.3.3 |
GLOB_ONLYDIR became available on Windows and
other systems not using the GNU C library
|
Przykłady
Przykład #1 Convenient way how glob() can replace opendir() and friends.
<?php
foreach (glob("*.txt") as $filename) {
echo "$filename size " . filesize($filename) . "\n";
}
?>
Powyższy przykład wyświetli coś podobnego do:
funclist.txt size 44686 funcsummary.txt size 267625 quickref.txt size 137820
Notatki
Informacja: Ta funkcja nie będzie działać na zdalnych plikach, ponieważ przetwarzany plik musi być dostępny w systemie plików serwera.
Informacja: This function isn't available on some systems (e.g. old Sun OS).
Informacja: The
GLOB_BRACEflag is not available on some non GNU systems, like Solaris.
Zobacz też:
- opendir() - Otwiera katalog
- readdir() - Czyta zawartość katalogu
- closedir() - Zamyka wskaźnik katalogu
- fnmatch() - Match filename against a pattern
is_dir
(PHP 4, PHP 5)
is_dir — Mówi czy nazwa_pliku jest katalogiem
Opis
$nazwa_pliku
)Mówi czy nazwa_pliku jest katalogiem.
Parametry
-
nazwa_pliku -
Ścieżka do pliku. Jeśli
nazwa_plikujest względną nazwą pliku, to zostanie sprawdzona względnie do bieżącego katalogu roboczego. Jeślinazwa_plikujest symbolicznym lub twardym dowiązaniem wtedy link zostanie rozwiązany i sprawdzony. Jeśli masz włączone tryb bezpieczny lub open_basedir dodatkowe ograniczenia mogą mieć zastosowanie.
Zwracane wartości
Zwraca TRUE jeśli nazwa pliku istnieje i jest katalogiem, w przeciwnym
razie FALSE
Przykłady
Przykład #1 is_dir() przykład
<?php
var_dump(is_dir('plik.txt'));
var_dump(is_dir('nieistniejacy_katalog/abc'));
var_dump(is_dir('..')); //jeden katalog wyżej
?>
Powyższy przykład wyświetli:
bool(false) bool(false) bool(true)
Błędy/Wyjątki
W przypadku niepowodzenia jest emitowany E_WARNING.
Notatki
Informacja: Wyniki działania tej funkcji są buforowane. Zobacz opis funkcji clearstatcache() aby uzyskać więcej informacji.
Od PHP 5.0.0 ta funkcja może być użyta także z niektórymi nakładkami URL. Zobacz Supported Protocols and Wrappers aby uzyskać listę nakładek, które obsługują funkcjonalność z rodziny stat().
is_executable
(PHP 4, PHP 5)
is_executable — Mówi czy plik jest wykonywalny
Opis
$nazwa_pliku
)
Zwraca TRUE jeśli plik istnieje i jest wykonywalny.
is_executable() w Windows jest dostępna w wersji PHP 5.0.0.
Przykład #1 is_executable() przykład
<?php
$file = '/home/vincent/somefile.sh';
if (is_executable($file)) {
echo $file.' jest wykonywalny';
} else {
echo $file.' nie jest wykonywalny';
}
?>
Informacja: Wyniki działania tej funkcji są buforowane. Zobacz opis funkcji clearstatcache() aby uzyskać więcej informacji.
Od PHP 5.0.0 ta funkcja może być użyta także z niektórymi nakładkami URL. Zobacz Supported Protocols and Wrappers aby uzyskać listę nakładek, które obsługują funkcjonalność z rodziny stat().
is_file
(PHP 4, PHP 5)
is_file — Mówi czy nazwa_pliku jest zwykłym plikiem
Opis
$nazwa_pliku
)
Zwraca TRUE jesli nazwa_pliku istnieje i jest zwykłym plikiem.
Przykład #1 is_file() przykład
<?php
var_dump(is_file('plik.txt')) . "\n";
var_dump(is_file('/usr/bin/')) . "\n";
?>
Powyższy przykład wyświetli:
bool(true) bool(false)
Informacja: Wyniki działania tej funkcji są buforowane. Zobacz opis funkcji clearstatcache() aby uzyskać więcej informacji.
Od PHP 5.0.0 ta funkcja może być użyta także z niektórymi nakładkami URL. Zobacz Supported Protocols and Wrappers aby uzyskać listę nakładek, które obsługują funkcjonalność z rodziny stat().
is_link
(PHP 4, PHP 5)
is_link — Mówi czy nazwa_pliku jest dowiązaniem symbolicznym
Opis
$nazwa_pliku
)
Zwraca TRUE jeśli nazwa_pliku istnieje i jest dowiązaniem symbolicznym.
Informacja: Wyniki działania tej funkcji są buforowane. Zobacz opis funkcji clearstatcache() aby uzyskać więcej informacji.
Od PHP 5.0.0 ta funkcja może być użyta także z niektórymi nakładkami URL. Zobacz Supported Protocols and Wrappers aby uzyskać listę nakładek, które obsługują funkcjonalność z rodziny stat().
Patrz także: is_dir(), is_file() i readlink().
is_readable
(PHP 4, PHP 5)
is_readable — Tells whether a file exists and is readable
Opis
$filename
)Tells whether a file exists and is readable.
Parametry
-
filename -
Path to the file.
Zwracane wartości
Returns TRUE if the file or directory specified by
filename exists and is readable, FALSE otherwise.
Przykłady
Przykład #1 is_readable() example
<?php
$filename = 'test.txt';
if (is_readable($filename)) {
echo 'The file is readable';
} else {
echo 'The file is not readable';
}
?>
Błędy/Wyjątki
W przypadku niepowodzenia jest emitowany E_WARNING.
Notatki
Keep in mind that PHP may be accessing the file as the user id that the web server runs as (often 'nobody'). Safe mode limitations are not taken into account before PHP 5.1.5.
Informacja: Wyniki działania tej funkcji są buforowane. Zobacz opis funkcji clearstatcache() aby uzyskać więcej informacji.
Od PHP 5.0.0 ta funkcja może być użyta także z niektórymi nakładkami URL. Zobacz Supported Protocols and Wrappers aby uzyskać listę nakładek, które obsługują funkcjonalność z rodziny stat().
Informacja:
The check is done using the real UID/GID instead of the effective one.
Zobacz też:
- is_writable() - Tells whether the filename is writable
- file_exists() - Sprawdza czy plik lub katalog istnieje
- fgets() - Pobiera linię ze wskaźnika pliku
is_uploaded_file
(PHP 4 >= 4.0.3, PHP 5)
is_uploaded_file — Mówi czy plik został przysłany przez HTTP POST.
Opis
$nazwa_pliku
)
Zwraca TRUE jeśli plik o nazwie nazwa_pliku
został przysłany (upload) przez HTTP POST. To pomaga upewnić się,
czy złośliwy użytkownik nie próbuje oszukać skryptu pracującego
na plikach, tak aby działał on na plikach na których nie powinien
-- na przykład
/etc/passwd.
Ten rodzaj testów jest szczególnie ważny jeśli istnieje szansa, że cokolwiek robimy z przysłanymi plikami może zdradzić ich treść użytkownikowi lub nawet innym użytkownikom tego samego systemu.
Do prawidłowego działania, funkcja is_uploaded_file() wymaga argumentu jak $_FILES['userfile']['tmp_name'], - nazwa przysyłanego pliku na maszynie klienta $_FILES['userfile']['name'] nie zadziała.
Przykład #1 is_uploaded_file() przykład
<?php
if (is_uploaded_file($_FILES['userfile']['tmp_name'])) {
echo "File ". $_FILES['userfile']['name'] ." upload prawidłowy.\n";
echo "Wyświetlam treść\n";
readfile($_FILES['userfile']['tmp_name']);
} else {
echo "Możliwy atak przez uploadowanie pliku: ";
echo "Plik '". $_FILES['userfile']['tmp_name'] . "'.";
}
?>
is_uploaded_file() jest dostępna tylko w wersjach PHP 3 późniejszych od PHP 3.0.16, i wersjach PHP 4 późniejszych od 4.0.2. Jeśli utknołeś przy używaniu wcześniejszej wersji, możesz użyć poniższej funkcji w celu pomocy w zabezpieczeniu siebie:
Informacja:
Poniższy przykład nie zadziała w wersjach PHP 4 późniejszych od 4.0.2. To jest spowodowane zmianą wewnętrznej funkcjonalności PHP po tej wersji.
Przykład #2 is_uploaded_file() przykład dla PHP 4 < 4.0.3
<?php
/* Test po stronie użytkownika na uploadowany plik */
function is_uploaded_file_4_0_2($filename)
{
if (!$tmp_file = get_cfg_var('upload_tmp_dir')) {
$tmp_file = dirname(tempnam('', ''));
}
$tmp_file .= '/' . basename($filename);
/* Użytkownik może mieć zamykający ukośnik w php.ini... */
return (ereg_replace('/+', '/', $tmp_file) == $filename);
}
/* Jak użyć tej funkcji, w starych wersjach nie masz także
* move_uploaded_file(): */
if (is_uploaded_file_4_0_2($HTTP_POST_FILES['userfile'])) {
copy($HTTP_POST_FILES['userfile'], "/place/to/put/uploaded/file");
} else {
echo "Prawdopodobny atak przez uploadowanie pliku: '$HTTP_POST_FILES[userfile]'.";
}
?>
Patrz także: move_uploaded_file() i rozdział Obsługa uploadowanych plików w celu uzyskania prostych przykładów użycia tej funkcji.
is_writable
(PHP 4, PHP 5)
is_writable — Tells whether the filename is writable
Opis
$filename
)
Returns TRUE if the filename exists and is
writable. The filename argument may be a directory name allowing you
to check if a directory is writable.
Keep in mind that PHP may be accessing the file as the user id that the web server runs as (often 'nobody'). Safe mode limitations are not taken into account.
Parametry
-
filename -
The filename being checked.
Zwracane wartości
Returns TRUE if the filename exists and is
writable.
Przykłady
Przykład #1 is_writable() example
<?php
$filename = 'test.txt';
if (is_writable($filename)) {
echo 'The file is writable';
} else {
echo 'The file is not writable';
}
?>
Błędy/Wyjątki
W przypadku niepowodzenia jest emitowany E_WARNING.
Notatki
Informacja: Wyniki działania tej funkcji są buforowane. Zobacz opis funkcji clearstatcache() aby uzyskać więcej informacji.
Od PHP 5.0.0 ta funkcja może być użyta także z niektórymi nakładkami URL. Zobacz Supported Protocols and Wrappers aby uzyskać listę nakładek, które obsługują funkcjonalność z rodziny stat().
Zobacz też:
- is_readable() - Tells whether a file exists and is readable
- file_exists() - Sprawdza czy plik lub katalog istnieje
- fwrite() - Zapis pliku binarnie bezpieczny
Opis
Ta funkcja jest aliasem dla: is_writable().
lchgrp
(PHP 5 >= 5.1.2)
lchgrp — Changes group ownership of symlink
Opis
Attempts to change the group of the symlink filename
to group.
Only the superuser may change the group of a symlink arbitrarily; other users may change the group of a symlink to any group of which that user is a member.
Parametry
-
filename -
Path to the symlink.
-
group -
The group specified by name or number.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Changing the group of a symbolic link
<?php
$target = 'output.php';
$link = 'output.html';
symlink($target, $link);
lchgrp($link, 8);
?>
Notatki
Informacja: Ta funkcja nie będzie działać na zdalnych plikach, ponieważ przetwarzany plik musi być dostępny w systemie plików serwera.
Informacja: Gdy włączony jest tryb bezpieczny, PHP sprawdza, czy pliki lub katalogi, na których zostaną wykonane operacje mają takie same UID (owner) jak skrypt, który jest aktualnie wykonywany.
Informacja: Ta funkcja nie jest dostępna na platformie Windows.
lchown
(PHP 5 >= 5.1.2)
lchown — Changes user ownership of symlink
Opis
Attempts to change the owner of the symlink filename
to user user.
Only the superuser may change the owner of a symlink.
Parametry
-
filename -
Path to the file.
-
user -
User name or number.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Changing the owner of a symbolic link
<?php
$target = 'output.php';
$link = 'output.html';
symlink($target, $link);
lchown($link, 8);
?>
Notatki
Informacja: Ta funkcja nie będzie działać na zdalnych plikach, ponieważ przetwarzany plik musi być dostępny w systemie plików serwera.
Informacja: Gdy włączony jest tryb bezpieczny, PHP sprawdza, czy pliki lub katalogi, na których zostaną wykonane operacje mają takie same UID (owner) jak skrypt, który jest aktualnie wykonywany.
Informacja: Ta funkcja nie jest dostępna na platformie Windows.
link
(PHP 4, PHP 5)
link — Tworzy dowiązanie twarde
Opis
$cel
, string $link
)
link() tworzy dowiązanie twarde. Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Informacja: Ta funkcja nie będzie działać na zdalnych plikach, ponieważ przetwarzany plik musi być dostępny w systemie plików serwera.
Informacja: Ta funkcja nie jest dostępna na platformie Windows.
Patrz także: symlink() do tworzenia dowiązań symbolicznych, i readlink() w powiązaniu z linkinfo().
linkinfo
(PHP 4, PHP 5)
linkinfo — Pobiera informacje o linku
Opis
$ścieżka
)
linkinfo() zwraca pole st_dev o strukturze
unix'owej funkcji (języka C) stat, pole zwracane jest poprzez wywołanie systemowe lstat.
Ta funkcja używana jest do weryfikacji czy link (wskazywany przez
ścieżkę) naprawdę istnieje (używana jest ta sama metoda
co w makrze S_ISLNK zdefiniowanym w stat.h). Zwraca 0 lub FALSE w przypadku
błędu.
Przykład #1 przykład linkinfo()
<?php
echo linkinfo('/vmlinuz'); // 835
?>
Informacja: Ta funkcja nie jest dostępna na platformie Windows.
Patrz także: symlink(), link() i readlink().
lstat
(PHP 4, PHP 5)
lstat — Podaje informacje o pliku lub dowiązaniu symbolicznym
Opis
$nazwa_pliku
)
Zbiera statystyki pliku lub dowiązania symbolicznego nazwanego przez
nazwę_pliku. Ta funkcja jest identyczna do funkcji
stat() z wyjątkiem tego, że jeśli parametr
nazwa_pliku jest dowiązaniem symbolicznym,
zwracany jest status dowiązania symbolicznego, a nie status pliku
na które ono wskazuje.
Zobacz stronę podręcznika dla stat() w którym znajdują się informacje na temat struktury tablicy jaką lstat() zwraca.
Informacja: Wyniki działania tej funkcji są buforowane. Zobacz opis funkcji clearstatcache() aby uzyskać więcej informacji.
Od PHP 5.0.0 ta funkcja może być użyta także z niektórymi nakładkami URL. Zobacz Supported Protocols and Wrappers aby uzyskać listę nakładek, które obsługują funkcjonalność z rodziny stat().
Patrz także: stat().
mkdir
(PHP 4, PHP 5)
mkdir — Tworzy katalog
Opis
$nazwa_ścieżki
[, int $prawa dostępu
[, bool $rekursywność
[, resource $kontekst
]]] )Tworzy katalog podany w nazwa_ścieżki.
Uwaga: Prawdopodobnie chciałbyś podać prawa dostępu jako wartość oktalną (ósemkową), co oznacza że powinieneś poprzedzić je zerem. Prawa dostępu mogą być także modyfikowane przez bieżący umask, który możesz zmienić używając umask().
Informacja:
Prawa dostępu sa ignorowane w Windows, i stały się opcjonalne w PHP 4.2.0.
Domyslnie prawa dostępu to 0777, co oznacza najbardziej otwarty dostęp. Po więcej informacji na temat praw dostępu, przeczytaj na stronie chmod().
Przykład #1 mkdir() przykład
<?php
mkdir ("/path/to/my/dir", 0700);
?>
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Informacja: Od PHP 5.0.0 mkdir() może być użyta z niektórymi wrapperami URL. Zajrzyj do Supported Protocols and Wrappers aby uzyskać listę wrapperów, które wspierają mkdir().
Informacja: Obsługa kontekstów została dodana w PHP 5.0.0. Opis kontekstów znajduje się w rozdziale Stream Funkcje.
Informacja: Parametr
rekursywnośćzostał dodany w PHP 5.0.0.
Informacja: Gdy włączony jest tryb bezpieczny, PHP sprawdza czy katalog, na którym zostaną wykonane operacje, ma takie same UID (owner) jak skrypt, który jest aktualnie wykonywany.
Patrz także: rmdir().
move_uploaded_file
(PHP 4 >= 4.0.3, PHP 5)
move_uploaded_file — Przenieś uploadowany plik do innej lokalizacji
Opis
$nazwa_pliku
, string $przeznaczenie
)
Funkcja ta sprawdza czy na pewno plik określony przez
nazwa_pliku jest prawidło uploadowanym plikiem
(to znaczy, że został uploadowany przez PHPowy mechanizm uploadowania HTTP
POST). Jeśli plik jest prawidłowy, to zostanie przeniesiony do nazwy pliku
wskazanej przez przeznaczenie.
Ten rodzaj testów jest szczególnie ważny jeśli istnieje szansa, że cokolwiek robimy z przysłanymi plikami może zdradzić ich treść użytkownikowi lub nawet innym użytkownikom tego samego systemu.
Parametry
-
nazwa_pliku -
Nazwa wgrywanego pliku.
-
przeznaczenie -
Miejsce docelowe przenoszonego pliku.
Zwracane wartości
Jeśli nazwa_pliku nie jest prawidło uploadowanym plikiem,
to żadna akcja nie zostanie wykonana i move_uploaded_file()
zwróci FALSE.
Jeśli nazwa_pliku jest prawidłowo uploadowanym plikiem,
ale nie może zostać przeniesiony z jakiś powodów, żadna akcja nie zostanie wykonana
i move_uploaded_file() zwróci FALSE.
Dodatkowo, zostanie pokazane ostrzeżenie.
Notatki
Informacja:
Funkcja move_uploaded_file() jest świadoma tryb bezpieczny oraz open_basedir. Jednak, ograniczenia nałożone są tylko na ścieżkę
przeznaczenie, ponieważ pozwala na przenoszenie uploadowanych plików w którychnazwa_plikumoże kolidować z takimi ograniczeniami. move_uploaded_file() zapewnia bezpieczeństwo tej operacji poprzez zezwolenie na przeniesienie tylko tych plików, które były uploadowane przez PHP.
Jeśli już istnieje plik docelowy, to zostanie on nadpisany.
Zobacz też:
- is_uploaded_file() - Mówi czy plik został przysłany przez HTTP POST.
- Zobacz Obsługa uploadowanych plików w celu uzyskania prostych przykładów użycia tej funkcji.
parse_ini_file
(PHP 4, PHP 5)
parse_ini_file — Parse a configuration file
Opis
$filename
[, bool $process_sections = false
[, int $scanner_mode = INI_SCANNER_NORMAL
]] )
parse_ini_file() loads in the
ini file specified in filename,
and returns the settings in it in an associative array.
The structure of the ini file is the same as the php.ini's.
Parametry
-
filename -
The filename of the ini file being parsed.
-
process_sections -
By setting the
process_sectionsparameter toTRUE, you get a multidimensional array, with the section names and settings included. The default forprocess_sectionsisFALSE -
scanner_mode -
Can either be
INI_SCANNER_NORMAL(default) orINI_SCANNER_RAW. IfINI_SCANNER_RAWis supplied, then option values will not be parsed.
Zwracane wartości
The settings are returned as an associative array on success,
and FALSE on failure.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.0 |
Added optional scanner_mode parameter.
Single quotes may now be used around variable assignments.
Hash marks (#) may no longer be used as comments
and will throw a deprecation warning if used.
|
| 5.2.7 |
On syntax error this function will return FALSE rather than an empty
array.
|
| 5.2.4 | Keys and section names consisting of numbers are now evaluated as PHP integers thus numbers starting by 0 are evaluated as octals and numbers starting by 0x are evaluated as hexadecimals. |
| 5.0.0 | Values enclosed in double quotes can contain new lines. |
| 4.2.1 | This function is now affected by tryb bezpieczny and open_basedir. |
Przykłady
Przykład #1 Contents of sample.ini
; This is a sample configuration file ; Comments start with ';', as in php.ini [first_section] one = 1 five = 5 animal = BIRD [second_section] path = "/usr/local/bin" URL = "http://www.example.com/~username" [third_section] phpversion[] = "5.0" phpversion[] = "5.1" phpversion[] = "5.2" phpversion[] = "5.3"
Przykład #2 parse_ini_file() example
Constants may also be parsed in the ini file so if you define a constant as an ini value before running parse_ini_file(), it will be integrated into the results. Only ini values are evaluated. For example:
<?php
define('BIRD', 'Dodo bird');
// Parse without sections
$ini_array = parse_ini_file("sample.ini");
print_r($ini_array);
// Parse with sections
$ini_array = parse_ini_file("sample.ini", true);
print_r($ini_array);
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[one] => 1
[five] => 5
[animal] => Dodo bird
[path] => /usr/local/bin
[URL] => http://www.example.com/~username
[phpversion] => Array
(
[0] => 5.0
[1] => 5.1
[2] => 5.2
[3] => 5.3
)
)
Array
(
[first_section] => Array
(
[one] => 1
[five] => 5
[animal] => Dodo bird
)
[second_section] => Array
(
[path] => /usr/local/bin
[URL] => http://www.example.com/~username
)
[third_section] => Array
(
[phpversion] => Array
(
[0] => 5.0
[1] => 5.1
[2] => 5.2
[3] => 5.3
)
)
)
Przykład #3 parse_ini_file() parsing a php.ini file
<?php
// A simple function used for comparing the results below
function yesno($expression)
{
return($expression ? 'Yes' : 'No');
}
// Get the path to php.ini using the php_ini_loaded_file()
// function available as of PHP 5.2.4
$ini_path = php_ini_loaded_file();
// Parse php.ini
$ini = parse_ini_file($ini_path);
// Print and compare the values, note that using get_cfg_var()
// will give the same results for parsed and loaded here
echo '(parsed) magic_quotes_gpc = ' . yesno($ini['magic_quotes_gpc']) . PHP_EOL;
echo '(loaded) magic_quotes_gpc = ' . yesno(get_cfg_var('magic_quotes_gpc')) . PHP_EOL;
?>
Powyższy przykład wyświetli coś podobnego do:
(parsed) magic_quotes_gpc = Yes (loaded) magic_quotes_gpc = Yes
Notatki
Informacja:
This function has nothing to do with the php.ini file. It is already processed by the time you run your script. This function can be used to read in your own application's configuration files.
Informacja:
If a value in the ini file contains any non-alphanumeric characters it needs to be enclosed in double-quotes (").
Informacja: There are reserved words which must not be used as keys for ini files. These include: null, yes, no, true, false, on, off, none. Values null, no and false results in "", yes and true results in "1". Characters ?{}|&~![()^" must not be used anywhere in the key and have a special meaning in the value.
parse_ini_string
(PHP 5 >= 5.3.0)
parse_ini_string — Parse a configuration string
Opis
$ini
[, bool $process_sections = false
[, int $scanner_mode = INI_SCANNER_NORMAL
]] )
parse_ini_string() returns the settings in string
ini in an associative array.
The structure of the ini string is the same as the php.ini's.
Parametry
-
ini -
The contents of the ini file being parsed.
-
process_sections -
By setting the
process_sectionsparameter toTRUE, you get a multidimensional array, with the section names and settings included. The default forprocess_sectionsisFALSE -
scanner_mode -
Can either be
INI_SCANNER_NORMAL(default) orINI_SCANNER_RAW. IfINI_SCANNER_RAWis supplied, then option values will not be parsed.
Zwracane wartości
The settings are returned as an associative array on success,
and FALSE on failure.
Notatki
Informacja: There are reserved words which must not be used as keys for ini files. These include: null, yes, no, true, false, on, off, none. Values null, no and false results in "", yes and true results in "1". Characters ?{}|&~![()^" must not be used anywhere in the key and have a special meaning in the value.
pathinfo
(PHP 4 >= 4.0.3, PHP 5)
pathinfo — Zwraca informacje o ścieżce do pliku
Opis
$ścieżka
[, int $opcje = PATHINFO_DIRNAME | PATHINFO_BASENAME | PATHINFO_EXTENSION | PATHINFO_FILENAME
] )
pathinfo() zwraca asocjacyjną tablicę
zawierającą informacje o ścieżce.
Parametry
-
ścieżka -
Ścieżka która jest sprawdzana
-
opcje -
Możesz określić, który element zostanie zwrócony, za pomocą opcjonalnego parametru
opcje. Składajego się zPATHINFO_DIRNAME,PATHINFO_BASENAME,PATHINFO_EXTENSIONiPATHINFO_FILENAME. Domyślnie zwracane są wszystkie elementy.
Zwracane wartości
Zwracane są następujące elementy asocjacyjnej tablicy array: dirname, basename, extension (jeśli wystąpi) i filename.
Jeśli parametr opcje zostanie użyty, funkcja zwróci
string w przypadku gdy nie zarządano wszystkich elementów.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.2.0 |
Została dodana stała PATHINFO_FILENAME.
|
Przykłady
Przykład #1 Przykład pathinfo()
<?php
$path_parts = pathinfo('/www/htdocs/inc/lib.inc.php');
echo $path_parts['dirname'], "\n";
echo $path_parts['basename'], "\n";
echo $path_parts['extension'], "\n";
echo $path_parts['filename'], "\n"; // od PHP 5.2.0
?>
Powyższy przykład wyświetli:
/www/htdocs/inc lib.inc.php php lib.inc
Notatki
Informacja:
W celu uzyskania informacji jak pobrać bieżącą ścieżkę, przeczytaj rozdział predefiniowane zarezerwowane zmienne.
Zobacz też:
- dirname() - Zwraca nazwę katalogu, będącego składową ścieżki
- basename() - Zwraca nazwę pliku, będącego składową ścieżki
- parse_url() - Przetwarza adres URL i zwraca jego składowe
- realpath() - Returns canonicalized absolute pathname
pclose
(PHP 4, PHP 5)
pclose — Zamyka wskaźnik pliku do procesu
popen
(PHP 4, PHP 5)
popen — Otwiera wskaźnik pliku do procesu
Opis
$polecenie
, string $tryb
)Otwiera potok do procesu uruchomionego przez rozwidlenie polecenia (ang. forking) podanego w parametrze polecenie.
Zwraca wskaźnik pliku identyczny do tego zwracanego przez fopen() z wyjątkiem tego, że jest on jednokierunkowy (może być tylko użyty do odczytu lub zapisu) i musi być zamknięty za pomocą pclose(). Wskaźnik ten może być użyty z fgets(), fgetss() i fwrite().
W przypadku błędu, zwraca FALSE.
Informacja:
Jeśli szukasz dwukierunkowej obsługi (w obie strony), użyj proc_open().
Przykład #1 popen() przykład
<?php
$uchwyt = popen("/bin/ls", "r");
?>
Jeśli polecenie uruchamiane nie może zostać znalezione, poprawny zasób jest zwracany. To może wydawać się dziwne, ale ma sens; pozwala tobie na dostęp do wszystkich informacji o błędach zwracanych przez powłokę.
<?php
error_reporting(E_ALL);
/* Dodanie przekierowania, aby móc dostać stderr. */
$uchwyt = popen('/sciezka/do/czegos 2>&1', 'r');
echo "'$uchwyt'; " . gettype($uchwyt) . "\n";
$czytaj = fread($uchwyt, 2096);
echo $czytaj;
pclose($uchwyt);
?>
Informacja: Jeśli tryb bezpieczny został włączony, możliwe jest wykonywanie programów tylko z katalogu określonego przez safe_mode_exec_dir. Ze względów praktycznych, nie można podawać elementów .. w ścieżce do pliku wykonywalnego.
Jeśli włączony jest tryb bezpieczny, ciągi zawierające polecenia są filtrowane przez funkcję escapeshellcmd(). W związku z tym, echo y | echo x staje się echo y \| echo x.
Patrz także pclose(), fopen() i proc_open().
readfile
(PHP 4, PHP 5)
readfile — Wyświetla plik
Opis
$nazwapliku
[, bool $użyj_include_path
[, resource $context
]] )Odczytuje plik i zapisuje go do bufora wyjściowego.
Zwraca liczbę odczytanych bajtów z pliku, Jeśli nastąpił błą,
zwraca FALSE oraz wyświetlany jest komunikat błędu, chyba, żę
funkcja została wywołana jako @readfile().
Jeśli włączona jest dyrektywa konfiguracyjna fopen wrappers, możliwe jest podanie jako nazwy pliku adresu URL. Zobacz opis funkcji fopen() aby dowiedzieć się jak przekazać nazwę pliku, oraz fopen wrappers aby uzyskać listę obsługiwanych protokołów.
Można ustawić opcjonalny drugi parametr na TRUE jeśli
plik ma być poszukiwany także w include_path.
Informacja: Obsługa kontekstów została dodana w PHP 5.0.0. Opis kontekstów znajduje się w rozdziale Stream Funkcje.
Patrz także: fpassthru(), file(), fopen(), include(), require(), virtual(), file_get_contents() i Supported Protocols and Wrappers.
readlink
(PHP 4, PHP 5)
readlink — Zwraca cel linku symbolicznego
Opis
$ścieżka
)
readlink() jest tym samym co funkcja języka C readlink
i zwraca ścieżkę linku symbolicznego lub FALSE
w przypadku błędu.
Przykład #1 readlink() przykład
<?php
// wynik np. /boot/vmlinux-2.4.20-xfs
echo readlink('/vmlinuz');
?>
Informacja: Ta funkcja nie jest dostępna na platformie Windows.
Patrz takżę: is_link(), symlink() i linkinfo().
realpath_cache_get
(PHP 5 >= 5.3.2)
realpath_cache_get — Get realpath cache entries
Opis
Get the contents of the realpath cache.
Zwracane wartości
Returns an array of realpath cache entries. The keys are original path entries, and the values are arrays of data items, containing the resolved path, expiration date, and other options kept in the cache.
Przykłady
Przykład #1 realpath_cache_get() example
<?php
var_dump(realpath_cache_get());
?>
Powyższy przykład wyświetli coś podobnego do:
array(2) {
["/test"]=>
array(4) {
["key"]=>
int(123456789)
["is_dir"]=>
bool(true)
["realpath"]=>
string(5) "/test"
["expires"]=>
int(1260318939)
}
["/test/test.php"]=>
array(4) {
["key"]=>
int(987654321)
["is_dir"]=>
bool(false)
["realpath"]=>
string(12) "/root/test.php"
["expires"]=>
int(1260318939)
}
}
realpath_cache_size
(PHP 5 >= 5.3.2)
realpath_cache_size — Get realpath cache size
Opis
Get the amount of memory used by the realpath cache.
Zwracane wartości
Returns how much memory realpath cache is using.
Przykłady
Przykład #1 realpath_cache_size() example
<?php
var_dump(realpath_cache_size());
?>
Powyższy przykład wyświetli coś podobnego do:
int(412)
realpath
(PHP 4, PHP 5)
realpath — Returns canonicalized absolute pathname
Opis
$path
)
realpath() expands all symbolic links and
resolves references to '/./', '/../' and extra '/' characters in
the input path and return the canonicalized
absolute pathname.
Parametry
-
path -
The path being checked.
Informacja:
Whilst a path must be supplied, the value can be blank or
NULLIn these cases, the value is interpreted as the current directory.
Zwracane wartości
Returns the canonicalized absolute pathname on success. The resulting path will have no symbolic link, '/./' or '/../' components.
realpath() returns FALSE on failure, e.g. if
the file does not exist.
Informacja:
The running script must have executable permissions on all directories in the hierarchy, otherwise realpath() will return
FALSE.
Informacja: Because PHP's integer type is signed and many platforms use 32bit integers, some filesystem functions may return unexpected results for files which are larger than 2GB.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.0 |
Prior to this release, if only the last path
component did not exist, realpath() would not fail on
*BSD systems. realpath() now fails in this case.
|
| 5.0.0 |
Prior to this release, a blank or NULL path would
cause realpath() to return the directory name of the script.
|
Przykłady
Przykład #1 realpath() example
<?php
chdir('/var/www/');
echo realpath('./../../etc/passwd');
?>
Powyższy przykład wyświetli:
/etc/passwd
Przykład #2 realpath() on Windows
On windows realpath() will change unix style paths to windows style.
<?php
echo realpath('/windows/system32');
?>
Powyższy przykład wyświetli:
C:\WINDOWS\System32
Zobacz też:
- basename() - Zwraca nazwę pliku, będącego składową ścieżki
- dirname() - Zwraca nazwę katalogu, będącego składową ścieżki
- pathinfo() - Zwraca informacje o ścieżce do pliku
rename
(PHP 4, PHP 5)
rename — Renames a file or directory
Opis
$oldname
, string $newname
[, resource $context
] )
Attempts to rename oldname to
newname.
Parametry
-
oldname -
Informacja:
The old name. The wrapper used in
oldnamemust match the wrapper used innewname. -
newname -
The new name.
-
context -
Informacja: Obsługa kontekstów została dodana w PHP 5.0.0. Opis kontekstów znajduje się w rozdziale Stream Funkcje.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.1 | rename() can now rename files across drives in Windows. |
| 5.0.0 | rename() can now also be used with some URL wrappers. Refer to Supported Protocols and Wrappers for a listing of which wrappers support rename(). |
| 4.3.3 | rename() may now be able to rename files across partitions on *nix based systems, provided the appropriate permissions are held. Warnings may be generated if the destination filesystem doesn't permit chown() or chmod() system calls to be made on files — for example, if the destination filesystem is a FAT filesystem. |
Przykłady
Przykład #1 Example with rename()
<?php
rename("/tmp/tmp_file.txt", "/home/user/login/docs/my_file.txt");
?>
Zobacz też:
- copy() - Kopiuje plik
- unlink() - Kasowanie pliku
- move_uploaded_file() - Przenieś uploadowany plik do innej lokalizacji
rewind
(PHP 4, PHP 5)
rewind — Rewind the position of a file pointer
Opis
$handle
)
Sets the file position indicator for handle
to the beginning of the file stream.
Informacja:
If you have opened the file in append ("a" or "a+") mode, any data you write to the file will always be appended, regardless of the file position.
Parametry
-
handle -
The file pointer must be valid, and must point to a file successfully opened by fopen().
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 rewind() overwriting example
<?php
$handle = fopen('output.txt', 'r+');
fwrite($handle, 'Really long sentence.');
rewind($handle);
fwrite($handle, 'Foo');
rewind($handle);
echo fread($handle, filesize('output.txt'));
fclose($handle);
?>
Powyższy przykład wyświetli coś podobnego do:
Foolly long sentence.
rmdir
(PHP 4, PHP 5)
rmdir — Usuwanie katalogów
Opis
$nazwa_katalogu
[, resource $kontekst
] )
Próbuje usunąć katalog podany przez nazwa_katalogu.
Katalog musi byc pusty, i stosowne uprawnienia muszą na to pozwalać.
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Informacja: Od PHP 5.0.0 rmdir() może być również użyta z niektórymi wrapperami URL. Odwołaj się do Supported Protocols and Wrappers listy wrapperów, które wspierają rmdir().
Informacja: Obsługa kontekstów została dodana w PHP 5.0.0. Opis kontekstów znajduje się w rozdziale Stream Funkcje.
Informacja: Gdy włączony jest tryb bezpieczny, PHP sprawdza czy katalog, na którym zostaną wykonane operacje, ma takie same UID (owner) jak skrypt, który jest aktualnie wykonywany.
Opis
Ta funkcja jest aliasem dla: stream_set_write_buffer().
stat
(PHP 4, PHP 5)
stat — Gives information about a file
Opis
$filename
)
Gathers the statistics of the file named by
filename. If filename is a
symbolic link, statistics are from the file itself, not the symlink.
lstat() is identical to stat() except it would instead be based off the symlinks status.
Parametry
-
filename -
Path to the file.
Zwracane wartości
| Numeric | Associative (since PHP 4.0.6) | Description |
|---|---|---|
| 0 | dev | device number |
| 1 | ino | inode number * |
| 2 | mode | inode protection mode |
| 3 | nlink | number of links |
| 4 | uid | userid of owner * |
| 5 | gid | groupid of owner * |
| 6 | rdev | device type, if inode device |
| 7 | size | size in bytes |
| 8 | atime | time of last access (Unix timestamp) |
| 9 | mtime | time of last modification (Unix timestamp) |
| 10 | ctime | time of last inode change (Unix timestamp) |
| 11 | blksize | blocksize of filesystem IO ** |
| 12 | blocks | number of 512-byte blocks allocated ** |
** Only valid on systems supporting the st_blksize type - other systems (e.g. Windows) return -1.
In case of error, stat() returns FALSE.
Informacja: Because PHP's integer type is signed and many platforms use 32bit integers, some filesystem functions may return unexpected results for files which are larger than 2GB.
Błędy/Wyjątki
Upon failure, an E_WARNING is emitted.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.0.6 | In addition to returning these attributes in a numeric array, they can be accessed with associative indices, as noted next to each parameter |
Przykłady
Przykład #1 stat() example
<?php
/* Get file stat */
$stat = stat('C:\php\php.exe');
/*
* Print file access time, this is the same
* as calling fileatime()
*/
echo 'Access time: ' . $stat['atime'];
/*
* Print file modification time, this is the
* same as calling filemtime()
*/
echo 'Modification time: ' . $stat['mtime'];
/* Print the device number */
echo 'Device number: ' . $stat['dev'];
?>
Przykład #2 Using stat() information together with touch()
<?php
/* Get file stat */
$stat = stat('C:\php\php.exe');
/* Did we failed to get stat information? */
if (!$stat) {
echo 'stat() call failed...';
} else {
/*
* We want the access time to be 1 week
* after the current access time.
*/
$atime = $stat['atime'] + 604800;
/* Touch the file */
if (!touch('some_file.txt', time(), $atime)) {
echo 'Failed to touch file...';
} else {
echo 'touch() returned success...';
}
}
?>
Notatki
Informacja:
Proszę zauważyć, że informacja o czasie dostępu może się różnić w zależności od systemu plików.
Informacja: Wyniki działania tej funkcji są buforowane. Zobacz opis funkcji clearstatcache() aby uzyskać więcej informacji.
Od PHP 5.0.0 ta funkcja może być użyta także z niektórymi nakładkami URL. Zobacz Supported Protocols and Wrappers aby uzyskać listę nakładek, które obsługują funkcjonalność z rodziny stat().
Zobacz też:
- lstat() - Podaje informacje o pliku lub dowiązaniu symbolicznym
- fstat() - Pobiera informacje o pliku używając otwartego wskaźnika pliku
- filemtime() - Pobiera czas ostatniej modyfikacji pliku
- filegroup() - Pobiera grupę pliku
symlink
(PHP 4, PHP 5)
symlink — Tworzy dowiązanie symboliczne
Opis
$cel
, string $dowiązanie
)
symlink() tworzy dowiązanie symboliczne do
istniejącego celu z
podaną nazwą dowiązanie.
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Informacja: Ta funkcja nie jest dostępna na platformie Windows.
Patrz także link() aby stworzyć twarde dowiązanie, i readlink() w powiązaniu z linkinfo().
tempnam
(PHP 4, PHP 5)
tempnam — Create file with unique file name
Opis
$dir
, string $prefix
)Creates a file with a unique filename, with access permission set to 0600, in the specified directory. If the directory does not exist, tempnam() may generate a file in the system's temporary directory, and return the name of that.
Parametry
-
dir -
The directory where the temporary filename will be created.
-
prefix -
The prefix of the generated temporary filename.
Informacja: Windows uses only the first three characters of prefix.
Zwracane wartości
Returns the new temporary filename, or FALSE on
failure.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 4.0.6 |
Prior to PHP 4.0.6, the behaviour of the
tempnam() function was system dependent. On
Windows the TMP environment variable will override the
dir parameter, on Linux the TMPDIR
environment variable has precedence, while SVR4 will always use
your dir parameter if the directory it
points to exists. Consult your system documentation on the
tempnam(3) function if in doubt.
|
| 4.0.3 | This function's behavior changed in 4.0.3. The temporary file is also created to avoid a race condition where the file might appear in the filesystem between the time the string was generated and before the script gets around to creating the file. Note, that you need to remove the file in case you need it no more, it is not done automatically. |
Przykłady
Przykład #1 tempnam() example
<?php
$tmpfname = tempnam("/tmp", "FOO");
$handle = fopen($tmpfname, "w");
fwrite($handle, "writing to tempfile");
fclose($handle);
// do here something
unlink($tmpfname);
?>
Notatki
Informacja: If PHP cannot create a file in the specified
dirparameter, it falls back on the system default. On NTFS this also happens if the specifieddircontains more than 65534 files.
Zobacz też:
- tmpfile() - Tworzy plik tymczasowy
- sys_get_temp_dir() - Returns directory path used for temporary files
- unlink() - Kasowanie pliku
tmpfile
(PHP 4, PHP 5)
tmpfile — Tworzy plik tymczasowy
Opis
Tworzy plik tymczasowy o unikalnej nazwie i otwiera go w trybie do odczytu i zapisu (w+), zwraca uchwyt pliku, podobnie jak fopen(). Plik jest automatycznie kasowany przy zamykaniu (po użyciu fclose()), lub gdy skrypt się zakończy.
Jeśli chcesz uzyskać więcej szczegółów, zajrzyj do dokumentacji twojego systemu dotyczącej funkcji tmpfile(3), albo do pliku nagłówkowego stdio.h.
Przykład #1 tmpfile() przykład
<?php
$temp = tmpfile();
fwrite($temp, "zapisywanie do pliku tymczasowego");
fseek($temp, 0);
echo fread($temp, 1024);
fclose($temp); // to kasuje plik
?>
Powyższy przykład wyświetli:
zapisywanie do pliku tymczasowego
Patrz także: tempnam(), sys_get_temp_dir().
touch
(PHP 4, PHP 5)
touch — Ustawia czas modyfikacji pliku
Opis
$nazwa_pliku
[, int $czas = time()
[, int $dczas
]] )
Próbuje ustawić czas dostępu i modyfikacji pliku o nazwie
nazwa_pliku na wartość podaną przez
czas.
Zauważ, że czas dostępu jest zawsze modyfikowany, niezależnie od
ilości parametrów.
Jeśli plik nie istnieje, to zostanie utworzony.
Parametry
-
nazwa_pliku -
Nazwa pliku, który ma być zmodyfikowany.
-
czas -
Czas modyfikacji. Jeśli
czasnie został podany, zostanie użyty bieżący czas systemowy. -
dczas -
Jeśli podano, to czas dostępu do podanego pliku zostanie ustawiony na wartość
dczas. W przeciwnym wypadku zostanie ustawiony na wartość przekazaną w parametrzetime. Jeśli, żaden nie występuje, zostanie użyty bieżący czas.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.3.0 | Możliwa jest zmiana czasu modyfikacji katalogu pod Windows. |
Przykłady
Przykład #1 touch() przykład
<?php
if (touch($filename)) {
echo $filename . ' czas modyfikacji został zmieniony na bieżący czas';
} else {
echo 'Przykro mi ale Nie Mogę zmienić czasu modyfikacji pliku ' . $filename;
}
?>
Przykład #2 touch() użycie parametru czas
<?php
// To jest czas modyfikacji, ustawimy go na jedną godzinę wstecz.
$time = time() - 3600;
// Modyfikujemy czas pliku
if (!touch('jakis_plik.txt', $time)) {
echo 'Coś się nie udało...';
} else {
echo 'Czas modyfikacji pliku ustawiony';
}
?>
Notatki
Informacja:
Proszę zauważyć, że informacja o czasie dostępu może się różnić w zależności od systemu plików.
Przed wersją PHP 5.3.0 nie istniała mozliwość zmiany czasu modyfikacji katalogu za pomocą tej funkcji pod systemem Windows.
umask
(PHP 4, PHP 5)
umask — Changes the current umask
Opis
$mask
] )
umask() sets PHP's umask to
mask & 0777 and returns the old
umask. When PHP is being used as a server module, the umask
is restored when each request is finished.
Parametry
-
mask -
The new umask.
Zwracane wartości
umask() without arguments simply returns the current umask otherwise the old umask is returned.
Przykłady
Przykład #1 umask() example
<?php
$old = umask(0);
chmod("/path/some_dir/some_file.txt", 0755);
umask($old);
// Checking
if ($old != umask()) {
die('An error occured while changing back the umask');
}
?>
Notatki
Informacja:
Avoid using this function in multithreaded webservers. It is better to change the file permissions with chmod() after creating the file. Using umask() can lead to unexpected behavior of concurrently running scripts and the webserver itself because they all use the same umask.
unlink
(PHP 4, PHP 5)
unlink — Kasowanie pliku
Opis
$nazwa_pliku
[, resource $kontekst
] )
Kasuje nazwa_pliku. Podobnie do uniksowej funkcji C
unlink(). W przypadku porażki zostanie wygenerowany błąd na poziomie
E_WARNING.
Parametry
-
nazwa_pliku -
Ścieżka do pliku.
-
context -
Informacja: Obsługa kontekstów została dodana w PHP 5.0.0. Opis kontekstów znajduje się w rozdziale Stream Funkcje.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Rejestr zmian
| Wersja | Opis |
|---|---|
| 5.0.0 | Od PHP 5.0.0 unlink() może być również użyty z niektórymi osłonami (wrapperami) URL. Zajrzyj do Supported Protocols and Wrappers aby uzyskać listę wrapperów, które obsługuje unlink(). |
Przykłady
Przykład #1 Podstawowe użycie unlink()
<?php
$fh = fopen('test.html', 'a');
fwrite($fh, '<h1>Witaj Świecie!</h1>');
fclose($fh);
unlink('test.html');
?>
Spis treści
- basename — Zwraca nazwę pliku, będącego składową ścieżki
- chgrp — Zmienia grupę pliku
- chmod — Zmienia prawa dostępu do pliku
- chown — Zmienia właściciela pliku
- clearstatcache — Czyści bufor statusu pliku
- copy — Kopiuje plik
- delete — Zobacz unlink lub unset
- dirname — Zwraca nazwę katalogu, będącego składową ścieżki
- disk_free_space — Zwraca ilość wolnego miejsca w systemie plików lub partycji dysku
- disk_total_space — Zwraca całkowity rozmiar systemu plików lub partycji dysku
- diskfreespace — Alias dla disk_free_space
- fclose — Zamyka otwarty wskaźnik pliku
- feof — Sprawdza czy wskaźnik pliku jest na końcu pliku (EOF)
- fflush — Przekierowuje wyjście do pliku
- fgetc — Pobiera znak ze wskaźnika pliku
- fgetcsv — Pobiera linię ze wskanika pliku i przetwarza na pola CSV
- fgets — Pobiera linię ze wskaźnika pliku
- fgetss — Pobiera linię ze wskaźnika pliku i usuwa znaczniki HTML
- file_exists — Sprawdza czy plik lub katalog istnieje
- file_get_contents — Reads entire file into a string
- file_put_contents — Write a string to a file
- file — Czyta całą zawartość pliku do tablicy
- fileatime — Pobiera ostatni czas dostępu do pliku
- filectime — Pobiera i-węzłowy czas zmiany pliku
- filegroup — Pobiera grupę pliku
- fileinode — Pobiera i-węzeł pliku
- filemtime — Pobiera czas ostatniej modyfikacji pliku
- fileowner — Pobiera właściciela pliku
- fileperms — Pobiera prawa dostępu pliku
- filesize — Pobiera rozmiar pliku
- filetype — Pobiera typ pliku
- flock — Portable advisory file locking
- fnmatch — Match filename against a pattern
- fopen — Otwiera plik lub URL
- fpassthru — Output all remaining data on a file pointer
- fputcsv — Format line as CSV and write to file pointer
- fputs — Alias dla fwrite
- fread — Odczyt pliku binarnie bezpieczy
- fscanf — Przetwarza dane z pliku według formatu
- fseek — Seeks on a file pointer
- fstat — Pobiera informacje o pliku używając otwartego wskaźnika pliku
- ftell — Mówi o pozycji odczyt/zapis wskaźnika pliku
- ftruncate — Przycina plik do podanej długości
- fwrite — Zapis pliku binarnie bezpieczny
- glob — Find pathnames matching a pattern
- is_dir — Mówi czy nazwa_pliku jest katalogiem
- is_executable — Mówi czy plik jest wykonywalny
- is_file — Mówi czy nazwa_pliku jest zwykłym plikiem
- is_link — Mówi czy nazwa_pliku jest dowiązaniem symbolicznym
- is_readable — Tells whether a file exists and is readable
- is_uploaded_file — Mówi czy plik został przysłany przez HTTP POST.
- is_writable — Tells whether the filename is writable
- is_writeable — Alias dla is_writable
- lchgrp — Changes group ownership of symlink
- lchown — Changes user ownership of symlink
- link — Tworzy dowiązanie twarde
- linkinfo — Pobiera informacje o linku
- lstat — Podaje informacje o pliku lub dowiązaniu symbolicznym
- mkdir — Tworzy katalog
- move_uploaded_file — Przenieś uploadowany plik do innej lokalizacji
- parse_ini_file — Parse a configuration file
- parse_ini_string — Parse a configuration string
- pathinfo — Zwraca informacje o ścieżce do pliku
- pclose — Zamyka wskaźnik pliku do procesu
- popen — Otwiera wskaźnik pliku do procesu
- readfile — Wyświetla plik
- readlink — Zwraca cel linku symbolicznego
- realpath_cache_get — Get realpath cache entries
- realpath_cache_size — Get realpath cache size
- realpath — Returns canonicalized absolute pathname
- rename — Renames a file or directory
- rewind — Rewind the position of a file pointer
- rmdir — Usuwanie katalogów
- set_file_buffer — Alias dla stream_set_write_buffer
- stat — Gives information about a file
- symlink — Tworzy dowiązanie symboliczne
- tempnam — Create file with unique file name
- tmpfile — Tworzy plik tymczasowy
- touch — Ustawia czas modyfikacji pliku
- umask — Changes the current umask
- unlink — Kasowanie pliku
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Funkcje Systemu plików
- basename — Zwraca nazwę pliku, będącego składową ścieżki
- chgrp — Zmienia grupę pliku
- chmod — Zmienia prawa dostępu do pliku
- chown — Zmienia właściciela pliku
- clearstatcache — Czyści bufor statusu pliku
- copy — Kopiuje plik
- delete — Zobacz unlink lub unset
- dirname — Zwraca nazwę katalogu, będącego składową ścieżki
- disk_free_space — Zwraca ilość wolnego miejsca w systemie plików lub partycji dysku
- disk_total_space — Zwraca całkowity rozmiar systemu plików lub partycji dysku
- diskfreespace — Alias dla disk_free_space
- fclose — Zamyka otwarty wskaźnik pliku
- feof — Sprawdza czy wskaźnik pliku jest na końcu pliku (EOF)
- fflush — Przekierowuje wyjście do pliku
- fgetc — Pobiera znak ze wskaźnika pliku
- fgetcsv — Pobiera linię ze wskanika pliku i przetwarza na pola CSV
- fgets — Pobiera linię ze wskaźnika pliku
- fgetss — Pobiera linię ze wskaźnika pliku i usuwa znaczniki HTML
- file_exists — Sprawdza czy plik lub katalog istnieje
- file_get_contents — Reads entire file into a string
- file_put_contents — Write a string to a file
- file — Czyta całą zawartość pliku do tablicy
- fileatime — Pobiera ostatni czas dostępu do pliku
- filectime — Pobiera i-węzłowy czas zmiany pliku
- filegroup — Pobiera grupę pliku
- fileinode — Pobiera i-węzeł pliku
- filemtime — Pobiera czas ostatniej modyfikacji pliku
- fileowner — Pobiera właściciela pliku
- fileperms — Pobiera prawa dostępu pliku
- filesize — Pobiera rozmiar pliku
- filetype — Pobiera typ pliku
- flock — Portable advisory file locking
- fnmatch — Match filename against a pattern
- fopen — Otwiera plik lub URL
- fpassthru — Output all remaining data on a file pointer
- fputcsv — Format line as CSV and write to file pointer
- fputs — Alias dla fwrite
- fread — Odczyt pliku binarnie bezpieczy
- fscanf — Przetwarza dane z pliku według formatu
- fseek — Seeks on a file pointer
- fstat — Pobiera informacje o pliku używając otwartego wskaźnika pliku
- ftell — Mówi o pozycji odczyt/zapis wskaźnika pliku
- ftruncate — Przycina plik do podanej długości
- fwrite — Zapis pliku binarnie bezpieczny
- glob — Find pathnames matching a pattern
- is_dir — Mówi czy nazwa_pliku jest katalogiem
- is_executable — Mówi czy plik jest wykonywalny
- is_file — Mówi czy nazwa_pliku jest zwykłym plikiem
- is_link — Mówi czy nazwa_pliku jest dowiązaniem symbolicznym
- is_readable — Tells whether a file exists and is readable
- is_uploaded_file — Mówi czy plik został przysłany przez HTTP POST.
- is_writable — Tells whether the filename is writable
- is_writeable — Alias dla is_writable
- lchgrp — Changes group ownership of symlink
- lchown — Changes user ownership of symlink
- link — Tworzy dowiązanie twarde
- linkinfo — Pobiera informacje o linku
- lstat — Podaje informacje o pliku lub dowiązaniu symbolicznym
- mkdir — Tworzy katalog
- move_uploaded_file — Przenieś uploadowany plik do innej lokalizacji
- parse_ini_file — Parse a configuration file
- parse_ini_string — Parse a configuration string
- pathinfo — Zwraca informacje o ścieżce do pliku
- pclose — Zamyka wskaźnik pliku do procesu
- popen — Otwiera wskaźnik pliku do procesu
- readfile — Wyświetla plik
- readlink — Zwraca cel linku symbolicznego
- realpath_cache_get — Get realpath cache entries
- realpath_cache_size — Get realpath cache size
- realpath — Returns canonicalized absolute pathname
- rename — Renames a file or directory
- rewind — Rewind the position of a file pointer
- rmdir — Usuwanie katalogów
- set_file_buffer — Alias dla stream_set_write_buffer
- stat — Gives information about a file
- symlink — Tworzy dowiązanie symboliczne
- tempnam — Create file with unique file name
- tmpfile — Tworzy plik tymczasowy
- touch — Ustawia czas modyfikacji pliku
- umask — Changes the current umask
- unlink — Kasowanie pliku
Inotify
Wstęp
The inotify extension exposes the inotify functions inotify_init(), inotify_add_watch() and inotify_rm_watch().
As the C inotify_init() function returns a file descriptor, PHP's inotify_init() returns a stream resource, usable with standard stream functions, like stream_select(), stream_set_blocking() and fclose(). inotify_read() replaces the C way of reading inotify events.
Instalacja/Konfiguracja
Spis treści
Wymagania
This extension requires Linux 2.6.13 or newer, and a recent libC.
Instalacja/Konfiguracja
To rozszerzenie » PECL nie jest dołączane do PHP.
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/inotify.
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
-
Inotify constants usable with inotify_add_watch() and/or returned by inotify_read()
-
IN_ACCESS(integer) - File was accessed (read) (*)
-
IN_MODIFY(integer) - File was modified (*)
-
IN_ATTRIB(integer) - Metadata changed (e.g. permissions, mtime, etc.) (*)
-
IN_CLOSE_WRITE(integer) - File opened for writing was closed (*)
-
IN_CLOSE_NOWRITE(integer) - File not opened for writing was closed (*)
-
IN_OPEN(integer) - File was opened (*)
-
IN_MOVED_TO(integer) - File moved into watched directory (*)
-
IN_MOVED_FROM(integer) - File moved out of watched directory (*)
-
IN_CREATE(integer) - File or directory created in watched directory (*)
-
IN_DELETE(integer) - File or directory deleted in watched directory (*)
-
IN_DELETE_SELF(integer) - Watched file or directory was deleted
-
IN_MOVE_SELF(integer) - Watch file or directory was moved
-
IN_CLOSE(integer) - Equals to IN_CLOSE_WRITE | IN_CLOSE_NOWRITE
-
IN_MOVE(integer) - Equals to IN_MOVED_FROM | IN_MOVED_TO
-
IN_ALL_EVENTS(integer) - Bitmask of all the above constants
-
IN_UNMOUNT(integer) - File system containing watched object was unmounted
-
IN_Q_OVERFLOW(integer) - Event queue overflowed (wd is -1 for this event)
-
IN_IGNORED(integer) - Watch was removed (explicitly by inotify_rm_watch() or because file was removed or filesystem unmounted
-
IN_ISDIR(integer) - Subject of this event is a directory
-
IN_ONLYDIR(integer) - Only watch pathname if it is a directory (Since Linux 2.6.15)
-
IN_DONT_FOLLOW(integer) - Do not dereference pathname if it is a symlink (Since Linux 2.6.15)
-
IN_MASK_ADD(integer) - Add events to watch mask for this pathname if it already exists (instead of replacing mask).
-
IN_ONESHOT(integer) - Monitor pathname for one event, then remove from watch list.
Informacja: The events marked with an asterisk (*) above can occur for files in watched directories.
Inotify Funkcje
inotify_add_watch
(PECL inotify >= 0.1.2)
inotify_add_watch — Add a watch to an initialized inotify instance
Opis
$inotify_instance
, string $pathname
, int $mask
)
inotify_add_watch() adds a new watch or modify an
existing watch for the file or directory specified in
pathname.
Using inotify_add_watch() on a watched object replaces
the existing watch. Using the IN_MASK_ADD constant
adds (OR) events to the existing watch.
Parametry
-
inotify_instance -
Zasób zwracany przez inotify_init()
-
pathname -
File or directory to watch
-
mask -
Events to watch for. See Predefiniowane stałe.
Zwracane wartości
The return value is a unique (inotify instance wide) watch descriptor.
inotify_init
(PECL inotify >= 0.1.2)
inotify_init — Initialize an inotify instance
Zwracane wartości
A stream resource or FALSE on error.
Przykłady
Przykład #1 Example usage of inotify
<?php
// Open an inotify instance
$fd = inotify_init();
// Watch __FILE__ for metadata changes (e.g. mtime)
$watch_descriptor = inotify_add_watch($fd, __FILE__, IN_ATTRIB);
// generate an event
touch(__FILE__);
// Read events
$events = inotify_read($fd);
print_r($events);
// The following methods allows to use inotify functions without blocking on inotify_read():
// - Using stream_select() on $fd:
$read = array($fd);
$write = null;
$except = null;
stream_select($read,$write,$except,0);
// - Using stream_set_blocking() on $fd
stream_set_blocking($fd, 0);
inotify_read($fd); // Does no block, and return false if no events are pending
// - Using inotify_queue_len() to check if event queue is not empty
$queue_len = inotify_queue_len($fd); // If > 0, inotify_read() will not block
// Stop watching __FILE__ for metadata changes
inotify_rm_watch($fd, $watch_descriptor);
// Close the inotify instance
// This may have closed all watches if this was not already done
fclose($fd);
?>
Powyższy przykład wyświetli coś podobnego do:
array(
array(
'wd' => 1, // Equals $watch_descriptor
'mask' => 4, // IN_ATTRIB bit is set
'cookie' => 0, // unique id to connect related events (e.g.
// IN_MOVE_FROM and IN_MOVE_TO events)
'name' => '', // the name of a file (e.g. if we monitored changes
// in a directory)
),
);
Zobacz też:
- inotify_add_watch() - Add a watch to an initialized inotify instance
- inotify_rm_watch() - Remove an existing watch from an inotify instance
- inotify_queue_len() - Return a number upper than zero if there are pending events
- inotify_read() - Read events from an inotify instance
- fclose() - Zamyka otwarty wskaźnik pliku
inotify_queue_len
(PECL inotify >= 0.1.2)
inotify_queue_len — Return a number upper than zero if there are pending events
Opis
$inotify_instance
)This function allows to know if inotify_read() will block or not. If a number upper than zero is returned, there are pending events and inotify_read() will not block.
Zwracane wartości
Returns a number upper than zero if there are pending events.
Zobacz też:
- inotify_init() - Initialize an inotify instance
- stream_select() - Runs the equivalent of the select() system call on the given arrays of streams with a timeout specified by tv_sec and tv_usec
- stream_set_blocking() - Set blocking/non-blocking mode on a stream
inotify_read
(PECL inotify >= 0.1.2)
inotify_read — Read events from an inotify instance
Opis
$inotify_instance
)Read inotify events from an inotify instance.
Zwracane wartości
An array of inotify events or FALSE if no events was pending and
inotify_instance is non-blocking. Each event is an array with the following keys:
- wd is a watch descriptor returned by inotify_add_watch()
- mask is a bit mask of events
- cookie is a unique id to connect related events (e.g.
IN_MOVE_FROMandIN_MOVE_TO) - name is the name of a file (e.g. if a file was modified in a watched directory)
Zobacz też:
- inotify_init() - Initialize an inotify instance
- stream_select() - Runs the equivalent of the select() system call on the given arrays of streams with a timeout specified by tv_sec and tv_usec
- stream_set_blocking() - Set blocking/non-blocking mode on a stream
- inotify_queue_len() - Return a number upper than zero if there are pending events
inotify_rm_watch
(PECL inotify >= 0.1.2)
inotify_rm_watch — Remove an existing watch from an inotify instance
Opis
$inotify_instance
, int $watch_descriptor
)
inotify_rm_watch() removes the watch
watch_descriptor from the inotify instance
inotify_instance.
Parametry
-
inotify_instance -
Zasób zwracany przez inotify_init()
-
watch_descriptor -
Watch to remove from the instance
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Spis treści
- inotify_add_watch — Add a watch to an initialized inotify instance
- inotify_init — Initialize an inotify instance
- inotify_queue_len — Return a number upper than zero if there are pending events
- inotify_read — Read events from an inotify instance
- inotify_rm_watch — Remove an existing watch from an inotify instance
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Inotify Funkcje
- inotify_add_watch — Add a watch to an initialized inotify instance
- inotify_init — Initialize an inotify instance
- inotify_queue_len — Return a number upper than zero if there are pending events
- inotify_read — Read events from an inotify instance
- inotify_rm_watch — Remove an existing watch from an inotify instance
Mimetype
Wstęp
This extension has been deprecated as the PECL extension Fileinfo provides the same functionality (and more) in a much cleaner way.
The functions in this module try to guess the content type and encoding of a file by looking for certain magic byte sequences at specific positions within the file. While this is not a bullet proof approach the heuristics used do a very good job.
This extension is derived from Apache mod_mime_magic, which is itself based on the file command maintained by Ian F. Darwin. See the source code for further historic and copyright information.
Instalacja/Konfiguracja
Spis treści
Wymagania
Do zbudowania tego rozszerzenia nie są wymagane żadne zewnętrzne biblioteki.
Instalacja
Mimetype extensions has been removed from PHP 5.3.0 in favor of Fileinfo.
You must compile PHP with the configure switch --with-mime-magic to get support for mime-type functions. The extension needs a copy of the simplified magic file that is distributed with the Apache httpd.
Informacja:
The configure option has been changed from --enable-mime-magic to --with-mime-magic since PHP 4.3.2
Informacja:
This extension is not capable of handling the fully decorated magic file that generally comes with standard Linux distro's and is supposed to be used with recent versions of file command.
Informacja: Note to Win32 Users
In order to use this module on a Windows environment, you must set the path to the bundled magic.mime file in your php.ini.
Przykład #1 Setting the path to magic.mime
mime_magic.magicfile = "$PHP_INSTALL_DIR\magic.mime"Remember to substitute the $PHP_INSTALL_DIR for your actual path to PHP in the above example. e.g. c:\php
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| mime_magic.debug | "0" | PHP_INI_SYSTEM | Available since PHP 5.0.0. |
| mime_magic.magicfile | "/path/to/php/magic.mime" | PHP_INI_SYSTEM | Available since PHP 4.3.0. |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
To rozszerzenie nie posiada żadnych stałych.
Proctitle
Wstęp
This extension allows changing the current process', and thread, name on Linux and *BSD systems. This is useful when using pcntl_fork() to identify running processes in process list
Instalacja/Konfiguracja
Spis treści
Wymagania
Nothing special.
Instalacja
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/proctitle.
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
To rozszerzenie nie posiada żadnych stałych.
Proctitle Funkcje
setproctitle
(PECL proctitle >= 0.1.0)
setproctitle — Set the process title
Opis
$title
)Sets the process title of the current process.
Parametry
-
title -
The title to use as the process title.
Zwracane wartości
Nie jest zwracana żadna wartość.
Przykłady
Przykład #1 setproctitle() example
Running the example below will change the process title (visible with ps a for example).
<?php
setproctitle("myscript");
?>
Powyższy przykład wyświetli coś podobnego do:
$ ps a PID TTY STAT TIME COMMAND 1168 pts/3 S 0:00 myscript
Zobacz też:
- pcntl_fork() - Forks the currently running process
- setthreadtitle() - Set the thread title
setthreadtitle
(PECL proctitle >= 0.1.2)
setthreadtitle — Set the thread title
Opis
$title
)Sets the thread title.
Parametry
-
title -
The title to use as the thread title.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 setthreadtitle() example
Running the example below will change the thread title (visible with ps c for example).
<?php
setthreadtitle("myscript");
?>
Powyższy przykład wyświetli coś podobnego do:
$ ps c PID TTY STAT TIME COMMAND 1178 pts/3 S 0:00 myscript
Zobacz też:
- pcntl_fork() - Forks the currently running process
- setproctitle() - Set the process title
Spis treści
- setproctitle — Set the process title
- setthreadtitle — Set the thread title
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Proctitle Funkcje
- setproctitle — Set the process title
- setthreadtitle — Set the thread title
xattr
Wstęp
The xattr extension allows for the manipulation of extended attributes on a filesystem.
Instalacja/Konfiguracja
Spis treści
Wymagania
To use xattr, you will need libattr installed. It is available at » http://oss.sgi.com/projects/xfs/.
Informacja:
These functions only work on filesystems that support extended attributes, and have them enabled at mount time. Some common filesystems that support extended attributes are ext2, ext3, reiserfs, jfs, and xfs.
Instalacja
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/xattr.
DLL z tym rozszerzeniem PECL można pobrać zarówno ze strony » PHP Downloads lub z » http://pecl4win.php.net/
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
-
XATTR_ROOT(integer) - Set attribute in root (trusted) namespace. Requires root privileges.
-
XATTR_DONTFOLLOW(integer) - Do not follow the symbolic link but operate on symbolic link itself.
-
XATTR_CREATE(integer) - Function will fail if extended attribute already exists.
-
XATTR_REPLACE(integer) - Function will fail if extended attribute doesn't exist.
xattr Funkcje
xattr_get
(PECL xattr >= 0.9.0)
xattr_get — Get an extended attribute
Opis
$filename
, string $name
[, int $flags = 0
] )This function gets the value of an extended attribute of a file.
Rozszerzone atrybuty mają dwie różne
przestrzenie nazw: przestrzeń użytkownika i roota. Przestrzeń
użytkownika dostępna jest dla wszystkich użytkowników, podczas gdy przestrzeń
roota dostępna jest tylko dla użytkownika z uprawnieniami superużytkownika.
xattr domyślne działa w przestrzeni użytkownika, ale można to zmienić używając
argumentu flags.
Parametry
-
filename -
The file from which we get the attribute.
-
name -
The name of the attribute.
-
flags -
Supported xattr flags XATTR_DONTFOLLOWDo not follow the symbolic link but operate on symbolic link itself. XATTR_ROOTSet attribute in root (trusted) namespace. Requires root privileges.
Zwracane wartości
Returns a string containing the value or FALSE if the attribute doesn't
exist.
Przykłady
Przykład #1 Checks if system administrator has signed the file
<?php
$file = '/usr/local/sbin/some_binary';
$signature = xattr_get($file, 'Root signature', XATTR_ROOT);
/* ... check if $signature is valid ... */
?>
Zobacz też:
- xattr_list() - Get a list of extended attributes
- xattr_set() - Set an extended attribute
- xattr_remove() - Remove an extended attribute
xattr_list
(PECL xattr >= 0.9.0)
xattr_list — Get a list of extended attributes
Opis
$filename
[, int $flags = 0
] )This functions gets a list of names of extended attributes of a file.
Rozszerzone atrybuty mają dwie różne
przestrzenie nazw: przestrzeń użytkownika i roota. Przestrzeń
użytkownika dostępna jest dla wszystkich użytkowników, podczas gdy przestrzeń
roota dostępna jest tylko dla użytkownika z uprawnieniami superużytkownika.
xattr domyślne działa w przestrzeni użytkownika, ale można to zmienić używając
argumentu flags.
Parametry
-
filename -
The path of the file.
-
flags -
Supported xattr flags XATTR_DONTFOLLOWDo not follow the symbolic link but operate on symbolic link itself. XATTR_ROOTSet attribute in root (trusted) namespace. Requires root privileges.
Zwracane wartości
This function returns an array with names of extended attributes.
Przykłady
Przykład #1 Prints names of all extended attributes of file
<?php
$file = 'some_file';
$root_attributes = xattr_list($file, XATTR_ROOT);
$user_attributes = xattr_list($file);
echo "Root attributes: \n";
foreach ($root_attributes as $attr_name) {
printf("%s\n", $attr_name);
}
echo "\n User attributes: \n";
foreach ($attributes as $attr_name) {
printf("%s\n", $attr_name);
}
?>
xattr_remove
(PECL xattr >= 0.9.0)
xattr_remove — Remove an extended attribute
Opis
$filename
, string $name
[, int $flags = 0
] )This function removes an extended attribute of a file.
Rozszerzone atrybuty mają dwie różne
przestrzenie nazw: przestrzeń użytkownika i roota. Przestrzeń
użytkownika dostępna jest dla wszystkich użytkowników, podczas gdy przestrzeń
roota dostępna jest tylko dla użytkownika z uprawnieniami superużytkownika.
xattr domyślne działa w przestrzeni użytkownika, ale można to zmienić używając
argumentu flags.
Parametry
-
filename -
The file from which we remove the attribute.
-
name -
The name of the attribute to remove.
-
flags -
Supported xattr flags XATTR_DONTFOLLOWDo not follow the symbolic link but operate on symbolic link itself. XATTR_ROOTSet attribute in root (trusted) namespace. Requires root privileges.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Removes all extended attributes of a file
<?php
$file = 'some_file';
$attributes = xattr_list($file);
foreach ($attributes as $attr_name) {
xattr_remove($file, $attr_name);
}
?>
Zobacz też:
- xattr_list() - Get a list of extended attributes
- xattr_set() - Set an extended attribute
- xattr_get() - Get an extended attribute
xattr_set
(PECL xattr >= 0.9.0)
xattr_set — Set an extended attribute
Opis
$filename
, string $name
, string $value
[, int $flags = 0
] )This function sets the value of an extended attribute of a file.
Rozszerzone atrybuty mają dwie różne
przestrzenie nazw: przestrzeń użytkownika i roota. Przestrzeń
użytkownika dostępna jest dla wszystkich użytkowników, podczas gdy przestrzeń
roota dostępna jest tylko dla użytkownika z uprawnieniami superużytkownika.
xattr domyślne działa w przestrzeni użytkownika, ale można to zmienić używając
argumentu flags.
Parametry
-
filename -
The file in which we set the attribute.
-
name -
The name of the extended attribute. This attribute will be created if it doesn't exist or replaced otherwise. You can change this behaviour by using the
flagsparameter. -
value -
The value of the attribute.
-
flags -
Supported xattr flags XATTR_CREATEFunction will fail if extended attribute already exists. XATTR_REPLACEFunction will fail if extended attribute doesn't exist. XATTR_DONTFOLLOWDo not follow the symbolic link but operate on symbolic link itself. XATTR_ROOTSet attribute in root (trusted) namespace. Requires root privileges.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 Sets extended attributes on .wav file
<?php
$file = 'my_favourite_song.wav';
xattr_set($file, 'Artist', 'Someone');
xattr_set($file, 'My ranking', 'Good');
xattr_set($file, 'Listen count', '34');
/* ... other code ... */
printf("You've played this song %d times", xattr_get($file, 'Listen count'));
?>
xattr_supported
(PECL xattr >= 1.0.0)
xattr_supported — Check if filesystem supports extended attributes
Opis
$filename
[, int $flags = 0
] )This functions checks if the filesystem holding the given file supports extended attributes. Read access to the file is required.
Parametry
-
filename -
The path of the tested file.
-
flags -
Supported xattr flags XATTR_DONTFOLLOWDo not follow the symbolic link but operate on symbolic link itself.
Zwracane wartości
This function returns TRUE if filesystem supports extended attributes,
FALSE if it doesn't and NULL if it can't be determined (for example
wrong path or lack of permissions to file).
Przykłady
Przykład #1 xattr_supported() example
The following code checks if we can use extended attributes.
<?php
$file = 'some_file';
if (xattr_supported($file)) {
/* ... make use of some xattr_* functions ... */
}
?>
Zobacz też:
- xattr_get() - Get an extended attribute
- xattr_list() - Get a list of extended attributes
Spis treści
- xattr_get — Get an extended attribute
- xattr_list — Get a list of extended attributes
- xattr_remove — Remove an extended attribute
- xattr_set — Set an extended attribute
- xattr_supported — Check if filesystem supports extended attributes
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- xattr Funkcje
- xattr_get — Get an extended attribute
- xattr_list — Get a list of extended attributes
- xattr_remove — Remove an extended attribute
- xattr_set — Set an extended attribute
- xattr_supported — Check if filesystem supports extended attributes
xdiff
Wstęp
xdiff extension enables you to create and apply patch files containing differences between different revisions of files.
This extension supports two modes of operation - on strings and on files, as well as two different patch formats - unified and binary. Unified patches are excellent for text files as they are human-readable and easy to review. For binary files like archives or images, binary patches will be adequate choice as they are binary safe and handle non-printable characters well.
Starting from version 1.5.0 there are two different sets of functions for generating binary patches. New functions - xdiff_string_rabdiff() and xdiff_file_rabdiff() generate output compatible with older functions but are typically faster and generate smaller results. For more details about methods of generating binary patches and differences between them, please check » libxdiff website.
This extension uses libxdiff to implement these functions. Please see » http://www.xmailserver.org/xdiff-lib.html for more information.
Instalacja/Konfiguracja
Spis treści
Wymagania
To use xdiff, you will need libxdiff installed, available on the libxdiff homepage » http://www.xmailserver.org/xdiff-lib.html.
Informacja:
You'll need at least libxdiff 0.7 for these functions to be aware of memory_limit.
Instalacja
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/xdiff.
DLL z tym rozszerzeniem PECL można pobrać zarówno ze strony » PHP Downloads lub z » http://pecl4win.php.net/
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
-
XDIFF_PATCH_NORMAL(integer) - This flag indicates that xdiff_string_patch() and xdiff_file_patch() functions should create result by applying patch to original content thus creating newer version of file. This is the default mode of operation.
-
XDIFF_PATCH_REVERSE(integer) - This flag indicated that xdiff_string_patch() and xdiff_file_patch() functions should create result by reversing patch changed from newer content thus creating original version.
xdiff Funkcje
xdiff_file_bdiff_size
(PECL xdiff >= 1.5.0)
xdiff_file_bdiff_size — Read a size of file created by applying a binary diff
Opis
$file
)
Returns a size of a result file that would be created after applying binary patch from file
file to the original file.
Parametry
-
file -
The path to the binary patch created by xdiff_string_bdiff() or xdiff_string_rabdiff() function.
Zwracane wartości
Returns the size of file that would be created.
Przykłady
Przykład #1 xdiff_file_bdiff_size() example
The following code applies reads a size of file that would be created after applying a binary diff.
<?php
$length = xdiff_string_bdiff_size('file.bdiff');
echo "Resulting file will be $length bytes long";
?>
Zobacz też:
- xdiff_file_bdiff() - Make binary diff of two files
- xdiff_file_rabdiff() - Make binary diff of two files using the Rabin's polynomial fingerprinting algorithm
- xdiff_file_bpatch() - Patch a file with a binary diff
xdiff_file_bdiff
(PECL xdiff >= 1.5.0)
xdiff_file_bdiff — Make binary diff of two files
Opis
$old_file
, string $new_file
, string $dest
)Makes a binary diff of two files and stores the result in a patch file. This function works with both text and binary files. Resulting patch file can be later applied using xdiff_file_bpatch()/xdiff_string_bpatch().
Parametry
-
old_file -
Path to the first file. This file acts as "old" file.
-
new_file -
Path to the second file. This file acts as "new" file.
-
dest -
Path of the resulting patch file. Resulting file contains differences between "old" and "new" files. It is in binary format and is human-unreadable.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 xdiff_file_bdiff() example
The following code makes binary diff of two archives.
<?php
$old_version = 'my_script_1.0.tgz';
$new_version = 'my_script_1.1.tgz';
xdiff_file_bdiff($old_version, $new_version, 'my_script.bdiff');
?>
Notatki
Informacja:
Both files will be loaded into memory so ensure that your memory_limit is set high enough.
xdiff_file_bpatch
(PECL xdiff >= 1.5.0)
xdiff_file_bpatch — Patch a file with a binary diff
Opis
$file
, string $patch
, string $dest
)
Patches a file with a binary
patch and stores the result in a file dest.
This function accepts patches created both via xdiff_file_bdiff()
and xdiff_file_rabdiff() functions or their string counterparts.
Parametry
-
file -
The original file.
-
patch -
The binary patch file.
-
dest -
Path of the resulting file.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 xdiff_file_bpatch() example
The following code applies binary diff to a file.
<?php
$old_version = 'archive-1.0.tgz';
$patch = 'archive.bpatch';
$result = xdiff_file_bpatch($old_version, $patch, 'archive-1.1.tgz');
if ($result) {
echo "File patched";
} else {
echo "File couldn't be patched";
}
?>
Notatki
Informacja:
Both files (
fileandpatch) will be loaded into memory so ensure that your memory_limit is set high enough.
Zobacz też:
- xdiff_file_bdiff() - Make binary diff of two files
- xdiff_file_rabdiff() - Make binary diff of two files using the Rabin's polynomial fingerprinting algorithm
xdiff_file_diff_binary
(PECL xdiff >= 0.2.0)
xdiff_file_diff_binary — Alias of xdiff_file_bdiff
Opis
$old_file
, string $new_file
, string $dest
)Makes a binary diff of two files and stores the result in a patch file. This function works with both text and binary files. Resulting patch file can be later applied using xdiff_file_bpatch().
Starting with version 1.5.0 this function is an alias of xdiff_file_bdiff().
Parametry
-
old_file -
Path to the first file. This file acts as "old" file.
-
new_file -
Path to the second file. This file acts as "new" file.
-
dest -
Path of the resulting patch file. Resulting file contains differences between "old" and "new" files. It is in binary format and is human-unreadable.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 xdiff_file_diff_binary() example
The following code makes binary diff of two archives.
<?php
$old_version = 'my_script_1.0.tgz';
$new_version = 'my_script_1.1.tgz';
xdiff_file_diff_binary($old_version, $new_version, 'my_script.bdiff');
?>
Notatki
Informacja:
Both files will be loaded into memory so ensure that your memory_limit is set high enough.
Zobacz też:
- xdiff_file_bdiff() - Make binary diff of two files
- xdiff_file_bpatch() - Patch a file with a binary diff
xdiff_file_diff
(PECL xdiff >= 0.2.0)
xdiff_file_diff — Make unified diff of two files
Opis
$old_file
, string $new_file
, string $dest
[, int $context = 3
[, bool $minimal = false
]] )
Makes an unified diff containing differences between old_file and
new_file and stores it in dest file. The
resulting file is human-readable. An optional context parameter
specifies how many lines of context should be added around each change.
Setting minimal parameter to true will result in outputting the shortest
patch file possible (can take a long time).
Parametry
-
old_file -
Path to the first file. This file acts as "old" file.
-
new_file -
Path to the second file. This file acts as "new" file.
-
dest -
Path of the resulting patch file.
-
context -
Indicates how many lines of context you want to include in diff result.
-
minimal -
Set this parameter to
TRUEif you want to minimalize size of the result (can take a long time).
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 xdiff_file_diff() example
The following code makes unified diff of two php files with context length of 2.
<?php
$old_version = 'my_script.php';
$new_version = 'my_new_script.php';
xdiff_file_diff($old_version, $new_version, 'my_script.diff', 2);
?>
Notatki
Informacja:
This function doesn't work well with binary files. To make diff of binary files use xdiff_file_bdiff()/xdiff_file_rabdiff() function.
xdiff_file_merge3
(PECL xdiff >= 0.2.0)
xdiff_file_merge3 — Merge 3 files into one
Opis
Merges three files into one and stores the result in a file dest.
The old_file is an original version while new_file1
and new_file2 are modified versions of an original.
Parametry
-
old_file -
Path to the first file. It acts as "old" file.
-
new_file1 -
Path to the second file. It acts as modified version of
old_file. -
new_file2 -
Path to the third file. It acts as modified version of
old_file. -
dest -
Path of the resulting file, containing merged changed from both
new_file1andnew_file2.
Zwracane wartości
Returns TRUE if merge was successful, string with rejected chunks if
it was not or FALSE if an internal error happened.
Przykłady
Przykład #1 xdiff_file_merge3() example
The following code merges three files into one.
<?php
$old_version = 'original_script.php';
$fix1 = 'script_with_fix1.php';
$fix2 = 'script_with_fix2.php';
$errors = xdiff_file_merge3($old_version, $fix1, $fix2, 'fixed_script.php');
if (is_string($errors)) {
echo "Rejects:\n";
echo $errors;
}
?>
xdiff_file_patch_binary
(PECL xdiff >= 0.2.0)
xdiff_file_patch_binary — Alias of xdiff_file_bpatch
Opis
$file
, string $patch
, string $dest
)
Patches a file with a binary
patch and stores the result in a file dest.
This function accepts patches created both via xdiff_file_bdiff()
or xdiff_file_rabdiff() functions or their string counterparts.
Starting with version 1.5.0 this function is an alias of xdiff_file_bpatch().
Parametry
-
file -
The original file.
-
patch -
The binary patch file.
-
dest -
Path of the resulting file.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 xdiff_file_patch_binary() example
The following code applies binary diff to a file.
<?php
$old_version = 'archive-1.0.tgz';
$patch = 'archive.bpatch';
$result = xdiff_file_patch_binary($old_version, $patch, 'archive-1.1.tgz');
if ($result) {
echo "File patched";
} else {
echo "File couldn't be patched";
}
?>
Notatki
Informacja:
Both files (
fileandpatch) will be loaded into memory so ensure that your memory_limit is set high enough.
xdiff_file_patch
(PECL xdiff >= 0.2.0)
xdiff_file_patch — Patch a file with an unified diff
Opis
$file
, string $patch
, string $dest
[, int $flags = DIFF_PATCH_NORMAL
] )
Patches a file with a patch and stores the result in a file.
patch has to be an unified diff created by
xdiff_file_diff()/xdiff_string_diff() function.
An optional flags parameter specifies mode of operation.
Parametry
-
file -
The original file.
-
patch -
The unified patch file. It has to be created using xdiff_string_diff(), xdiff_file_diff() functions or compatible tools.
-
dest -
Path of the resulting file.
-
flags -
Can be either
XDIFF_PATCH_NORMAL(default mode, normal patch) orXDIFF_PATCH_REVERSE(reversed patch).Starting from version 1.5.0, you can also use binary OR to enable
XDIFF_PATCH_IGNORESPACEflag.
Zwracane wartości
Returns FALSE if an internal error happened, string with rejected
chunks if patch couldn't be applied or TRUE if patch has been successfully applied.
Przykłady
Przykład #1 xdiff_file_patch() example
The following code applies unified diff to a file.
<?php
$old_version = 'my_script-1.0.php';
$patch = 'my_script.patch';
$errors = xdiff_file_patch($old_version, $patch, 'my_script-1.1.php');
if (is_string($errors)) {
echo "Rejects:\n";
echo $errors;
}
?>
Przykład #2 Patch reversing example
The following code reverses a patch.
<?php
$new_version = 'my_script-1.1.php';
$patch = 'my_script.patch';
$errors = xdiff_file_patch($new_version, $patch, 'my_script-1.0.php', XDIFF_PATCH_REVERSE);
if (is_string($errors)) {
echo "Rejects:\n";
echo $errors;
}
?>
xdiff_file_rabdiff
(PECL xdiff >= 1.5.0)
xdiff_file_rabdiff — Make binary diff of two files using the Rabin's polynomial fingerprinting algorithm
Opis
$old_file
, string $new_file
, string $dest
)Makes a binary diff of two files and stores the result in a patch file. The difference between this function and xdiff_file_bdiff() is different algorithm used which should result in faster execution and smaller diff produced. This function works with both text and binary files. Resulting patch file can be later applied using xdiff_file_bpatch()/xdiff_string_bpatch().
For more details about differences between algorithm used please check » libxdiff website.
Parametry
-
old_file -
Path to the first file. This file acts as "old" file.
-
new_file -
Path to the second file. This file acts as "new" file.
-
dest -
Path of the resulting patch file. Resulting file contains differences between "old" and "new" files. It is in binary format and is human-unreadable.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 xdiff_file_rabdiff() example
The following code makes binary diff of two archives.
<?php
$old_version = 'my_script_1.0.tgz';
$new_version = 'my_script_1.1.tgz';
xdiff_file_rabdiff($old_version, $new_version, 'my_script.bdiff');
?>
Notatki
Informacja:
Both files will be loaded into memory so ensure that your memory_limit is set high enough.
xdiff_string_bdiff_size
(PECL xdiff >= 1.5.0)
xdiff_string_bdiff_size — Read a size of file created by applying a binary diff
Opis
$patch
)
Returns a size of a result file that would be created after applying binary patch to
the original file.
Parametry
-
patch -
The binary patch created by xdiff_string_bdiff() or xdiff_string_rabdiff() function.
Zwracane wartości
Returns the size of file that would be created.
Przykłady
Przykład #1 xdiff_string_bdiff_size() example
The following code applies reads a size of file that would be created after applying a binary diff.
<?php
$binary_patch = file_get_contents('file.bdiff');
$length = xdiff_string_bdiff_size($binary_patch);
echo "Resulting file will be $length bytes long";
?>
Zobacz też:
- xdiff_string_bdiff() - Make binary diff of two strings
- xdiff_string_rabdiff() - Make binary diff of two strings using the Rabin's polynomial fingerprinting algorithm
- xdiff_string_bpatch() - Patch a string with a binary diff
xdiff_string_bdiff
(PECL xdiff >= 1.5.0)
xdiff_string_bdiff — Make binary diff of two strings
Opis
$old_data
, string $new_data
)Makes a binary diff of two strings and returns the result. This function works with both text and binary data. Resulting patch can be later applied using xdiff_string_bpatch()/xdiff_file_bpatch().
Parametry
-
old_data -
First string with binary data. It acts as "old" data.
-
new_data -
Second string with binary data. It acts as "new" data.
Zwracane wartości
Returns string with binary diff containing differences between "old" and "new"
data or FALSE if an internal error occurred.
xdiff_string_bpatch
(PECL xdiff >= 1.5.0)
xdiff_string_bpatch — Patch a string with a binary diff
Opis
$str
, string $patch
)
Patches a string str with a binary patch.
This function accepts patches created both via xdiff_string_bdiff()
and xdiff_string_rabdiff() functions or their file counterparts.
Parametry
-
str -
The original binary string.
-
patch -
The binary patch string.
Zwracane wartości
Returns the patched string, or FALSE on error.
Zobacz też:
- xdiff_string_bdiff() - Make binary diff of two strings
- xdiff_string_rabdiff() - Make binary diff of two strings using the Rabin's polynomial fingerprinting algorithm
xdiff_string_diff_binary
(PECL xdiff >= 0.2.0)
xdiff_string_diff_binary — Alias of xdiff_string_bdiff
Opis
Makes a binary diff of two strings and returns the result. This function works with both text and binary data. Resulting patch can be later applied using xdiff_string_bpatch()/xdiff_file_bpatch().
Starting with version 1.5.0 this function is an alias of xdiff_string_bdiff().
Parametry
-
old_data -
First string with binary data. It acts as "old" data.
-
new_data -
Second string with binary data. It acts as "new" data.
Zwracane wartości
Returns string with result or FALSE if an internal error happened.
Zobacz też:
- xdiff_string_bdiff() - Make binary diff of two strings
- xdiff_string_bpatch() - Patch a string with a binary diff
xdiff_string_diff
(PECL xdiff >= 0.2.0)
xdiff_string_diff — Make unified diff of two strings
Opis
$old_data
, string $new_data
[, int $context = 3
[, bool $minimal = false
]] )
Makes an unified diff containing differences between old_data string and
new_data string and returns it. The resulting diff is human-readable.
An optional context parameter specifies how many lines of context should be
added around each change. Setting minimal parameter
to true will result in outputting the shortest patch file possible (can take a long time).
Parametry
-
old_data -
First string with data. It acts as "old" data.
-
new_data -
Second string with data. It acts as "new" data.
-
context -
Indicates how many lines of context you want to include in the diff result.
-
minimal -
Set this parameter to
TRUEif you want to minimalize the size of the result (can take a long time).
Zwracane wartości
Returns string with resulting diff or FALSE if an internal error happened.
Przykłady
Przykład #1 xdiff_string_diff() example
The following code makes unified diff of two articles.
<?php
$old_article = file_get_contents('./old_article.txt');
$new_article = $_REQUEST['article']; /* Let's say that someone pasted a new article to html form */
$diff = xdiff_string_diff($old_article, $new_article, 1);
if (is_string($diff)) {
echo "Differences between two articles:\n";
echo $diff;
}
?>
Notatki
Informacja:
This function doesn't work well with binary strings. To make diff of binary strings use xdiff_string_bdiff()/xdiff_string_rabdiff().
xdiff_string_merge3
(PECL xdiff >= 0.2.0)
xdiff_string_merge3 — Merge 3 strings into one
Opis
$old_data
, string $new_data1
, string $new_data2
[, string &$error
] )
Merges three strings into one and returns the result.
The old_data is an original version of data
while new_file1 and new_file2 are modified
versions of an original. An optional error is used to pass any
rejected parts during merging process.
Parametry
-
old_data -
First string with data. It acts as "old" data.
-
new_data1 -
Second string with data. It acts as modified version of
old_data. -
new_data2 -
Third string with data. It acts as modified version of
old_data. -
error -
If provided then rejected parts are stored inside this variable.
Zwracane wartości
Returns the merged string, FALSE if an internal error happened, or TRUE
if merged string is empty.
xdiff_string_patch_binary
(PECL xdiff >= 0.2.0)
xdiff_string_patch_binary — Alias of xdiff_string_bpatch
Opis
$str
, string $patch
)
Patches a string str with a binary patch.
This function accepts patches created both via xdiff_string_bdiff()
and xdiff_string_rabdiff() functions or their file counterparts.
Starting with version 1.5.0 this function is an alias of xdiff_string_bpatch().
Parametry
-
str -
The original binary string.
-
patch -
The binary patch string.
Zwracane wartości
Returns the patched string, or FALSE on error.
Zobacz też:
- xdiff_string_bpatch() - Patch a string with a binary diff
- xdiff_string_bdiff() - Make binary diff of two strings
- xdiff_string_rabdiff() - Make binary diff of two strings using the Rabin's polynomial fingerprinting algorithm
xdiff_string_patch
(PECL xdiff >= 0.2.0)
xdiff_string_patch — Patch a string with an unified diff
Opis
$str
, string $patch
[, int $flags
[, string &$error
]] )
Patches a str string with an unified patch in patch parameter
and returns the result. patch has to be an unified diff created by
xdiff_file_diff()/xdiff_string_diff() function.
An optional flags parameter specifies mode of operation. Any
rejected parts of the patch will be stored inside error variable if
it is provided.
Parametry
-
str -
The original string.
-
patch -
The unified patch string. It has to be created using xdiff_string_diff(), xdiff_file_diff() functions or compatible tools.
-
flags -
flagscan be eitherXDIFF_PATCH_NORMAL(default mode, normal patch) orXDIFF_PATCH_REVERSE(reversed patch).Starting from version 1.5.0, you can also use binary OR to enable
XDIFF_PATCH_IGNORESPACEflag. -
error -
If provided then rejected parts are stored inside this variable.
Zwracane wartości
Returns the patched string, or FALSE on error.
Przykłady
Przykład #1 xdiff_string_patch() example
The following code applies changes to some article.
<?php
$old_article = file_get_contents('./old_article.txt');
$diff = $_SERVER['patch']; /* Let's say that someone pasted a patch to html form */
$errors = '';
$new_article = xdiff_string_patch($old_article, $diff, XDIFF_PATCH_NORMAL, $errors);
if (is_string($new_article)) {
echo "New article:\n";
echo $new_article;
}
if (strlen($errors)) {
echo "Rejects: \n";
echo $errors;
}
?>
xdiff_string_rabdiff
(PECL xdiff >= 1.5.0)
xdiff_string_rabdiff — Make binary diff of two strings using the Rabin's polynomial fingerprinting algorithm
Opis
Makes a binary diff of two strings and returns the result. The difference between this function and xdiff_string_bdiff() is different algorithm used which should result in faster execution and smaller diff produced. This function works with both text and binary data. Resulting patch can be later applied using xdiff_string_bpatch()/xdiff_file_bpatch().
For more details about differences between algorithm used please check » libxdiff website.
Parametry
-
old_data -
First string with binary data. It acts as "old" data.
-
new_data -
Second string with binary data. It acts as "new" data.
Zwracane wartości
Returns string with binary diff containing differences between "old" and "new"
data or FALSE if an internal error occurred.
Spis treści
- xdiff_file_bdiff_size — Read a size of file created by applying a binary diff
- xdiff_file_bdiff — Make binary diff of two files
- xdiff_file_bpatch — Patch a file with a binary diff
- xdiff_file_diff_binary — Alias of xdiff_file_bdiff
- xdiff_file_diff — Make unified diff of two files
- xdiff_file_merge3 — Merge 3 files into one
- xdiff_file_patch_binary — Alias of xdiff_file_bpatch
- xdiff_file_patch — Patch a file with an unified diff
- xdiff_file_rabdiff — Make binary diff of two files using the Rabin's polynomial fingerprinting algorithm
- xdiff_string_bdiff_size — Read a size of file created by applying a binary diff
- xdiff_string_bdiff — Make binary diff of two strings
- xdiff_string_bpatch — Patch a string with a binary diff
- xdiff_string_diff_binary — Alias of xdiff_string_bdiff
- xdiff_string_diff — Make unified diff of two strings
- xdiff_string_merge3 — Merge 3 strings into one
- xdiff_string_patch_binary — Alias of xdiff_string_bpatch
- xdiff_string_patch — Patch a string with an unified diff
- xdiff_string_rabdiff — Make binary diff of two strings using the Rabin's polynomial fingerprinting algorithm
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- xdiff Funkcje
- xdiff_file_bdiff_size — Read a size of file created by applying a binary diff
- xdiff_file_bdiff — Make binary diff of two files
- xdiff_file_bpatch — Patch a file with a binary diff
- xdiff_file_diff_binary — Alias of xdiff_file_bdiff
- xdiff_file_diff — Make unified diff of two files
- xdiff_file_merge3 — Merge 3 files into one
- xdiff_file_patch_binary — Alias of xdiff_file_bpatch
- xdiff_file_patch — Patch a file with an unified diff
- xdiff_file_rabdiff — Make binary diff of two files using the Rabin's polynomial fingerprinting algorithm
- xdiff_string_bdiff_size — Read a size of file created by applying a binary diff
- xdiff_string_bdiff — Make binary diff of two strings
- xdiff_string_bpatch — Patch a string with a binary diff
- xdiff_string_diff_binary — Alias of xdiff_string_bdiff
- xdiff_string_diff — Make unified diff of two strings
- xdiff_string_merge3 — Merge 3 strings into one
- xdiff_string_patch_binary — Alias of xdiff_string_bpatch
- xdiff_string_patch — Patch a string with an unified diff
- xdiff_string_rabdiff — Make binary diff of two strings using the Rabin's polynomial fingerprinting algorithm
- Direct IO
- Directories
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Directory — The Directory class
- Funkcje katalogów
- Fileinfo — File Information
- Filesystem
- Inotify
- Mimetype
- Proctitle
- xattr
- xdiff
Język naturalny i obsługa kodowania znaków
Enchant spelling library
Wstęp
Enchant is the PHP binding for the » Enchant library. Enchant steps in to provide uniformity and conformity on top of all spelling libraries, and implement certain features that may be lacking in any individual provider library. Everything should "just work" for any and every definition of "just working."
Enchant supports the following backends:
-
Aspell/Pspell (intends to replace Ispell)
-
Ispell (old as sin, could be interpreted as a defacto standard)
-
MySpell/Hunspell (an OOo projects, also used by Mozilla)
-
Uspell (primarily Yiddish, Hebrew, and Eastern European languages - hosted in AbiWord's CVS under the module "uspell")
-
Hspell (Hebrew)
-
AppleSpell (Mac OSX)
Instalacja/Konfiguracja
Spis treści
Wymagania
This version uses the functions of the » Enchant library by Dom Lachowicz. You need Enchant 1.2.4 or later.
Enchant also requires » Glib 2.6 or greater. Pre-compiled Windows libraries are available from » http://ftp.gnome.org/pub/gnome/binaries/win32/glib/.
Instalacja
This extension is bundled with PHP as of PHP 5.3.0. Before this time, enchant was a PECL extension. Users of versions prior to 5.3.0 may use the » PECL extension.
Provided the required libraries are installed, users of PHP 5.3.0 or later may enable enchant by adding the --with-enchant[=dir] option when compiling PHP.
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
There are two types of resources in this extension. The first one is the broker (backends manager) and the second is for the dictionary.
Stałe predefiniowane
To rozszerzenie nie posiada żadnych stałych.
Przykłady
Przykład #1 Enchant Usage Example
<?php
$tag = 'en_US';
$r = enchant_broker_init();
$bprovides = enchant_broker_describe($r);
echo "Current broker provides the following backend(s):\n";
print_r($bprovides);
$dicts = enchant_broker_list_dicts($r);
print_r($dicts);
if (enchant_broker_dict_exists($r,$tag)) {
$d = enchant_broker_request_dict($r, $tag);
$dprovides = enchant_dict_describe($d);
echo "dictionary $tag provides:\n";
$wordcorrect = enchant_dict_check($d, "soong");
print_r($dprovides);
if (!$wordcorrect) {
$suggs = enchant_dict_suggest($d, "soong");
echo "Suggestions for 'soong':";
print_r($suggs);
}
enchant_broker_free_dict($d);
} else {
}
enchant_broker_free($r);
?>
Enchant Funkcje
enchant_broker_describe
(PHP 5 >= 5.3.0, PECL enchant >= 0.1.0)
enchant_broker_describe — Enumerates the Enchant providers
Opis
$broker
)Enumerates the Enchant providers and tells you some rudimentary information about them. The same info is provided through phpinfo().
Parametry
-
broker -
Broker resource
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 List the backends provided by the given broker
<?php
$r = enchant_broker_init();
$bprovides = enchant_broker_describe($r);
echo "Current broker provides the following backend(s):\n";
print_r($bprovides);
?>
Powyższy przykład wyświetli coś podobnego do:
Current broker provides the following backend(s):
Array
(
[0] => Array
(
[name] => aspell
[desc] => Aspell Provider
[file] => /usr/lib/enchant/libenchant_aspell.so
)
[1] => Array
(
[name] => hspell
[desc] => Hspell Provider
[file] => /usr/lib/enchant/libenchant_hspell.so
)
[2] => Array
(
[name] => ispell
[desc] => Ispell Provider
[file] => /usr/lib/enchant/libenchant_ispell.so
)
[3] => Array
(
[name] => myspell
[desc] => Myspell Provider
[file] => /usr/lib/enchant/libenchant_myspell.so
)
)
enchant_broker_dict_exists
(PHP 5 >= 5.3.0, PECL enchant >= 0.1.0 )
enchant_broker_dict_exists — Whether a dictionary exists or not. Using non-empty tag
Opis
$broker
, string $tag
)Tells if a dictionary exists or not, using a non-empty tags
Parametry
-
broker -
Broker resource
-
tag -
non-empty tag in the LOCALE format, ex: us_US, ch_DE, etc.
Zwracane wartości
Returns TRUE when the tag exist or FALSE when not.
Przykłady
Przykład #1 A enchant_broker_dict_exists() example
<?php
$tag = 'en_US';
$r = enchant_broker_init();
if (enchant_broker_dict_exists($r,$tag)) {
echo $tag . " dictionary found.\n";
}
?>
enchant_broker_free_dict
(PHP 5 >= 5.3.0, PECL enchant >= 0.1.0 )
enchant_broker_free_dict — Free a dictionary resource
Opis
$dict
)Free a dictionary resource.
Parametry
-
dict -
Dictionary resource.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- enchant_broker_request_dict() - create a new dictionary using a tag
- enchant_broker_request_pwl_dict() - creates a dictionary using a PWL file
enchant_broker_free
(PHP 5 >= 5.3.0, PECL enchant >= 0.1.0 )
enchant_broker_free — Free the broker resource and its dictionnaries
Opis
$broker
)Free a broker resource with all its dictionaries.
Parametry
-
broker -
Broker resource
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
enchant_broker_get_error
(PHP 5 >= 5.3.0, PECL enchant >= 0.1.0 )
enchant_broker_get_error — Returns the last error of the broker
Opis
$broker
)Returns the last error which occurred in this broker.
Parametry
-
broker -
Broker resource.
Zwracane wartości
Return the msg string if an error was found or FALSE
enchant_broker_init
(PHP 5 >= 5.3.0, PECL enchant >= 0.1.0 )
enchant_broker_init — create a new broker object capable of requesting
Opis
Parametry
Zwracane wartości
Returns a broker resource on success or FALSE.
enchant_broker_list_dicts
(PHP 5 >= 5.3.0, PECL enchant >= 1.0.1)
enchant_broker_list_dicts — Returns a list of available dictionaries
Opis
Returns a list of available dictionaries with their details.
Parametry
-
broker -
Broker resource
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 List all available dictionaries for one broker
<?php
$r = enchant_broker_init();
$dicts = enchant_broker_list_dicts($r);
print_r($dicts);
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[0] => Array
(
[lang_tag] => de
[provider_name] => aspell
[provider_desc] => Aspell Provider
[provider_file] => /usr/lib/enchant/libenchant_aspell.so
)
[1] => Array
(
[lang_tag] => de_DE
[provider_name] => aspell
[provider_desc] => Aspell Provider
[provider_file] => /usr/lib/enchant/libenchant_aspell.so
)
[3] => Array
(
[lang_tag] => en
[provider_name] => aspell
[provider_desc] => Aspell Provider
[provider_file] => /usr/lib/enchant/libenchant_aspell.so
)
[4] => Array
(
[lang_tag] => en_GB
[provider_name] => aspell
[provider_desc] => Aspell Provider
[provider_file] => /usr/lib/enchant/libenchant_aspell.so
)
[5] => Array
(
[lang_tag] => en_US
[provider_name] => aspell
[provider_desc] => Aspell Provider
[provider_file] => /usr/lib/enchant/libenchant_aspell.so
)
[6] => Array
(
[lang_tag] => hi_IN
[provider_name] => myspell
[provider_desc] => Myspell Provider
[provider_file] => /usr/lib/enchant/libenchant_myspell.so
)
)
enchant_broker_request_dict
(PHP 5 >= 5.3.0, PECL enchant >= 0.1.0 )
enchant_broker_request_dict — create a new dictionary using a tag
Opis
$broker
, string $tag
)create a new dictionary using tag, the non-empty language tag you wish to request a dictionary for ("en_US", "de_DE", ...)
Parametry
-
broker -
Broker resource
-
tag -
A tag describing the locale, for example en_US, de_DE
Zwracane wartości
Returns a dictionary resource on success lub FALSE w przypadku niepowodzenia.
Przykłady
Przykład #1 A enchant_broker_request_dict() example
Check if a dictionary exists using enchant_broker_dict_exists() and request it.
<?php
$tag = 'en_US';
$broker = enchant_broker_init();
if (enchant_broker_dict_exists($broker,$tag)) {
$dict = enchant_broker_request_dict($r, $tag);
}
?>
Zobacz też:
- enchant_dict_describe() - Describes an individual dictionary
- enchant_broker_dict_exists() - Whether a dictionary exists or not. Using non-empty tag
- enchant_broker_free_dict() - Free a dictionary resource
enchant_broker_request_pwl_dict
(PHP 5 >= 5.3.0, PECL enchant >= 0.1.0 )
enchant_broker_request_pwl_dict — creates a dictionary using a PWL file
Opis
$broker
, string $filename
)Creates a dictionary using a PWL file. A PWL file is personal word file one word per line.
Parametry
-
broker -
Broker resource
-
filename -
Path to the PWL file.
Zwracane wartości
Returns a dictionary resource on success lub FALSE w przypadku niepowodzenia.
Zobacz też:
- enchant_dict_describe() - Describes an individual dictionary
- enchant_broker_dict_exists() - Whether a dictionary exists or not. Using non-empty tag
- enchant_broker_free_dict() - Free a dictionary resource
enchant_broker_set_ordering
(PHP 5 >= 5.3.0, PECL enchant >= 0.1.0 )
enchant_broker_set_ordering — Declares a preference of dictionaries to use for the language
Opis
$broker
, string $tag
, string $ordering
)Declares a preference of dictionaries to use for the language described/referred to by 'tag'. The ordering is a comma delimited list of provider names. As a special exception, the "*" tag can be used as a language tag to declare a default ordering for any language that does not explicitly declare an ordering.
Parametry
-
broker -
Broker resource
-
tag -
Language tag. The special "*" tag can be used as a language tag to declare a default ordering for any language that does not explicitly declare an ordering.
-
ordering -
Comma delimited list of provider names
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
enchant_dict_add_to_personal
(PHP 5 >= 5.3.0, PECL enchant >= 0.1.0 )
enchant_dict_add_to_personal — add a word to personal word list
Opis
$dict
, string $word
)Add a word to personal word list of the given dictionary.
Parametry
-
dict -
Dictionary resource
-
word -
The word to add
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Zobacz też:
- enchant_broker_request_pwl_dict() - creates a dictionary using a PWL file
- enchant_broker_request_dict() - create a new dictionary using a tag
enchant_dict_add_to_session
(PHP 5 >= 5.3.0, PECL enchant >= 0.1.0 )
enchant_dict_add_to_session — add 'word' to this spell-checking session
Opis
$dict
, string $word
)Add a word to the given dictionary. It will be added only for the active spell-checking session.
Parametry
-
dict -
Dictionary resource
-
word -
The word to add
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
enchant_dict_check
(PHP 5 >= 5.3.0, PECL enchant >= 0.1.0 )
enchant_dict_check — Check whether a word is correctly spelled or not
Opis
$dict
, string $word
)
If the word is correctly spelled return TRUE, otherwise return FALSE
Parametry
-
dict -
Dictionary resource
-
word -
The word to check
Zwracane wartości
Returns TRUE if the word is spelled correctly, FALSE if not.
enchant_dict_describe
(PHP 5 >= 5.3.0, PECL enchant >= 0.1.0 )
enchant_dict_describe — Describes an individual dictionary
Parametry
-
dict -
Dictinaray resource
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 A enchant_dict_describe() example
Check if a dictionary exists using enchant_broker_dict_exists() and show the detail of it.
<?php
$tag = 'en_US';
$broker = enchant_broker_init();
if (enchant_broker_dict_exists($broker,$tag)) {
$dict = enchant_broker_request_dict($r, $tag);
$dict_details = enchant_dict_describe($dict);
print_r($dict_details);
}
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[lang] => en_US
[name] => aspell
[desc] => Aspell Provider
[file] => /usr/lib/enchant/libenchant_aspell.so
)
enchant_dict_get_error
(PHP 5 >= 5.3.0, PECL enchant >= 0.1.0 )
enchant_dict_get_error — Returns the last error of the current spelling-session
Opis
$dict
)Returns the last error of the current spelling-session
Parametry
-
dict -
Dictinaray resource
Zwracane wartości
Returns the error message as string or FALSE if no error occurred.
enchant_dict_is_in_session
(PHP 5 >= 5.3.0, PECL enchant >= 0.1.0 )
enchant_dict_is_in_session — whether or not 'word' exists in this spelling-session
Opis
$dict
, string $word
)Tells whether or not a word already exists in the current session.
Parametry
-
dict -
Dictionary resource
-
word -
The word to lookup
Zwracane wartości
Returns TRUE if the word exists or FALSE
enchant_dict_quick_check
(PHP 5 >= 5.3.0, PECL enchant:0.2.0-1.0.1)
enchant_dict_quick_check — Check the word is correctly spelled and provide suggestions
Opis
$dict
, string $word
[, array &$suggestions
] )
If the word is correctly spelled return TRUE, otherwise return FALSE, if suggestions variable
is provided, fill it with spelling alternatives.
Parametry
-
dict -
Dictionary resource
-
word -
The word to check
-
suggestions -
If the word is not correctly spelled, this variable will contain an array of suggestions.
Zwracane wartości
Returns TRUE if the word is correctly spelled or FALSE
Przykłady
Przykład #1 A enchant_dict_quick_check() example
<?php
$tag = 'en_US';
$r = enchant_broker_init();
if (enchant_broker_dict_exists($r,$tag)) {
$d = enchant_broker_request_dict($r, $tag);
enchant_dict_quick_check($d, 'soong', $suggs);
print_r($suggs);
}
?>
Powyższy przykład wyświetli coś podobnego do:
Array
(
[0] => song
[1] => snog
[2] => soon
[3] => Sang
[4] => Sung
[5] => sang
[6] => sung
[7] => sponge
[8] => spongy
[9] => snag
[10] => snug
[11] => sonic
[12] => sing
[13] => songs
[14] => Son
[15] => Sonja
[16] => Synge
[17] => son
[18] => Sejong
[19] => sarong
[20] => sooner
[21] => Sony
[22] => sown
[23] => scone
[24] => song's
)
Zobacz też:
- enchant_dict_check() - Check whether a word is correctly spelled or not
- enchant_dict_suggest() - Will return a list of values if any of those pre-conditions are not met
enchant_dict_store_replacement
(PHP 5 >= 5.3.0, PECL enchant >= 0.1.0 )
enchant_dict_store_replacement — Add a correction for a word
Opis
$dict
, string $mis
, string $cor
)Add a correction for 'mis' using 'cor'. Notes that you replaced @mis with @cor, so it's possibly more likely that future occurrences of @mis will be replaced with @cor. So it might bump @cor up in the suggestion list.
Parametry
-
dict -
Dictionary resource
-
mis -
The work to fix
-
cor -
The correct word
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
enchant_dict_suggest
(PHP 5 >= 5.3.0, PECL enchant >= 0.1.0 )
enchant_dict_suggest — Will return a list of values if any of those pre-conditions are not met
Opis
$dict
, string $word
)
Parametry
-
dict -
Dictionary resource
-
word -
Word to use for the suggestions.
Zwracane wartości
Will returns an array of suggestions if the word is bad spelled.
Przykłady
Przykład #1 A enchant_dict_suggest() example
<?php
$tag = 'en_US';
$r = enchant_broker_init();
if (enchant_broker_dict_exists($r,$tag)) {
$d = enchant_broker_request_dict($r, $tag);
$wordcorrect = enchant_dict_check($d, "soong");
if (!$wordcorrect) {
$suggs = enchant_dict_suggest($d, "soong");
echo "Suggestions for 'soong':";
print_r($suggs);
}
enchant_broker_free_dict($d);
}
enchant_broker_free($r);
?>
Zobacz też:
- enchant_dict_check() - Check whether a word is correctly spelled or not
- enchant_dict_quick_check() - Check the word is correctly spelled and provide suggestions
Spis treści
- enchant_broker_describe — Enumerates the Enchant providers
- enchant_broker_dict_exists — Whether a dictionary exists or not. Using non-empty tag
- enchant_broker_free_dict — Free a dictionary resource
- enchant_broker_free — Free the broker resource and its dictionnaries
- enchant_broker_get_error — Returns the last error of the broker
- enchant_broker_init — create a new broker object capable of requesting
- enchant_broker_list_dicts — Returns a list of available dictionaries
- enchant_broker_request_dict — create a new dictionary using a tag
- enchant_broker_request_pwl_dict — creates a dictionary using a PWL file
- enchant_broker_set_ordering — Declares a preference of dictionaries to use for the language
- enchant_dict_add_to_personal — add a word to personal word list
- enchant_dict_add_to_session — add 'word' to this spell-checking session
- enchant_dict_check — Check whether a word is correctly spelled or not
- enchant_dict_describe — Describes an individual dictionary
- enchant_dict_get_error — Returns the last error of the current spelling-session
- enchant_dict_is_in_session — whether or not 'word' exists in this spelling-session
- enchant_dict_quick_check — Check the word is correctly spelled and provide suggestions
- enchant_dict_store_replacement — Add a correction for a word
- enchant_dict_suggest — Will return a list of values if any of those pre-conditions are not met
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Przykłady
- Enchant Funkcje
- enchant_broker_describe — Enumerates the Enchant providers
- enchant_broker_dict_exists — Whether a dictionary exists or not. Using non-empty tag
- enchant_broker_free_dict — Free a dictionary resource
- enchant_broker_free — Free the broker resource and its dictionnaries
- enchant_broker_get_error — Returns the last error of the broker
- enchant_broker_init — create a new broker object capable of requesting
- enchant_broker_list_dicts — Returns a list of available dictionaries
- enchant_broker_request_dict — create a new dictionary using a tag
- enchant_broker_request_pwl_dict — creates a dictionary using a PWL file
- enchant_broker_set_ordering — Declares a preference of dictionaries to use for the language
- enchant_dict_add_to_personal — add a word to personal word list
- enchant_dict_add_to_session — add 'word' to this spell-checking session
- enchant_dict_check — Check whether a word is correctly spelled or not
- enchant_dict_describe — Describes an individual dictionary
- enchant_dict_get_error — Returns the last error of the current spelling-session
- enchant_dict_is_in_session — whether or not 'word' exists in this spelling-session
- enchant_dict_quick_check — Check the word is correctly spelled and provide suggestions
- enchant_dict_store_replacement — Add a correction for a word
- enchant_dict_suggest — Will return a list of values if any of those pre-conditions are not met
FriBiDi
Instalacja/Konfiguracja
Spis treści
Instalacja
To rozszerzenie » PECL nie jest dołączane do PHP. Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/fribidi.
In order to use these functions you must compile PHP with Fribidi support by using the --with-fribidi[=DIR] configure option.
Windows users will enable php_fribidi.dll inside of php.ini in order to use these functions. DLL z tym rozszerzeniem PECL można pobrać zarówno ze strony » PHP Downloads lub z » http://pecl4win.php.net/
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane z PHP, lub załadowane dynamicznie przy starcie.
-
FRIBIDI_CHARSET_UTF8(integer) - Unicode
-
FRIBIDI_CHARSET_8859_6(integer) - Arabic
-
FRIBIDI_CHARSET_8859_8(integer) - Hebrew
-
FRIBIDI_CHARSET_CP1255(integer) - Hebrew/Yiddish
-
FRIBIDI_CHARSET_CP1256(integer) - Arabic
-
FRIBIDI_CHARSET_ISIRI_3342(integer) - Persian
-
FRIBIDI_CHARSET_CAP_RTL(integer) - Used for test purposes, will treat CAPS as non-English letters
-
FRIBIDI_RTL(integer) - Right to left
-
FRIBIDI_LTR(integer) - Left to right
-
FRIBIDI_AUTO(integer) - Autodetect the base direction
FriBiDi Funkcje
fribidi_log2vis
(PHP 4 >= 4.0.4 and PHP 4 <= 4.1.0, PECL fribidi >= 1.0)
fribidi_log2vis — Convert a logical string to a visual one
Opis
$str
, string $direction
, int $charset
)Converts a logical string to a visual one.
Parametry
-
str -
The logical string.
-
direction -
One of
FRIBIDI_RTL,FRIBIDI_LTRorFRIBIDI_AUTO. -
charset -
One of the FRIBIDI_CHARSET_XXX constants.
Zwracane wartości
Returns the visual string on success lub FALSE w przypadku niepowodzenia.
Spis treści
- fribidi_log2vis — Convert a logical string to a visual one
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- FriBiDi Funkcje
- fribidi_log2vis — Convert a logical string to a visual one
Gettext
Wstęp
The gettext functions implement an NLS (Native Language Support) API which can be used to internationalize your PHP applications. Please see the gettext documentation for your system for a thorough explanation of these functions or view the docs at » http://www.gnu.org/software/gettext/manual/gettext.html.
Instalacja/Konfiguracja
Spis treści
Wymagania
To use these functions you must download and install the GNU gettext package from » http://www.gnu.org/software/gettext/gettext.html
Instalacja
To include GNU gettext support in your PHP build you must add the option --with-gettext[=DIR] where DIR is the gettext install directory, defaults to /usr/local.
Konfiguracja wykonawcza
To rozszerzenie nie definiuje posiada żadnych dyrektyw konfiguracyjnych w pliku php.ini.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
To rozszerzenie nie posiada żadnych stałych.
Gettext Funkcje
bind_textdomain_codeset
(PHP 4 >= 4.2.0, PHP 5)
bind_textdomain_codeset — Specify the character encoding in which the messages from the DOMAIN message catalog will be returned
Opis
$domain
, string $codeset
)
With bind_textdomain_codeset(), you can set in which
encoding will be messages from domain returned by
gettext() and similar functions.
Parametry
-
domain -
The domain
-
codeset -
The code set
Zwracane wartości
A string on success.
bindtextdomain
(PHP 4, PHP 5)
bindtextdomain — Sets the path for a domain
Opis
$domain
, string $directory
)The bindtextdomain() function sets the path for a domain.
Parametry
-
domain -
The domain
-
directory -
The directory path
Zwracane wartości
The full pathname for the domain currently being set.
Przykłady
Przykład #1 bindtextdomain() example
<?php
$domain = 'myapp';
echo bindtextdomain($domain, '/usr/share/myapp/locale');
?>
Powyższy przykład wyświetli:
/usr/share/myapp/locale
dcgettext
(PHP 4, PHP 5)
dcgettext — Overrides the domain for a single lookup
Opis
$domain
, string $message
, int $category
)This function allows you to override the current domain for a single message lookup.
Parametry
-
domain -
The domain
-
message -
The message
-
category -
The category
Zwracane wartości
A string on success.
dcngettext
(PHP 4 >= 4.2.0, PHP 5)
dcngettext — Plural version of dcgettext
Opis
$domain
, string $msgid1
, string $msgid2
, int $n
, int $category
)This function allows you to override the current domain for a single plural message lookup.
Parametry
-
domain -
The domain
-
msgid1 -
-
msgid2 -
-
n -
-
category -
Zwracane wartości
A string on success.
dgettext
(PHP 4, PHP 5)
dgettext — Override the current domain
Opis
$domain
, string $message
)
The dgettext() function allows you to override
the current domain for a single message lookup.
Parametry
-
domain -
The domain
-
message -
The message
Zwracane wartości
A string on success.
dngettext
(PHP 4 >= 4.2.0, PHP 5)
dngettext — Plural version of dgettext
Opis
$domain
, string $msgid1
, string $msgid2
, int $n
)
The dngettext() function allows you to override
the current domain for a single plural message lookup.
Parametry
-
domain -
The domain
-
msgid1 -
-
msgid2 -
-
n -
Zwracane wartości
A string on success.
gettext
(PHP 4, PHP 5)
gettext — Lookup a message in the current domain
Opis
$message
)Looks up a message in the current domain.
Parametry
-
message -
The message being translated.
Zwracane wartości
Returns a translated string if one is found in the translation table, or the submitted message if not found.
Przykłady
Przykład #1 gettext()-check
<?php
// Set language to German
putenv('LC_ALL=de_DE');
setlocale(LC_ALL, 'de_DE');
// Specify location of translation tables
bindtextdomain("myPHPApp", "./locale");
// Choose domain
textdomain("myPHPApp");
// Translation is looking for in ./locale/de_DE/LC_MESSAGES/myPHPApp.mo now
// Print a test message
echo gettext("Welcome to My PHP Application");
// Or use the alias _() for gettext()
echo _("Have a nice day");
?>
Notatki
Informacja:
You may use the underscore character '_' as an alias to this function.
Informacja:
Setting a language isn't enough for some systems and the putenv() should be used to define the current locale.
ngettext
(PHP 4 >= 4.2.0, PHP 5)
ngettext — Plural version of gettext
Opis
$msgid1
, string $msgid2
, int $n
)The plural version of gettext(). Some languages have more than one form for plural messages dependent on the count.
Parametry
-
msgid1 -
-
msgid2 -
-
n -
Zwracane wartości
Returns correct plural form of message identified by
msgid1 and msgid2
for count n.
Przykłady
Przykład #1 ngettext() example
<?php
setlocale(LC_ALL, 'cs_CZ');
printf(ngettext("%d window", "%d windows", 1), 1); // 1 okno
printf(ngettext("%d window", "%d windows", 2), 2); // 2 okna
printf(ngettext("%d window", "%d windows", 5), 5); // 5 oken
?>
textdomain
(PHP 4, PHP 5)
textdomain — Sets the default domain
Opis
$text_domain
)This function sets the domain to search within when calls are made to gettext(), usually the named after an application.
Parametry
-
text_domain -
The new message domain, or
NULLto get the current setting without changing it
Zwracane wartości
If successful, this function returns the current message domain, after possibly changing it.
Spis treści
- bind_textdomain_codeset — Specify the character encoding in which the messages from the DOMAIN message catalog will be returned
- bindtextdomain — Sets the path for a domain
- dcgettext — Overrides the domain for a single lookup
- dcngettext — Plural version of dcgettext
- dgettext — Override the current domain
- dngettext — Plural version of dgettext
- gettext — Lookup a message in the current domain
- ngettext — Plural version of gettext
- textdomain — Sets the default domain
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- Gettext Funkcje
- bind_textdomain_codeset — Specify the character encoding in which the messages from the DOMAIN message catalog will be returned
- bindtextdomain — Sets the path for a domain
- dcgettext — Overrides the domain for a single lookup
- dcngettext — Plural version of dcgettext
- dgettext — Override the current domain
- dngettext — Plural version of dgettext
- gettext — Lookup a message in the current domain
- ngettext — Plural version of gettext
- textdomain — Sets the default domain
iconv
Wstęp
This module contains an interface to iconv character set conversion facility. With this module, you can turn a string represented by a local character set into the one represented by another character set, which may be the Unicode character set. Supported character sets depend on the iconv implementation of your system. Note that the iconv function on some systems may not work as you expect. In such case, it'd be a good idea to install the » GNU libiconv library. It will most likely end up with more consistent results.
Since PHP 5.0.0, this extension comes with various utility functions that help you to write multilingual scripts. Let's have a look at the following sections to explore the new features.
Instalacja/Konfiguracja
Spis treści
Wymagania
You will need nothing if the system you are using is one of the recent POSIX-compliant systems because standard C libraries that are supplied in them must provide iconv facility. Otherwise, you have to get the » libiconv library installed in your system.
Instalacja
This extension is enabled by default, although it may be disabled by compiling with --without-iconv .
The optional --with-iconv-dir directive is used to specify the location of iconv on the system that PHP is being compiled on, otherwise only the default locations are scanned.
Informacja: Note to PHP 4 users
Enabling this extension requires building with --with-iconv=[DIR] , or Windows users may enable by having iconv.dll available in the systems PATH, and php_iconv.dll enabled in php.ini.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| iconv.input_encoding | "ISO-8859-1" | PHP_INI_ALL | Available since PHP 4.0.5. |
| iconv.output_encoding | "ISO-8859-1" | PHP_INI_ALL | Available since PHP 4.0.5. |
| iconv.internal_encoding | "ISO-8859-1" | PHP_INI_ALL | Available since PHP 4.0.5. |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
Some systems (like IBM AIX) use "ISO8859-1" instead of "ISO-8859-1" so this value has to be used in configuration options and function parameters.
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
Since PHP 4.3.0 it is possible to identify at runtime which iconv implementation is adopted by this extension.
| Name | Type | Description |
|---|---|---|
ICONV_IMPL |
string | The implementation name |
ICONV_VERSION |
string | The implementation version |
Informacja:
Writing implementation-dependent scripts with these constants is strongly discouraged.
Since PHP 5.0.0, the following constants are also available:
| Name | Type | Description |
|---|---|---|
ICONV_MIME_DECODE_STRICT |
integer | A bitmask used for iconv_mime_decode() |
ICONV_MIME_DECODE_CONTINUE_ON_ERROR |
integer | A bitmask used for iconv_mime_decode() |
iconv Funkcje
Zobacz też:
See also GNU Recode functions.
iconv_get_encoding
(PHP 4 >= 4.0.5, PHP 5)
iconv_get_encoding — Pobiera aktualne ustawienia dla konwersji zestawu znaków
Opis
$typ
] )
Zwraca aktualne ustawienia funkcji ob_iconv_handler()
jako tablicę, lub FALSE jeśli się nie uda.
Patrz także: iconv_set_encoding() i ob_iconv_handler().
iconv_mime_decode_headers
(PHP 5)
iconv_mime_decode_headers — Decodes multiple MIME header fields at once
Opis
$encoded_headers
[, int $mode = 0
[, string $charset = ini_get("iconv.internal_encoding")
]] )Decodes multiple MIME header fields at once.
Parametry
-
encoded_headers -
The encoded headers, as a string.
-
mode -
modedetermines the behaviour in the event iconv_mime_decode_headers() encounters a malformed MIME header field. You can specify any combination of the following bitmasks.Bitmasks acceptable to iconv_mime_decode_headers() Value Constant Description 1 ICONV_MIME_DECODE_STRICT If set, the given header is decoded in full conformance with the standards defined in » RFC2047. This option is disabled by default because there are a lot of broken mail user agents that don't follow the specification and don't produce correct MIME headers. 2 ICONV_MIME_DECODE_CONTINUE_ON_ERROR If set, iconv_mime_decode_headers() attempts to ignore any grammatical errors and continue to process a given header. -
charset -
The optional
charsetparameter specifies the character set to represent the result by. If omitted, iconv.internal_encoding will be used.
Zwracane wartości
Returns an associative array that holds a whole set of
MIME header fields specified by
encoded_headers on success, or FALSE
if an error occurs during the decoding.
Each key of the return value represents an individual field name and the corresponding element represents a field value. If more than one field of the same name are present, iconv_mime_decode_headers() automatically incorporates them into a numerically indexed array in the order of occurrence.
Przykłady
Przykład #1 iconv_mime_decode_headers() example
<?php
$headers_string = <<<EOF
Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?=
To: example@example.com
Date: Thu, 1 Jan 1970 00:00:00 +0000
Message-Id: <example@example.com>
Received: from localhost (localhost [127.0.0.1]) by localhost
with SMTP id example for <example@example.com>;
Thu, 1 Jan 1970 00:00:00 +0000 (UTC)
(envelope-from example-return-0000-example=example.com@example.com)
Received: (qmail 0 invoked by uid 65534); 1 Thu 2003 00:00:00 +0000
EOF;
$headers = iconv_mime_decode_headers($headers_string, 0, "ISO-8859-1");
print_r($headers);
?>
Powyższy przykład wyświetli:
Array
(
[Subject] => Prüfung Prüfung
[To] => example@example.com
[Date] => Thu, 1 Jan 1970 00:00:00 +0000
[Message-Id] => <example@example.com>
[Received] => Array
(
[0] => from localhost (localhost [127.0.0.1]) by localhost with SMTP id example for <example@example.com>; Thu, 1 Jan 1970 00:00:00 +0000 (UTC) (envelope-from example-return-0000-example=example.com@example.com)
[1] => (qmail 0 invoked by uid 65534); 1 Thu 2003 00:00:00 +0000
)
)
Zobacz też:
- iconv_mime_decode() - Decodes a MIME header field
- mb_decode_mimeheader() - Decode string in MIME header field
- imap_mime_header_decode() - Decode MIME header elements
- imap_base64() - Decode BASE64 encoded text
- imap_qprint() - Convert a quoted-printable string to an 8 bit string
iconv_mime_decode
(PHP 5)
iconv_mime_decode — Decodes a MIME header field
Opis
$encoded_header
[, int $mode = 0
[, string $charset = ini_get("iconv.internal_encoding")
]] )Decodes a MIME header field.
Parametry
-
encoded_header -
The encoded header, as a string.
-
mode -
modedetermines the behaviour in the event iconv_mime_decode() encounters a malformed MIME header field. You can specify any combination of the following bitmasks.Bitmasks acceptable to iconv_mime_decode() Value Constant Description 1 ICONV_MIME_DECODE_STRICT If set, the given header is decoded in full conformance with the standards defined in » RFC2047. This option is disabled by default because there are a lot of broken mail user agents that don't follow the specification and don't produce correct MIME headers. 2 ICONV_MIME_DECODE_CONTINUE_ON_ERROR If set, iconv_mime_decode_headers() attempts to ignore any grammatical errors and continue to process a given header. -
charset -
The optional
charsetparameter specifies the character set to represent the result by. If omitted, iconv.internal_encoding will be used.
Zwracane wartości
Returns a decoded MIME field on success,
or FALSE if an error occurs during the decoding.
Przykłady
Przykład #1 iconv_mime_decode() example
<?php
// This yields "Subject: Prüfung Prüfung"
echo iconv_mime_decode("Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?=",
0, "ISO-8859-1");
?>
Zobacz też:
- iconv_mime_decode_headers() - Decodes multiple MIME header fields at once
- mb_decode_mimeheader() - Decode string in MIME header field
- imap_mime_header_decode() - Decode MIME header elements
- imap_base64() - Decode BASE64 encoded text
- imap_qprint() - Convert a quoted-printable string to an 8 bit string
iconv_mime_encode
(PHP 5)
iconv_mime_encode — Composes a MIME header field
Opis
$field_name
, string $field_value
[, array $preferences = NULL
] )Composes and returns a string that represents a valid MIME header field, which looks like the following:
Subject: =?ISO-8859-1?Q?Pr=FCfung_f=FCr?= Entwerfen von einer MIME kopfzeile
Parametry
-
field_name -
The field name.
-
field_value -
The field value.
-
preferences -
You can control the behaviour of iconv_mime_encode() by specifying an associative array that contains configuration items to the optional third parameter
preferences. The items supported by iconv_mime_encode() are listed below. Note that item names are treated case-sensitive.Configuration items supported by iconv_mime_encode() Item Type Description Default value Example scheme string Specifies the method to encode a field value by. The value of this item may be either "B" or "Q", where "B" stands for base64 encoding scheme and "Q" stands for quoted-printable encoding scheme. B B input-charset string Specifies the character set in which the first parameter field_nameand the second parameterfield_valueare presented. If not given, iconv_mime_encode() assumes those parameters are presented to it in the iconv.internal_encoding ini setting.iconv.internal_encoding ISO-8859-1 output-charset string Specifies the character set to use to compose the MIME header. iconv.internal_encoding UTF-8 line-length integer Specifies the maximum length of the header lines. The resulting header is "folded" to a set of multiple lines in case the resulting header field would be longer than the value of this parameter, according to » RFC2822 - Internet Message Format. If not given, the length will be limited to 76 characters. 76 996 line-break-chars string Specifies the sequence of characters to append to each line as an end-of-line sign when "folding" is performed on a long header field. If not given, this defaults to "\r\n" (CR LF). Note that this parameter is always treated as an ASCII string regardless of the value of input-charset. \r\n \n
Zwracane wartości
Returns an encoded MIME field on success,
or FALSE if an error occurs during the encoding.
Przykłady
Przykład #1 iconv_mime_encode() example
<?php
$preferences = array(
"input-charset" => "ISO-8859-1",
"output-charset" => "UTF-8",
"line-length" => 76,
"line-break-chars" => "\n"
);
$preferences["scheme"] = "Q";
// This yields "Subject: =?UTF-8?Q?Pr=C3=BCfung=20Pr=C3=BCfung?="
echo iconv_mime_encode("Subject", "Prüfung Prüfung", $preferences);
$preferences["scheme"] = "B";
// This yields "Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?="
echo iconv_mime_encode("Subject", "Prüfung Prüfung", $preferences);
?>
Zobacz też:
- imap_binary() - Convert an 8bit string to a base64 string
- mb_encode_mimeheader() - Encode string for MIME header
- imap_8bit() - Convert an 8bit string to a quoted-printable string
- quoted_printable_encode() - Convert a 8 bit string to a quoted-printable string
iconv_set_encoding
(PHP 4 >= 4.0.5, PHP 5)
iconv_set_encoding — Ustawia aktualne ustawienia dla konwersji zestawu znaków
Opis
$typ
, string $zestaw_znaków
)
Zmienia wartość zmiennej typ na
zestaw_znaków. Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Argument typ może przyjmować następujące wartości:
- input_encoding
- output_encoding
- internal_encoding
Przykład #1 przykład iconv_set_encoding():
iconv_set_encoding("internal_encoding", "UTF-8");
iconv_set_encoding("output_encoding", "ISO-8859-1");
Patrz także: iconv_get_encoding() i ob_iconv_handler().
iconv_strlen
(PHP 5)
iconv_strlen — Returns the character count of string
Opis
$str
[, string $charset = ini_get("iconv.internal_encoding")
] )
In contrast to strlen(),
iconv_strlen() counts the occurrences of characters
in the given byte sequence str on the basis of
the specified character set, the result of which is not necessarily
identical to the length of the string in byte.
Parametry
-
str -
The string.
-
charset -
If
charsetparameter is omitted,stris assumed to be encoded in iconv.internal_encoding.
Zwracane wartości
Returns the character count of str, as an integer.
iconv_strpos
(PHP 5)
iconv_strpos — Finds position of first occurrence of a needle within a haystack
Opis
$haystack
, string $needle
[, int $offset = 0
[, string $charset = ini_get("iconv.internal_encoding")
]] )
Finds position of first occurrence of a needle
within a haystack.
In contrast to strpos(), the return value of
iconv_strpos() is the number of characters that
appear before the needle, rather than the offset in bytes to the
position where the needle has been found. The characters are counted
on the basis of the specified character set charset.
Parametry
-
haystack -
The entire string.
-
needle -
The searched substring.
-
offset -
The optional
offsetparameter specifies the position from which the search should be performed. -
charset -
If
charsetparameter is omitted,stringare assumed to be encoded in iconv.internal_encoding.
If haystack or needle is
not a string, it is converted to a string and applied as the ordinal
value of a character.
Zwracane wartości
Returns the numeric position of the first occurrence of
needle in haystack.
If needle is not found,
iconv_strpos() will return FALSE.
Ta funkcja może
zwrócić Boolean FALSE, ale może też zwrócić wartość innego typu niż Boolean, która oznacza
wartość FALSE, takie jak 0 lub
"". Aby uzyskać więcej informacji proszę zapoznać się z rozdziałem Typy logiczne.
Można używać operatora ===
do testowania zwracanych wartości przez tę
funkcję.
Zobacz też:
- strpos() - Find the position of the first occurrence of a substring in a string
- iconv_strrpos() - Finds the last occurrence of a needle within a haystack
- mb_strpos() - Find position of first occurrence of string in a string
iconv_strrpos
(PHP 5)
iconv_strrpos — Finds the last occurrence of a needle within a haystack
Opis
$haystack
, string $needle
[, string $charset = ini_get("iconv.internal_encoding")
] )
Finds the last occurrence of a needle
within a haystack.
In contrast to strrpos(), the return value of
iconv_strrpos() is the number of characters that
appear before the needle, rather than the offset in bytes to the
position where the needle has been found. The characters are counted
on the basis of the specified character set charset.
Parametry
-
haystack -
The entire string.
-
needle -
The searched substring.
-
charset -
If
charsetparameter is omitted,stringare assumed to be encoded in iconv.internal_encoding.
If haystack or needle is
not a string, it is converted to a string and applied as the ordinal
value of a character.
Zwracane wartości
Returns the numeric position of the last occurrence of
needle in haystack.
If needle is not found,
iconv_strrpos() will return FALSE.
Ta funkcja może
zwrócić Boolean FALSE, ale może też zwrócić wartość innego typu niż Boolean, która oznacza
wartość FALSE, takie jak 0 lub
"". Aby uzyskać więcej informacji proszę zapoznać się z rozdziałem Typy logiczne.
Można używać operatora ===
do testowania zwracanych wartości przez tę
funkcję.
Zobacz też:
- strrpos() - Znajduje pozycję ostatniego wystąpienia znaku w ciągu znaków
- iconv_strpos() - Finds position of first occurrence of a needle within a haystack
- mb_strrpos() - Find position of last occurrence of a string in a string
iconv_substr
(PHP 5)
iconv_substr — Cut out part of a string
Opis
$str
, int $offset
[, int $length = iconv_strlen($str, $charset)
[, string $charset = ini_get("iconv.internal_encoding")
]] )
Cuts a portion of str specified by the
offset and length parameters.
Parametry
-
str -
The original string.
-
offset -
If
offsetis non-negative, iconv_substr() cuts the portion out ofstrbeginning atoffset'th character, counting from zero.If
offsetis negative, iconv_substr() cuts out the portion beginning at the position,offsetcharacters away from the end ofstr. -
length -
If
lengthis given and is positive, the return value will contain at mostlengthcharacters of the portion that begins atoffset(depending on the length ofstring).If negative
lengthis passed, iconv_substr() cuts the portion out ofstrfrom theoffset'th character up to the character that islengthcharacters away from the end of the string. In caseoffsetis also negative, the start position is calculated beforehand according to the rule explained above. -
charset -
If
charsetparameter is omitted,stringare assumed to be encoded in iconv.internal_encoding.Note that
offsetandlengthparameters are always deemed to represent offsets that are calculated on the basis of the character set determined bycharset, whilst the counterpart substr() always takes these for byte offsets.
Zwracane wartości
Returns the portion of str specified by the
offset and length parameters.
If str is shorter than offset
characters long, FALSE will be returned.
Zobacz też:
- substr() - Return part of a string
- mb_substr() - Get part of string
- mb_strcut() - Get part of string
iconv
(PHP 4 >= 4.0.5, PHP 5)
iconv — Konwertuje łańcuch znaków do innego zestawu znaków
Opis
$zestaw_wejściowy
, string $zestaw_docelowy
, string $łańcuch
)
Konwertuje łańcuch znaków łańcuch, zakodowany
w zestaw_wejściowy na łańcuch znaków zakodowany
w zestaw_docelowy. Zwraca skonwertowany łańcuch
lub FALSE, jeśli konwersja się nie uda.
Przykład #1 przykład iconv():
echo iconv("ISO-8859-1","UTF-8","To jest test.");
echo iconv("ISO-8859-2","UTF-8","Zażółć gęślą jaźń");
ob_iconv_handler
(PHP 4 >= 4.0.5, PHP 5)
ob_iconv_handler — Konwersja kodowania znaków jako uchwyt buforu wyjścia
Opis
$zawartość
, int $status
)
Konwertuje string zapisany w internal_encoding do
output_encoding.
internal_encoding i
output_encoding powinny zostać zdefiniowane przez
iconv_set_encoding() lub w pliku konfiguracyjnym
php.ini.
Przykład #1 przykład ob_iconv_handler():
<?php
ob_start("ob_iconv_handler"); // rozpocznij buforowanie wyjścia
?>
Patrz także: iconv_get_encoding(), iconv_set_encoding() i funkcje output-control.
Spis treści
- iconv_get_encoding — Pobiera aktualne ustawienia dla konwersji zestawu znaków
- iconv_mime_decode_headers — Decodes multiple MIME header fields at once
- iconv_mime_decode — Decodes a MIME header field
- iconv_mime_encode — Composes a MIME header field
- iconv_set_encoding — Ustawia aktualne ustawienia dla konwersji zestawu znaków
- iconv_strlen — Returns the character count of string
- iconv_strpos — Finds position of first occurrence of a needle within a haystack
- iconv_strrpos — Finds the last occurrence of a needle within a haystack
- iconv_substr — Cut out part of a string
- iconv — Konwertuje łańcuch znaków do innego zestawu znaków
- ob_iconv_handler — Konwersja kodowania znaków jako uchwyt buforu wyjścia
- Wstęp
- Instalacja/Konfiguracja
- Stałe predefiniowane
- iconv Funkcje
- iconv_get_encoding — Pobiera aktualne ustawienia dla konwersji zestawu znaków
- iconv_mime_decode_headers — Decodes multiple MIME header fields at once
- iconv_mime_decode — Decodes a MIME header field
- iconv_mime_encode — Composes a MIME header field
- iconv_set_encoding — Ustawia aktualne ustawienia dla konwersji zestawu znaków
- iconv_strlen — Returns the character count of string
- iconv_strpos — Finds position of first occurrence of a needle within a haystack
- iconv_strrpos — Finds the last occurrence of a needle within a haystack
- iconv_substr — Cut out part of a string
- iconv — Konwertuje łańcuch znaków do innego zestawu znaków
- ob_iconv_handler — Konwersja kodowania znaków jako uchwyt buforu wyjścia
Internationalization Functions
Wstęp
Internationalization extension (further is referred as Intl) is a wrapper for » ICU library, enabling PHP programmers to perform » UCA-conformant collation and date/time/number/currency formatting in their scripts.
It tends to closely follow ICU APIs, so that people having experience working with ICU in either C/C++ or Java could easily use the PHP API. Also, this way ICU documentation would be useful to understand various ICU functions.
Intl consists of several modules, each of them exposes the corresponding ICU API:
- Collator: provides string comparison capability with support for appropriate locale-sensitive sort orderings.
- Number Formatter: allows to display number according to the localized format or given pattern or set of rules, and to parse strings into numbers.
- Message Formatter: allows to create messages incorporating data (such as numbers or dates) formatted according to given pattern and locale rules, and parse messages extracting data from them.
- Normalizer: provides a function to transform text into one of the Unicode normalization forms, and provides a routine to test if a given string is already normalized.
- Locale: provides interaction with locale identifiers in the form of functions to get subtags from locale identifier; parse, compose, match(lookup and filter) locale identifiers.
Instalacja/Konfiguracja
Spis treści
Wymagania
To build the extension you need to install the » ICU library of version 3.6+.
This extension is bundled with PHP as of PHP version 5.3.0. Alternatively, the PECL version of this extension may be used with all PHP versions greater than 5.2.0 (5.2.4+ recommended).
Instalacja
This extension may be installed using the bundled version as of PHP 5.3.0, or as a PECL extension as of PHP 5.2.0. In other words, there are two methods to install the intl extension.
Informacje na temat instalacji tego rozszerzenia PECL można znaleźć w podręczniku w rozdziale zatytułowanym Instalacja rozszerzeń PECL. Dodatkowe informacje, takie jak nowe wersje, pliki do pobrania, pliki źródłowe, informacje o opiekunach czy rejestr zmian, można znaleźć tutaj: » http://pecl.php.net/package/intl.
Alternatively, --enable-intl will enable the bundled version while compiling PHP.
If your ICU is installed to a non-standard directory then you might want to
specify its location in
LD_LIBRARY_PATH
environment variable so that dynamic linker can find it:
Otherwise, if PHP and ICU are installed to their default locations, then the additional options to `configure' are not needed.
Konfiguracja wykonawcza
Na działanie tych funkcji wpływają ustawienia zawarte w pliku php.ini.
| Nazwa | Domyślnie | Możliwość zmian | Rejestr zmian |
|---|---|---|---|
| intl.default_locale | PHP_INI_ALL |
Oto krótkie wyjaśnienie dyrektyw konfiguracji.
-
intl.default_localestring -
Typy zasobów
To rozszerzenie nie posiada żadnych rodzajów zasobów.
Stałe predefiniowane
-
INTL_MAX_LOCALE_LEN(integer) - Limit on locale length, set to 80 in PHP code. Locale names longer than this limit will not be accepted.
-
IDNA_DEFAULT(integer) - Prohibit processing of unassigned codepoints in the input for IDN functions and do not check if the input conforms to domain name ASCII rules.
-
IDNA_ALLOW_UNASSIGNED(integer) - Allow processing of unassigned codepoints in the input for IDN functions.
-
IDNA_USE_STD3_RULES(integer) - Check if the input for IDN functions conforms to domain name ASCII rules.
-
IDNA_CHECK_BIDI(integer) - Check whether the input conforms to the BiDi rules. Ignored by the IDNA2003 implementation, which always performs this check.
-
IDNA_CHECK_CONTEXTJ(integer) - Check whether the input conforms to the CONTEXTJ rules. Ignored by the IDNA2003 implementation, as this check is new in IDNA2008.
-
IDNA_NONTRANSITIONAL_TO_ASCII(integer) - Option for nontransitional processing in idn_to_ascii(). Transitional processing is activated by default. This option is ignored by the IDNA2003 implementation.
-
IDNA_NONTRANSITIONAL_TO_UNICODE(integer) - Option for nontransitional processing in idn_to_utf8(). Transitional processing is activated by default. This option is ignored by the IDNA2003 implementation.
-
INTL_IDNA_VARIANT_2003(integer) - Use IDNA 2003 algorithm in idn_to_utf8() and idn_to_ascii(). This is the default.
-
INTL_IDNA_VARIANT_UTS46(integer) - Use UTS #46 algorithm in idn_to_utf8() and idn_to_ascii().
-
IDNA_ERROR_EMPTY_LABEL(integer)
IDNA_ERROR_LABEL_TOO_LONG(integer)
IDNA_ERROR_DOMAIN_NAME_TOO_LONG(integer)
IDNA_ERROR_LEADING_HYPHEN(integer)
IDNA_ERROR_TRAILING_HYPHEN(integer)
IDNA_ERROR_HYPHEN_3_4(integer)
IDNA_ERROR_LEADING_COMBINING_MARK(integer)
IDNA_ERROR_DISALLOWED(integer)
IDNA_ERROR_PUNYCODE(integer)
IDNA_ERROR_LABEL_HAS_DOT(integer)
IDNA_ERROR_INVALID_ACE_LABEL(integer)
IDNA_ERROR_BIDI(integer)
IDNA_ERROR_CONTEXTJ(integer) - Errors reported in a bitset returned by the UTS #46 algorithm in idn_to_utf8() and idn_to_ascii().
Przykłady
Spis treści
Basic usage of this extension
Each module provides two kind of APIs: a procedural one and an object oriented one. Both are actually identical and described in the corresponding document.
Informacja:
All input strings must be in UTF-8 encoding. All output strings are also in UTF-8.
Przykład #1 Example of using the procedural API
<?php
$coll = collator_create('en_US');
$result = collator_compare($coll, "string#1", "string#2");
?>
Przykład #2 Example of using the object-oriented API
<?php
$coll = new Collator('en_US');
$al = $coll->getLocale(Locale::ACTUAL_LOCALE);
echo "Actual locale: $al\n";
$formatter = new NumberFormatter('en_US', NumberFormatter::DECIMAL);
echo $formatter->format(1234567);
?>
The Collator class
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Wstęp
Provides string comparison capability with support for appropriate locale-sensitive sort orderings.
Krótki opis klasy
Stałe predefiniowane
-
Collator::FRENCH_COLLATION(integer) -
Sort strings with different accents from the back of the string. This attribute is automatically set to On for the French locales and a few others. Users normally would not need to explicitly set this attribute. There is a string comparison performance cost when it is set On, but sort key length is unaffected. Possible values are:
Collator::ONCollator::OFF(default)Collator::DEFAULT_VALUE
Przykład #1 FRENCH_COLLATION rules
- F=OFF cote < coté < côte < côté
- F=ON cote < côte < coté < côté
-
Collator::ALTERNATE_HANDLING(integer) -
The Alternate attribute is used to control the handling of the so called variable characters in the UCA: whitespace, punctuation and symbols. If Alternate is set to NonIgnorable (N), then differences among these characters are of the same importance as differences among letters. If Alternate is set to Shifted (S), then these characters are of only minor importance. The Shifted value is often used in combination with Strength set to Quaternary. In such a case, whitespace, punctuation, and symbols are considered when comparing strings, but only if all other aspects of the strings (base letters, accents, and case) are identical. If Alternate is not set to Shifted, then there is no difference between a Strength of 3 and a Strength of 4. For more information and examples, see Variable_Weighting in the » UCA. The reason the Alternate values are not simply On and Off is that additional Alternate values may be added in the future. The UCA option Blanked is expressed with Strength set to 3, and Alternate set to Shifted. The default for most locales is NonIgnorable. If Shifted is selected, it may be slower if there are many strings that are the same except for punctuation; sort key length will not be affected unless the strength level is also increased.
Possible values are:
Collator::NON_IGNORABLE(default)Collator::SHIFTEDCollator::DEFAULT_VALUE
Przykład #2 ALTERNATE_HANDLING rules
- S=3, A=N di Silva < Di Silva < diSilva < U.S.A. < USA
- S=3, A=S di Silva = diSilva < Di Silva < U.S.A. = USA
- S=4, A=S di Silva < diSilva < Di Silva < U.S.A. < USA
-
Collator::CASE_FIRST(integer) -
The Case_First attribute is used to control whether uppercase letters come before lowercase letters or vice versa, in the absence of other differences in the strings. The possible values are Uppercase_First (U) and Lowercase_First (L), plus the standard Default and Off. There is almost no difference between the Off and Lowercase_First options in terms of results, so typically users will not use Lowercase_First: only Off or Uppercase_First. (People interested in the detailed differences between X and L should consult the Collation Customization). Specifying either L or U won't affect string comparison performance, but will affect the sort key length.
Possible values are:
Collator::OFF(default)Collator::LOWER_FIRSTCollator::UPPER_FIRSTCollator:DEFAULT
Przykład #3 CASE_FIRST rules
- C=X or C=L "china" < "China" < "denmark" < "Denmark"
- C=U "China" < "china" < "Denmark" < "denmark"
-
Collator::CASE_LEVEL(integer) -
The Case_Level attribute is used when ignoring accents but not case. In such a situation, set Strength to be Primary, and Case_Level to be On. In most locales, this setting is Off by default. There is a small string comparison performance and sort key impact if this attribute is set to be On.
Possible values are:
Collator::OFF(default)Collator::ONCollator::DEFAULT_VALUE
Przykład #4 CASE_LEVEL rules
- S=1, E=X role = Role = rôle
- S=1, E=O role = rôle < Role
-
Collator::NORMALIZATION_MODE(integer) -
The Normalization setting determines whether text is thoroughly normalized or not in comparison. Even if the setting is off (which is the default for many locales), text as represented in common usage will compare correctly (for details, see UTN #5). Only if the accent marks are in noncanonical order will there be a problem. If the setting is On, then the best results are guaranteed for all possible text input. There is a medium string comparison performance cost if this attribute is On, depending on the frequency of sequences that require normalization. There is no significant effect on sort key length. If the input text is known to be in NFD or NFKD normalization forms, there is no need to enable this Normalization option.
Possible values are:
Collator::OFF(default)Collator::ONCollator::DEFAULT_VALUE
-
Collator::STRENGTH(integer) -
The ICU Collation Service supports many levels of comparison (named "Levels", but also known as "Strengths"). Having these categories enables ICU to sort strings precisely according to local conventions. However, by allowing the levels to be selectively employed, searching for a string in text can be performed with various matching conditions. For more detailed information, see collator_set_strength() chapter.
Possible values are:
Collator::PRIMARYCollator::SECONDARYCollator::TERTIARY(default)Collator::QUATERNARYCollator::IDENTICALCollator::DEFAULT_VALUE
-
Collator::HIRAGANA_QUATERNARY_MODE(integer) -
Compatibility with JIS x 4061 requires the introduction of an additional level to distinguish Hiragana and Katakana characters. If compatibility with that standard is required, then this attribute should be set On, and the strength set to Quaternary. This will affect sort key length and string comparison string comparison performance.
Possible values are:
Collator::OFF(default)Collator::ONCollator::DEFAULT_VALUE
-
Collator::NUMERIC_COLLATION(integer) -
When turned on, this attribute generates a collation key for the numeric value of substrings of digits. This is a way to get '100' to sort AFTER '2'.
Possible values are:
Collator::OFF(default)Collator::ONCollator::DEFAULT_VALUE
-
Collator::DEFAULT_VALUE(integer) -
Collator::PRIMARY(integer) -
Collator::SECONDARY(integer) -
Collator::TERTIARY(integer) -
Collator::DEFAULT_STRENGTH(integer) -
Collator::QUATERNARY(integer) -
Collator::IDENTICAL(integer) -
Collator::OFF(integer) -
Collator::ON(integer) -
Collator::SHIFTED(integer) -
Collator::NON_IGNORABLE(integer) -
Collator::LOWER_FIRST(integer) -
Collator::UPPER_FIRST(integer)
Collator::asort
collator_asort
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Collator::asort -- collator_asort — Sort array maintaining index association
Opis
Styl obiektowy
&$arr
[, int $sort_flag
] )Styl proceduralny
This function sorts an array such that array indices maintain their correlation with the array elements they are associated with. This is used mainly when sorting associative arrays where the actual element order is significant. Array elements will have sort order according to current locale rules.
Equivalent to standard PHP asort().
Parametry
-
coll -
Collator object.
-
arr -
Array of strings to sort.
-
sort_flag -
Optional sorting type, one of the following:
-
Collator::SORT_REGULAR- compare items normally (don't change types) -
Collator::SORT_NUMERIC- compare items numerically -
Collator::SORT_STRING- compare items as strings
Default $sort_flag value is
Collator::SORT_REGULAR. It is also used if an invalid $sort_flag value has been specified. -
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 collator_asort()example
<?php
$coll = collator_create( 'en_US' );
$arr = array(
'a' => '100',
'b' => '50',
'c' => '7'
);
collator_asort( $coll, $arr, Collator::SORT_NUMERIC );
var_export( $arr );
collator_asort( $coll, $arr, Collator::SORT_STRING );
var_export( $arr );
?>
Powyższy przykład wyświetli:
array ( 'c' => '7', 'b' => '50', 'a' => '100', )array ( 'a' => '100', 'b' => '50', 'c' => '7', )
Zobacz też:
- Collator constants
- collator_sort() - Sort array using specified collator
- collator_sort_with_sort_keys() - Sort array using specified collator and sort keys
Collator::compare
collator_compare
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Collator::compare -- collator_compare — Compare two Unicode strings
Opis
Styl obiektowy
$str1
, string $str2
)Styl proceduralny
Compare two Unicode strings according to collation rules.
Parametry
-
coll -
Collator object.
-
str1 -
The first string to compare.
-
str2 -
The second string to compare.
Zwracane wartości
Return comparison result:
-
1 if
str1is greater thanstr2; -
0 if
str1is equal tostr2; -
-1 if
str1is less thanstr2.
FALSE
is returned.
Ta funkcja może
zwrócić Boolean FALSE, ale może też zwrócić wartość innego typu niż Boolean, która oznacza
wartość FALSE, takie jak 0 lub
"". Aby uzyskać więcej informacji proszę zapoznać się z rozdziałem Typy logiczne.
Można używać operatora ===
do testowania zwracanych wartości przez tę
funkcję.
Przykłady
Przykład #1 collator_compare()example
<?php
$s1 = 'Hello';
$s2 = 'hello';
$coll = collator_create( 'en_US' );
$res = collator_compare( $coll, $s1, $s2 );
if ($res === false) {
echo collator_get_error_message( $coll );
} else if( $res > 0 ) {
echo "s1 is greater than s2\n";
} else if( $res < 0 ) {
echo "s1 is less than s2\n";
} else {
echo "s1 is equal to s2\n";
}
?>
Powyższy przykład wyświetli:
s1 is greater than s2
Collator::__construct
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Collator::__construct — Create a collator
Opis
$locale
)Creates a new instance of Collator.
Parametry
-
locale -
The locale whose collation rules should be used. Special values for locales can be passed in - if null is passed for the locale, the default locale collation rules will be used. If empty string ("") or "root" are passed, UCA rules will be used.
The Locale attribute is typically the most important attribute for correct sorting and matching, according to the user expectations in different countries and regions. The default » UCA ordering will only sort a few languages such as Dutch and Portuguese correctly ("correctly" meaning according to the normal expectations for users of the languages). Otherwise, you need to supply the locale to UCA in order to properly collate text for a given language. Thus a locale needs to be supplied so as to choose a collator that is correctly tailored for that locale. The choice of a locale will automatically preset the values for all of the attributes to something that is reasonable for that locale. Thus most of the time the other attributes do not need to be explicitly set. In some cases, the choice of locale will make a difference in string comparison performance and/or sort key length.
Zwracane wartości
Returns Collator instance.
Błędy/Wyjątki
Returns an "empty" object on error. You can use intl_get_error_code() and/or intl_get_error_message() to know what happened.
Przykłady
Przykład #1 Collator::__construct() example
<?php
$coll = new Collator( 'en_CA' );
?>
Collator::create
collator_create
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Collator::create -- collator_create — Create a collator
Opis
Styl obiektowy
Styl proceduralny
The strings will be compared using the options already specified.
Parametry
-
locale -
The locale containing the required collation rules. Special values for locales can be passed in - if null is passed for the locale, the default locale collation rules will be used. If empty string ("") or "root" are passed, » UCA rules will be used.
Zwracane wartości
Return new instance of Collator object, or NULL
on error.
Przykłady
Przykład #1 collator_create() example
<?php
$coll = collator_create( 'en_US' );
if( !isset( $coll ) ) {
printf( "Collator creation failed: %s\n", intl_get_error_message() );
exit( 1 );
}
?>
Collator::getAttribute
collator_get_attribute
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Collator::getAttribute -- collator_get_attribute — Get collation attribute value
Opis
Styl obiektowy
$attr
)Styl proceduralny
Get a value of an integer collator attribute.
Zwracane wartości
Attribute value, or boolean FALSE on error.
Przykłady
Przykład #1 collator_get_attribute() example
<?php
$coll = collator_create( 'en_CA' );
$val = collator_get_attribute( $coll, Collator::NUMERIC_COLLATION );
if( $val === false )
{
// Handle error.
}
?>
Zobacz też:
- Collator constants
- collator_set_attribute() - Set collation attribute
- collator_get_strength() - Get current collation strength
Collator::getErrorCode
collator_get_error_code
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Collator::getErrorCode -- collator_get_error_code — Get collator's last error code
Opis
Styl obiektowy
Styl proceduralny
Zwracane wartości
Error code returned by the last Collator API function call.
Przykłady
Przykład #1 collator_get_error_code() example
<?php
$coll = collator_create( 'en_US' );
if( collator_get_attribute( $coll, Collator::FRENCH_COLLATION ) === false )
handle_error( collator_get_error_code() );
?>
Collator::getErrorMessage
collator_get_error_message
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Collator::getErrorMessage -- collator_get_error_message — Get text for collator's last error code
Opis
Styl obiektowy
Styl proceduralny
Retrieves the message for the last error.
Zwracane wartości
Description of an error occurred in the last Collator API function call.
Przykłady
Przykład #1 collator_get_error_message() example
<?php
$coll = collator_create( 'lt' );
if( collator_compare( $coll, 'y', 'k' ) === false ) {
echo collator_get_error_message( $coll );
}
?>
Collator::getLocale
collator_get_locale
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Collator::getLocale -- collator_get_locale — Get the locale name of the collator
Opis
Styl obiektowy
$type
] )Styl proceduralny
Get collector locale name.
Parametry
-
coll -
Collator object.
-
type -
You can choose between valid and actual locale (
Locale::VALID_LOCALEandLocale::ACTUAL_LOCALE, respectively). The default is the actual locale.
Zwracane wartości
Real locale name from which the collation data comes. If the collator was
instantiated from rules or an error occurred, returns
boolean FALSE.
Przykłady
Przykład #1 collator_get_locale() example
<?php
$coll = collator_create( 'en_US_California' );
$res_val = collator_get_locale( $coll, Locale::VALID_LOCALE );
$res_act = collator_get_locale( $coll, Locale::ACTUAL_LOCALE );
printf( "Valid locale name: %s\nActual locale name: %s\n",
$res_req, $res_val, $res_act );
?>
Powyższy przykład wyświetli:
Requested locale name: en_US_California Valid locale name: en_US Actual locale name: en
Collator::getSortKey
collator_get_sort_key
(No version information available, might only be in SVN)
Collator::getSortKey -- collator_get_sort_key — Get sorting key for a string
Opis
Styl obiektowy
$str
)Styl proceduralny
Return collation key for a string.
Zwracane wartości
Returns the collation key for the string. Collation keys can be compared directly instead of strings.
Ta funkcja może
zwrócić Boolean FALSE, ale może też zwrócić wartość innego typu niż Boolean, która oznacza
wartość FALSE, takie jak 0 lub
"". Aby uzyskać więcej informacji proszę zapoznać się z rozdziałem Typy logiczne.
Można używać operatora ===
do testowania zwracanych wartości przez tę
funkcję.
Przykłady
Przykład #1 collator_get_sort_key()example
<?php
$s1 = 'Hello';
$coll = collator_create( 'en_US' );
$res = collator_get_sort_key( $coll, $s1);
echo urlencode($res);
?>
Powyższy przykład wyświetli:
71%3F%3FE%01%09%01%8F%08%00
Zobacz też:
- collator_sort() - Sort array using specified collator
- collator_sort_with_sort_keys() - Sort array using specified collator and sort keys
Collator::getStrength
collator_get_strength
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Collator::getStrength -- collator_get_strength — Get current collation strength
Opis
Styl obiektowy
Styl proceduralny
Zwracane wartości
Returns current collation strength, or boolean FALSE on error.
Przykłady
Przykład #1 collator_get_strength() example
<?php
$coll = collator_create( 'en_US' );
$strength = collator_get_strength( $coll );
?>
Zobacz też:
- Collator constants
- collator_set_strength() - Set collation strength
- collator_get_attribute() - Get collation attribute value
Collator::setAttribute
collator_set_attribute
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Collator::setAttribute -- collator_set_attribute — Set collation attribute
Opis
Styl obiektowy
$attr
, int $val
)Styl proceduralny
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 collator_set_attribute() example
<?php
$coll = collator_create( 'en_CA' );
$val = collator_get_attribute( $coll, Collator::NUMERIC_COLLATION );
if ($val === false) {
// Handle error.
} elseif ($val === Collator::ON) {
// Do something useful.
}
?>
Zobacz też:
- Collator constants
- collator_get_attribute() - Get collation attribute value
- collator_set_strength() - Set collation strength
Collator::setStrength
collator_set_strength
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Collator::setStrength -- collator_set_strength — Set collation strength
Opis
Styl obiektowy
$strength
)Styl proceduralny
The » ICU Collation Service supports many levels of comparison (named "Levels", but also known as "Strengths"). Having these categories enables ICU to sort strings precisely according to local conventions. However, by allowing the levels to be selectively employed, searching for a string in text can be performed with various matching conditions.
-
Primary Level: Typically, this is used to denote differences between base characters (for example, "a" < "b"). It is the strongest difference. For example, dictionaries are divided into different sections by base character. This is also called the level1 strength.
-
Secondary Level: Accents in the characters are considered secondary differences (for example, "as" < "às" < "at"). Other differences between letters can also be considered secondary differences, depending on the language. A secondary difference is ignored when there is a primary difference anywhere in the strings. This is also called the level2 strength.
Informacja:
Note: In some languages (such as Danish), certain accented letters are considered to be separate base characters. In most languages, however, an accented letter only has a secondary difference from the unaccented version of that letter.
-
Tertiary Level: Upper and lower case differences in characters are distinguished at the tertiary level (for example, "ao" < "Ao" < "aò"). In addition, a variant of a letter differs from the base form on the tertiary level (such as "A" and " "). Another example is the difference between large and small Kana. A tertiary difference is ignored when there is a primary or secondary difference anywhere in the strings. This is also called the level3 strength.
-
Quaternary Level: When punctuation is ignored (see Ignoring Punctuations ) at level 13, an additional level can be used to distinguish words with and without punctuation (for example, "ab" < "a-b" < "aB"). This difference is ignored when there is a primary, secondary or tertiary difference. This is also known as the level4 strength. The quaternary level should only be used if ignoring punctuation is required or when processing Japanese text (see Hiragana processing).
-
Identical Level: When all other levels are equal, the identical level is used as a tiebreaker. The Unicode code point values of the NFD form of each string are compared at this level, just in case there is no difference at levels 14. For example, Hebrew cantillation marks are only distinguished at this level. This level should be used sparingly, as only code point values differences between two strings is an extremely rare occurrence. Using this level substantially decreases the performance for both incremental comparison and sort key generation (as well as increasing the sort key length). It is also known as level 5 strength.
For example, people may choose to ignore accents or ignore accents and case when searching for text. Almost all characters are distinguished by the first three levels, and in most locales the default value is thus Tertiary. However, if Alternate is set to be Shifted, then the Quaternary strength can be used to break ties among whitespace, punctuation, and symbols that would otherwise be ignored. If very fine distinctions among characters are required, then the Identical strength can be used (for example, Identical Strength distinguishes between the Mathematical Bold Small A and the Mathematical Italic Small A.). However, using levels higher than Tertiary the Identical strength result in significantly longer sort keys, and slower string comparison performance for equal strings.
Parametry
-
coll -
Collator object.
-
strength -
Strength to set.
Possible values are:
-
Collator::PRIMARY -
Collator::SECONDARY -
Collator::TERTIARY -
Collator::QUATERNARY -
Collator::IDENTICAL -
Collator::DEFAULT
-
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 collator_set_strength() example
<?php
$arr = array( 'aò', 'Ao', 'ao' );
$coll = collator_create( 'en_US' );
// Sort array using default strength.
collator_sort( $coll, $arr );
var_export( $arr );
// Sort array using primary strength.
collator_set_strength( $coll, Collator::PRIMARY );
collator_sort( $coll, $arr );
var_export( $arr );
?>
Powyższy przykład wyświetli:
array ( 0 => 'ao', 1 => 'Ao', 2 => 'aò', ) array ( 0 => 'aò', 1 => 'Ao', 2 => 'ao', )
Collator::sortWithSortKeys
collator_sort_with_sort_keys
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Collator::sortWithSortKeys -- collator_sort_with_sort_keys — Sort array using specified collator and sort keys
Opis
Styl obiektowy
&$arr
)Styl proceduralny
Similar to collator_sort() but uses ICU sorting keys produced by ucol_getSortKey() to gain more speed on large arrays.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 collator_sort_with_sort_keys() example
<?php
$arr = array( 'Köpfe', 'Kypper', 'Kopfe' );
$coll = collator_create( 'sv' );
collator_sort_with_sort_keys( $coll, $arr );
var_export( $arr );
?>
Powyższy przykład wyświetli:
array ( 0 => 'Kopfe', 1 => 'Kypper', 2 => 'Köpfe', )
Zobacz też:
- Collator constants
- collator_sort() - Sort array using specified collator
- collator_asort() - Sort array maintaining index association
Collator::sort
collator_sort
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Collator::sort -- collator_sort — Sort array using specified collator
Opis
Styl obiektowy
&$arr
[, int $sort_flag
] )Styl proceduralny
This function sorts an array according to current locale rules.
Equivalent to standard PHP sort() .
Parametry
-
coll -
Collator object.
-
arr -
Array of strings to sort.
-
sort_flag -
Optional sorting type, one of the following:
-
Collator::SORT_REGULAR- compare items normally (don't change types) -
Collator::SORT_NUMERIC- compare items numerically -
Collator::SORT_STRING- compare items as strings
Collator::SORT_REGULAR. It is also used if an invalidsort_flagvalue has been specified. -
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 collator_sort() example
<?php
$coll = collator_create( 'en_US' );
$arr = array( 'at', 'às', 'as' );
var_export( $arr );
collator_sort( $coll, $arr );
var_export( $arr );
?>
Powyższy przykład wyświetli:
array ( 0 => 'at', 1 => 'às', 2 => 'as', )array ( 0 => 'as', 1 => 'às', 2 => 'at', )
Zobacz też:
- Collator constants
- collator_asort() - Sort array maintaining index association
- collator_sort_with_sort_keys() - Sort array using specified collator and sort keys
Spis treści
- Collator::asort — Sort array maintaining index association
- Collator::compare — Compare two Unicode strings
- Collator::__construct — Create a collator
- Collator::create — Create a collator
- Collator::getAttribute — Get collation attribute value
- Collator::getErrorCode — Get collator's last error code
- Collator::getErrorMessage — Get text for collator's last error code
- Collator::getLocale — Get the locale name of the collator
- Collator::getSortKey — Get sorting key for a string
- Collator::getStrength — Get current collation strength
- Collator::setAttribute — Set collation attribute
- Collator::setStrength — Set collation strength
- Collator::sortWithSortKeys — Sort array using specified collator and sort keys
- Collator::sort — Sort array using specified collator
The NumberFormatter class
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Wstęp
Programs store and operate on numbers using a locale-independent binary representation. When displaying or printing a number it is converted to a locale-specific string. For example, the number 12345.67 is "12,345.67" in the US, "12 345,67" in France and "12.345,67" in Germany.
By invoking the methods provided by the NumberFormatter class, you can format numbers, currencies, and percentages according to the specified or default locale. NumberFormatter is locale-sensitive so you need to create a new NumberFormatter for each locale. NumberFormatter methods format primitive-type numbers, such as double and output the number as a locale-specific string.
For currencies you can use currency format type to create a formatter that returns a string with the formatted number and the appropriate currency sign. Of course, the NumberFormatter class is unaware of exchange rates so, the number output is the same regardless of the specified currency. This means that the same number has different monetary values depending on the currency locale. If the number is 9988776.65 the results will be:
- 9 988 776,65 € in France
- 9.988.776,65 € in Germany
- $9,988,776.65 in the United States
In order to format percentages, create a locale-specific formatter with percentage format type. With this formatter, a decimal fraction such as 0.75 is displayed as 75%.
For more complex formatting, like spelled-out numbers, the rule-based number formatters are used.
Krótki opis klasy
Stałe predefiniowane
These styles are used by the numfmt_create() to define the type of the formatter.
-
NumberFormatter::PATTERN_DECIMAL(integer) - Decimal format defined by pattern
-
NumberFormatter::DECIMAL(integer) - Decimal format
-
NumberFormatter::CURRENCY(integer) - Currency format
-
NumberFormatter::PERCENT(integer) - Percent format
-
NumberFormatter::SCIENTIFIC(integer) - Scientific format
-
NumberFormatter::SPELLOUT(integer) - Spellout rule-based format
-
NumberFormatter::ORDINAL(integer) - Ordinal rule-based format
-
NumberFormatter::DURATION(integer) - Duration rule-based format
-
NumberFormatter::PATTERN_RULEBASED(integer) - Rule-based format defined by pattern
-
NumberFormatter::DEFAULT_STYLE(integer) - Default format for the locale
-
NumberFormatter::IGNORE(integer) - Alias for PATTERN_DECIMAL
These constants define how the numbers are parsed or formatted. They should be used as arguments to numfmt_format() and numfmt_parse().
-
NumberFormatter::TYPE_DEFAULT(integer) - Derive the type from variable type
-
NumberFormatter::TYPE_INT32(integer) - Format/parse as 32-bit integer
-
NumberFormatter::TYPE_INT64(integer) - Format/parse as 64-bit integer
-
NumberFormatter::TYPE_DOUBLE(integer) - Format/parse as floating point value
-
NumberFormatter::TYPE_CURRENCY(integer) - Format/parse as currency value
Number format attribute used by numfmt_get_attribute() and numfmt_set_attribute().
-
NumberFormatter::PARSE_INT_ONLY(integer) - Parse integers only.
-
NumberFormatter::GROUPING_USED(integer) - Use grouping separator.
-
NumberFormatter::DECIMAL_ALWAYS_SHOWN(integer) - Always show decimal point.
-
NumberFormatter::MAX_INTEGER_DIGITS(integer) - Maximum integer digits.
-
NumberFormatter::MIN_INTEGER_DIGITS(integer) - Minimum integer digits.
-
NumberFormatter::INTEGER_DIGITS(integer) - Integer digits.
-
NumberFormatter::MAX_FRACTION_DIGITS(integer) - Maximum fraction digits.
-
NumberFormatter::MIN_FRACTION_DIGITS(integer) - Minimum fraction digits.
-
NumberFormatter::FRACTION_DIGITS(integer) - Fraction digits.
-
NumberFormatter::MULTIPLIER(integer) - Multiplier.
-
NumberFormatter::GROUPING_SIZE(integer) - Grouping size.
-
NumberFormatter::ROUNDING_MODE(integer) - Rounding Mode.
-
NumberFormatter::ROUNDING_INCREMENT(integer) - Rounding increment.
-
NumberFormatter::FORMAT_WIDTH(integer) - The width to which the output of format() is padded.
-
NumberFormatter::PADDING_POSITION(integer) - The position at which padding will take place. See pad position constants for possible argument values.
-
NumberFormatter::SECONDARY_GROUPING_SIZE(integer) - Secondary grouping size.
-
NumberFormatter::SIGNIFICANT_DIGITS_USED(integer) - Use significant digits.
-
NumberFormatter::MIN_SIGNIFICANT_DIGITS(integer) - Minimum significant digits.
-
NumberFormatter::MAX_SIGNIFICANT_DIGITS(integer) - Maximum significant digits.
-
NumberFormatter::LENIENT_PARSE(integer) - Lenient parse mode used by rule-based formats.
Number format text attribute used by numfmt_get_text_attribute() and numfmt_set_text_attribute().
-
NumberFormatter::POSITIVE_PREFIX(integer) - Positive prefix.
-
NumberFormatter::POSITIVE_SUFFIX(integer) - Positive suffix.
-
NumberFormatter::NEGATIVE_PREFIX(integer) - Negative prefix.
-
NumberFormatter::NEGATIVE_SUFFIX(integer) - Negative suffix.
-
NumberFormatter::PADDING_CHARACTER(integer) - The character used to pad to the format width.
-
NumberFormatter::CURRENCY_CODE(integer) - The ISO currency code.
-
NumberFormatter::DEFAULT_RULESET(integer) - The default rule set. This is only available with rule-based formatters.
-
NumberFormatter::PUBLIC_RULESETS(integer) - The public rule sets. This is only available with rule-based formatters. This is a read-only attribute. The public rulesets are returned as a single string, with each ruleset name delimited by ';' (semicolon).
Number format symbols used by numfmt_get_symbol() and numfmt_set_symbol().
-
NumberFormatter::DECIMAL_SEPARATOR_SYMBOL(integer) - The decimal separator.
-
NumberFormatter::GROUPING_SEPARATOR_SYMBOL(integer) - The grouping separator.
-
NumberFormatter::PATTERN_SEPARATOR_SYMBOL(integer) - The pattern separator.
-
NumberFormatter::PERCENT_SYMBOL(integer) - The percent sign.
-
NumberFormatter::ZERO_DIGIT_SYMBOL(integer) - Zero.
-
NumberFormatter::DIGIT_SYMBOL(integer) - Character representing a digit in the pattern.
-
NumberFormatter::MINUS_SIGN_SYMBOL(integer) - The minus sign.
-
NumberFormatter::PLUS_SIGN_SYMBOL(integer) - The plus sign.
-
NumberFormatter::CURRENCY_SYMBOL(integer) - The currency symbol.
-
NumberFormatter::INTL_CURRENCY_SYMBOL(integer) - The international currency symbol.
-
NumberFormatter::MONETARY_SEPARATOR_SYMBOL(integer) - The monetary separator.
-
NumberFormatter::EXPONENTIAL_SYMBOL(integer) - The exponential symbol.
-
NumberFormatter::PERMILL_SYMBOL(integer) - Per mill symbol.
-
NumberFormatter::PAD_ESCAPE_SYMBOL(integer) - Escape padding character.
-
NumberFormatter::INFINITY_SYMBOL(integer) - Infinity symbol.
-
NumberFormatter::NAN_SYMBOL(integer) - Not-a-number symbol.
-
NumberFormatter::SIGNIFICANT_DIGIT_SYMBOL(integer) - Significant digit symbol.
-
NumberFormatter::MONETARY_GROUPING_SEPARATOR_SYMBOL(integer) - The monetary grouping separator.
Rounding mode values used by numfmt_get_attribute()
and numfmt_set_attribute() with
NumberFormatter::ROUNDING_MODE attribute.
-
NumberFormatter::ROUND_CEILING(integer) - Rounding mode to round towards positive infinity.
-
NumberFormatter::ROUND_DOWN(integer) - Rounding mode to round towards zero.
-
NumberFormatter::ROUND_FLOOR(integer) - Rounding mode to round towards negative infinity.
-
NumberFormatter::ROUND_HALFDOWN(integer) - Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round down.
-
NumberFormatter::ROUND_HALFEVEN(integer) - Rounding mode to round towards the "nearest neighbor" unless both neighbors are equidistant, in which case, round towards the even neighbor.
-
NumberFormatter::ROUND_HALFUP(integer) - Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round up.
-
NumberFormatter::ROUND_UP(integer) - Rounding mode to round away from zero.
Pad position values used by numfmt_get_attribute()
and numfmt_set_attribute() with
NumberFormatter::PADDING_POSITION attribute.
-
NumberFormatter::PAD_AFTER_PREFIX(integer) - Pad characters inserted after the prefix.
-
NumberFormatter::PAD_AFTER_SUFFIX(integer) - Pad characters inserted after the suffix.
-
NumberFormatter::PAD_BEFORE_PREFIX(integer) - Pad characters inserted before the prefix.
-
NumberFormatter::PAD_BEFORE_SUFFIX(integer) - Pad characters inserted before the suffix.
NumberFormatter::create
numfmt_create
NumberFormatter::__construct
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
NumberFormatter::create -- numfmt_create -- NumberFormatter::__construct — Create a number formatter
Opis
Styl obiektowy (method)
Styl proceduralny
Styl obiektowy (constructor):
$locale
, int $style
[, string $pattern
] )Creates a number formatter.
Parametry
-
locale -
Locale in which the number would be formatted (locale name, e.g. en_CA).
-
style -
Style of the formatting, one of the format style constants. If
NumberFormatter::PATTERN_DECIMALorNumberFormatter::PATTERN_RULEBASEDis passed then the number format is opened using the given pattern, which must conform to the syntax described in » ICU DecimalFormat documentation or » ICU RuleBasedNumberFormat documentation, respectively. -
pattern -
Pattern string if the chosen style requires a pattern.
Zwracane wartości
Returns NumberFormatter object or FALSE on error.
Przykłady
Przykład #1 numfmt_create() example
<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
echo numfmt_format($fmt, 1234567.891234567890000)."\n";
$fmt = numfmt_create( 'it', NumberFormatter::SPELLOUT );
echo numfmt_format($fmt, 1142)."\n";
?>
Przykład #2 NumberFormatter::create() example
<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
echo $fmt->format(1234567.891234567890000)."\n";
$fmt = new NumberFormatter( 'it', NumberFormatter::SPELLOUT );
echo $fmt->format(1142)."\n";
?>
Powyższy przykład wyświetli:
1.234.567,891 millicentoquarantadue
NumberFormatter::formatCurrency
numfmt_format_currency
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
NumberFormatter::formatCurrency -- numfmt_format_currency — Format a currency value
Opis
Styl obiektowy
$value
, string $currency
)Styl proceduralny
Format the currency value according to the formatter rules.
Parametry
-
fmt -
NumberFormatter object.
-
value -
The numeric currency value.
-
currency -
The 3-letter ISO 4217 currency code indicating the currency to use.
Zwracane wartości
String representing the formatted currency value.
Przykłady
Przykład #1 numfmt_format_currency() example
<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::CURRENCY );
echo numfmt_format_currency($fmt, 1234567.891234567890000, "EUR")."\n";
echo numfmt_format_currency($fmt, 1234567.891234567890000, "RUR")."\n";
$fmt = numfmt_create( 'ru_RU', NumberFormatter::CURRENCY );
echo numfmt_format_currency($fmt, 1234567.891234567890000, "EUR")."\n";
echo numfmt_format_currency($fmt, 1234567.891234567890000, "RUR")."\n";
?>
Przykład #2 OO example
<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::CURRENCY );
echo $fmt->formatCurrency(1234567.891234567890000, "EUR")."\n";
echo $fmt->formatCurrency(1234567.891234567890000, "RUR")."\n";
$fmt = new NumberFormatter( 'ru_RU', NumberFormatter::CURRENCY );
echo $fmt->formatCurrency(1234567.891234567890000, "EUR")."\n";
echo $fmt->formatCurrency(1234567.891234567890000, "RUR")."\n";
?>
Powyższy przykład wyświetli:
1.234.567,89 € 1.234.567,89 RUR 1 234 567,89€ 1 234 567,89р.
Zobacz też:
- numfmt_get_error_code() - Get formatter's last error code.
- numfmt_format() - Format a number
- numfmt_parse_currency() - Parse a currency number
NumberFormatter::format
numfmt_format
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
NumberFormatter::format -- numfmt_format — Format a number
Opis
Styl obiektowy
Styl proceduralny
Format a numeric value according to the formatter rules.
Parametry
-
fmt -
NumberFormatter object.
-
value -
The value to format. Can be integer or float, other values will be converted to a numeric value.
-
type -
The formatting type to use.
Zwracane wartości
Returns the string containing formatted value, or FALSE on error.
Przykłady
Przykład #1 numfmt_format() example
<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
$data = numfmt_format($fmt, 1234567.891234567890000);
if(intl_is_failure(numfmt_format($fmt))) {
report_error("Formatter error");
}
?>
Przykład #2 OO example
<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
$fmt->format(1234567.891234567890000);
if(intl_is_failure($fmt->getErrorCode())) {
report_error("Formatter error");
}
?>
Powyższy przykład wyświetli:
1.234.567,891
Zobacz też:
- numfmt_get_error_code() - Get formatter's last error code.
- numfmt_format_currency() - Format a currency value
- numfmt_parse() - Parse a number
NumberFormatter::getAttribute
numfmt_get_attribute
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
NumberFormatter::getAttribute -- numfmt_get_attribute — Get an attribute
Opis
Styl obiektowy
$attr
)Styl proceduralny
Get a numeric attribute associated with the formatter. An example of a numeric attribute is the number of integer digits the formatter will produce.
Parametry
-
fmt -
NumberFormatter object.
-
attr -
Attribute specifier - one of the numeric attribute constants.
Zwracane wartości
Return attribute value on success, or FALSE on error.
Przykłady
Przykład #1 numfmt_get_attribute() example
<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
echo "Digits: ".numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS)."\n";
echo numfmt_format($fmt, 1234567.891234567890000)."\n";
numfmt_set_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS, 2);
echo "Digits: ".numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS)."\n";
echo numfmt_format($fmt, 1234567.891234567890000)."\n";
?>
Przykład #2 OO example
<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
echo "Digits: ".$fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS)."\n";
echo $fmt->format(1234567.891234567890000)."\n";
$fmt->setAttribute(NumberFormatter::MAX_FRACTION_DIGITS, 2);
echo "Digits: ".$fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS)."\n";
echo $fmt->format(1234567.891234567890000)."\n";
?>
Powyższy przykład wyświetli:
Digits: 3 1.234.567,891 Digits: 2 1.234.567,89
Zobacz też:
- numfmt_get_error_code() - Get formatter's last error code.
- numfmt_get_text_attribute() - Get a text attribute
- numfmt_set_attribute() - Set an attribute
NumberFormatter::getErrorCode
numfmt_get_error_code
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
NumberFormatter::getErrorCode -- numfmt_get_error_code — Get formatter's last error code.
Opis
Styl obiektowy
Styl proceduralny
Get error code from the last function performed by the formatter.
Zwracane wartości
Returns error code from last formatter call.
Przykłady
Przykład #1 numfmt_get_error_code() example
<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
$data = numfmt_format($fmt, 1234567.891234567890000);
if(intl_is_failure(numfmt_get_error_code($fmt))) {
report_error("Formatter error");
}
?>
Przykład #2 OO example
<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
$fmt->format(1234567.891234567890000);
if(intl_is_failure($fmt->getErrorCode())) {
report_error("Formatter error");
}
?>
Zobacz też:
- numfmt_get_error_message() - Get formatter's last error message.
- intl_get_error_code() - Get the last error code
- intl_is_failure() - Check whether the given error code indicates failure
NumberFormatter::getErrorMessage
numfmt_get_error_message
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
NumberFormatter::getErrorMessage -- numfmt_get_error_message — Get formatter's last error message.
Opis
Styl obiektowy
Styl proceduralny
Get error message from the last function performed by the formatter.
Zwracane wartości
Returns error message from last formatter call.
Przykłady
Przykład #1 numfmt_get_error_message() example
<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
$data = numfmt_format($fmt, 1234567.891234567890000);
if(intl_is_failure(numfmt_get_error_code($fmt))) {
report_error("Formatter error");
}
?>
Przykład #2 OO example
<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
$fmt->format(1234567.891234567890000);
if(intl_is_failure($fmt->getErrorCode())) {
report_error("Formatter error");
}
?>
Zobacz też:
- numfmt_get_error_code() - Get formatter's last error code.
- intl_get_error_code() - Get the last error code
- intl_is_failure() - Check whether the given error code indicates failure
NumberFormatter::getLocale
numfmt_get_locale
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
NumberFormatter::getLocale -- numfmt_get_locale — Get formatter locale
Opis
Styl obiektowy
$type
] )Styl proceduralny
Get formatter locale name.
Parametry
-
fmt -
NumberFormatter object.
-
type -
You can choose between valid and actual locale (
Locale::VALID_LOCALE,Locale::ACTUAL_LOCALE, respectively). The default is the actual locale.
Zwracane wartości
The locale name used to create the formatter.
Przykłady
Przykład #1 numfmt_get_locale() example
<?php
$req = 'fr_FR_PARIS';
$fmt = numfmt_create( $req, NumberFormatter::DECIMAL);
$res_val = numfmt_get_locale( $fmt, Locale::VALID_LOCALE );
$res_act = numfmt_get_locale( $fmt, Locale::ACTUAL_LOCALE );
printf( "Requested locale name: %s\nValid locale name: %s\nActual locale name: %s\n",
$req, $res_val, $res_act );
?>
Powyższy przykład wyświetli:
Requested locale name: fr_FR_PARIS Valid locale name: fr_FR Actual locale name: fr
Zobacz też:
- numfmt_create() - Create a number formatter
- numfmt_get_error_code() - Get formatter's last error code.
NumberFormatter::getPattern
numfmt_get_pattern
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
NumberFormatter::getPattern -- numfmt_get_pattern — Get formatter pattern
Opis
Styl obiektowy
Styl proceduralny
Extract pattern used by the formatter.
Zwracane wartości
Pattern string that is used by the formatter, or FALSE if an error happens.
Przykłady
Przykład #1 numfmt_get_pattern() example
<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
echo "Pattern: ".numfmt_get_pattern($fmt)."\n";
echo numfmt_format($fmt, 1234567.891234567890000)."\n";
numfmt_set_pattern($fmt, "#0.# kg");
echo "Pattern: ".numfmt_get_pattern($fmt)."\n";
echo numfmt_format($fmt, 1234567.891234567890000)."\n";
?>
Przykład #2 OO example
<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
echo "Pattern: ".$fmt->getPattern()."\n";
echo $fmt->format(1234567.891234567890000)."\n";
$fmt->setPattern("#0.# kg");
echo "Pattern: ".$fmt->getPattern()."\n";
echo $fmt->format(1234567.891234567890000)."\n";
?>
Powyższy przykład wyświetli:
Pattern: #,##0.### 1.234.567,891 Pattern: #0.# kg 1234567,9 kg
Zobacz też:
- numfmt_get_error_code() - Get formatter's last error code.
- numfmt_set_pattern() - Set formatter pattern
- numfmt_create() - Create a number formatter
NumberFormatter::getSymbol
numfmt_get_symbol
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
NumberFormatter::getSymbol -- numfmt_get_symbol — Get a symbol value
Opis
Styl obiektowy
$attr
)Styl proceduralny
Get a symbol associated with the formatter. The formatter uses symbols to represent the special locale-dependent characters in a number, for example the percent sign. This API is not supported for rule-based formatters.
Zwracane wartości
The symbol string or FALSE on error.
Przykłady
Przykład #1 numfmt_get_symbol() example
<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
echo "Sep: ".numfmt_get_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
echo numfmt_format($fmt, 1234567.891234567890000)."\n";
numfmt_set_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL, "*");
echo "Sep: ".numfmt_get_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
echo numfmt_format($fmt, 1234567.891234567890000)."\n";
?>
Przykład #2 OO example
<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
echo "Sep: ".$fmt->getSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
echo $fmt->format(1234567.891234567890000)."\n";
$fmt->setSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL, "*");
echo "Sep: ".$fmt->getSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
echo $fmt->format(1234567.891234567890000)."\n";
?>
Powyższy przykład wyświetli:
Sep: . 1.234.567,891 Sep: * 1*234*567,891
Zobacz też:
- numfmt_get_error_code() - Get formatter's last error code.
- numfmt_set_symbol() - Set a symbol value
NumberFormatter::getTextAttribute
numfmt_get_text_attribute
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
NumberFormatter::getTextAttribute -- numfmt_get_text_attribute — Get a text attribute
Opis
Styl obiektowy
$attr
)Styl proceduralny
Get a text attribute associated with the formatter. An example of a text
attribute is the suffix for positive numbers. If the formatter does not
understand the attribute,
U_UNSUPPORTED_ERROR
error is produced. Rule-based formatters only understand
NumberFormatter::DEFAULT_RULESET and
NumberFormatter::PUBLIC_RULESETS.
Parametry
-
fmt -
NumberFormatter object.
-
attr -
Attribute specifier - one of the text attribute constants.
Zwracane wartości
Return attribute value on success, or FALSE on error.
Przykłady
Przykład #1 numfmt_get_text_attribute() example
<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
echo "Prefix: ".numfmt_get_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX)."\n";
echo numfmt_format($fmt, -1234567.891234567890000)."\n";
numfmt_set_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX, "MINUS");
echo "Prefix: ".numfmt_get_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX)."\n";
echo numfmt_format($fmt, -1234567.891234567890000)."\n";
?>
Przykład #2 OO example
<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
echo "Prefix: ".$fmt->getTextAttribute(NumberFormatter::NEGATIVE_PREFIX)."\n";
echo $fmt->format(-1234567.891234567890000)."\n";
$fmt->setTextAttribute(NumberFormatter::NEGATIVE_PREFIX, "MINUS");
echo "Prefix: ".$fmt->getTextAttribute(NumberFormatter::NEGATIVE_PREFIX)."\n";
echo $fmt->format(-1234567.891234567890000)."\n";
?>
Powyższy przykład wyświetli:
Prefix: - -1.234.567,891 Prefix: MINUS MINUS1.234.567,891
Zobacz też:
- numfmt_get_error_code() - Get formatter's last error code.
- numfmt_get_attribute() - Get an attribute
- numfmt_set_text_attribute() - Set a text attribute
NumberFormatter::parseCurrency
numfmt_parse_currency
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
NumberFormatter::parseCurrency -- numfmt_parse_currency — Parse a currency number
Opis
Styl obiektowy
$value
, string &$currency
[, int &$position
] )Styl proceduralny
$fmt
, string $value
, string &$currency
[, int &$position
] )Parse a string into a double and a currency using the current formatter.
Parametry
-
fmt -
NumberFormatter object.
-
currency -
Parameter to receive the currency name (3-letter ISO 4217 currency code).
-
position -
Offset in the string at which to begin parsing. On return, this value will hold the offset at which parsing ended.
Zwracane wartości
The parsed numeric value or FALSE on error.
Przykłady
Przykład #1 numfmt_parse_currency() example
<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::CURRENCY );
$num = "1.234.567,89 $";
echo "We have ".numfmt_parse_currency($fmt, $num, $curr)." in $curr\n";
?>
Przykład #2 OO example
<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::CURRENCY );
$num = "1.234.567,89 $";
echo "We have ".$fmt->parseCurrency($num, $curr)." in $curr\n";
?>
Powyższy przykład wyświetli:
We have 1234567.89 in USD
Zobacz też:
- numfmt_get_error_code() - Get formatter's last error code.
- numfmt_parse() - Parse a number
- numfmt_format_currency() - Format a currency value
NumberFormatter::parse
numfmt_parse
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
NumberFormatter::parse -- numfmt_parse — Parse a number
Opis
Styl obiektowy
Styl proceduralny
Parse a string into a number using the current formatter rules.
Parametry
-
fmt -
NumberFormatter object.
-
type -
The formatting type to use. By default,
NumberFormatter::TYPE_DOUBLEis used. -
position -
Offset in the string at which to begin parsing. On return, this value will hold the offset at which parsing ended.
Zwracane wartości
The value of the parsed number or FALSE on error.
Przykłady
Przykład #1 numfmt_parse() example
<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
$num = "1.234.567,891";
echo numfmt_parse($fmt, $num)."\n";
echo numfmt_parse($fmt, $num, NumberFormatter::TYPE_INT32)."\n";
?>
Przykład #2 OO example
<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
$num = "1.234.567,891";
echo $fmt->parse($num)."\n";
echo $fmt->parse($num, NumberFormatter::TYPE_INT32)."\n";
?>
Powyższy przykład wyświetli:
1234567.891 1234567
Zobacz też:
- numfmt_get_error_code() - Get formatter's last error code.
- numfmt_format() - Format a number
- numfmt_parse_currency() - Parse a currency number
NumberFormatter::setAttribute
numfmt_set_attribute
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
NumberFormatter::setAttribute -- numfmt_set_attribute — Set an attribute
Opis
Styl obiektowy
$attr
, int $value
)Styl proceduralny
Set a numeric attribute associated with the formatter. An example of a numeric attribute is the number of integer digits the formatter will produce.
Parametry
-
fmt -
NumberFormatter object.
-
attr -
Attribute specifier - one of the numeric attribute constants.
-
value -
The attribute value.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 numfmt_set_attribute() example
<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
echo "Digits: ".numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS)."\n";
echo numfmt_format($fmt, 1234567.891234567890000)."\n";
numfmt_set_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS, 2);
echo "Digits: ".numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS)."\n";
echo numfmt_format($fmt, 1234567.891234567890000)."\n";
?>
Przykład #2 OO example
<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
echo "Digits: ".$fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS)."\n";
echo $fmt->format(1234567.891234567890000)."\n";
$fmt->setAttribute(NumberFormatter::MAX_FRACTION_DIGITS, 2);
echo "Digits: ".$fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS)."\n";
echo $fmt->format(1234567.891234567890000)."\n";
?>
Powyższy przykład wyświetli:
Digits: 3 1.234.567,891 Digits: 2 1.234.567,89
Zobacz też:
- numfmt_get_error_code() - Get formatter's last error code.
- numfmt_get_attribute() - Get an attribute
- numfmt_set_text_attribute() - Set a text attribute
NumberFormatter::setPattern
numfmt_set_pattern
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
NumberFormatter::setPattern -- numfmt_set_pattern — Set formatter pattern
Opis
Styl obiektowy
$pattern
)Styl proceduralny
Set the pattern used by the formatter. Can not be used on a rule-based formatter.
Parametry
-
fmt -
NumberFormatter object.
-
pattern -
Pattern in syntax described in » ICU DecimalFormat documentation.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 numfmt_set_pattern() example
<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
echo "Pattern: ".numfmt_get_pattern($fmt)."\n";
echo numfmt_format($fmt, 1234567.891234567890000)."\n";
numfmt_set_pattern($fmt, "#0.# kg");
echo "Pattern: ".numfmt_get_pattern($fmt)."\n";
echo numfmt_format($fmt, 1234567.891234567890000)."\n";
?>
Przykład #2 OO example
<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
echo "Pattern: ".$fmt->getPattern()."\n";
echo $fmt->format(1234567.891234567890000)."\n";
$fmt->setPattern("#0.# kg");
echo "Pattern: ".$fmt->getPattern()."\n";
echo $fmt->format(1234567.891234567890000)."\n";
?>
Powyższy przykład wyświetli:
Pattern: #,##0.### 1.234.567,891 Pattern: #0.# kg 1234567,9 kg
Zobacz też:
- numfmt_get_error_code() - Get formatter's last error code.
- numfmt_create() - Create a number formatter
- numfmt_get_pattern() - Get formatter pattern
NumberFormatter::setSymbol
numfmt_set_symbol
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
NumberFormatter::setSymbol -- numfmt_set_symbol — Set a symbol value
Opis
Styl obiektowy
$attr
, string $value
)Styl proceduralny
Set a symbol associated with the formatter. The formatter uses symbols to represent the special locale-dependent characters in a number, for example the percent sign. This API is not supported for rule-based formatters.
Parametry
-
fmt -
NumberFormatter object.
-
attr -
Symbol specifier, one of the format symbol constants.
-
value -
Text for the symbol.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 numfmt_set_symbol() example
<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
echo "Sep: ".numfmt_get_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
echo numfmt_format($fmt, 1234567.891234567890000)."\n";
numfmt_set_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL, "*");
echo "Sep: ".numfmt_get_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
echo numfmt_format($fmt, 1234567.891234567890000)."\n";
?>
Przykład #2 OO example
<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
echo "Sep: ".$fmt->getSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
echo $fmt->format(1234567.891234567890000)."\n";
$fmt->setSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL, "*");
echo "Sep: ".$fmt->getSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
echo $fmt->format(1234567.891234567890000)."\n";
?>
Powyższy przykład wyświetli:
Sep: . 1.234.567,891 Sep: * 1*234*567,891
Zobacz też:
- numfmt_get_error_code() - Get formatter's last error code.
- numfmt_get_symbol() - Get a symbol value
NumberFormatter::setTextAttribute
numfmt_set_text_attribute
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
NumberFormatter::setTextAttribute -- numfmt_set_text_attribute — Set a text attribute
Opis
Styl obiektowy
$attr
, string $value
)Styl proceduralny
Set a text attribute associated with the formatter. An example of a text
attribute is the suffix for positive numbers. If the formatter does not
understand the attribute,
U_UNSUPPORTED_ERROR
error is produced. Rule-based formatters only understand
NumberFormatter::DEFAULT_RULESET and
NumberFormatter::PUBLIC_RULESETS.
Parametry
-
fmt -
NumberFormatter object.
-
attr -
Attribute specifier - one of the text attribute constants.
-
value -
Text for the attribute value.
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 numfmt_set_text_attribute() example
<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
echo "Prefix: ".numfmt_get_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX)."\n";
echo numfmt_format($fmt, -1234567.891234567890000)."\n";
numfmt_set_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX, "MINUS");
echo "Prefix: ".numfmt_get_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX)."\n";
echo numfmt_format($fmt, -1234567.891234567890000)."\n";
?>
Przykład #2 OO example
<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
echo "Prefix: ".$fmt->getTextAttribute(NumberFormatter::NEGATIVE_PREFIX)."\n";
echo $fmt->format(-1234567.891234567890000)."\n";
$fmt->setTextAttribute(NumberFormatter::NEGATIVE_PREFIX, "MINUS");
echo "Prefix: ".$fmt->getTextAttribute(NumberFormatter::NEGATIVE_PREFIX)."\n";
echo $fmt->format(-1234567.891234567890000)."\n";
?>
Powyższy przykład wyświetli:
Prefix: - -1.234.567,891 Prefix: MINUS MINUS1.234.567,891
Zobacz też:
- numfmt_get_error_code() - Get formatter's last error code.
- numfmt_get_text_attribute() - Get a text attribute
- numfmt_set_attribute() - Set an attribute
Spis treści
- NumberFormatter::create — Create a number formatter
- NumberFormatter::formatCurrency — Format a currency value
- NumberFormatter::format — Format a number
- NumberFormatter::getAttribute — Get an attribute
- NumberFormatter::getErrorCode — Get formatter's last error code.
- NumberFormatter::getErrorMessage — Get formatter's last error message.
- NumberFormatter::getLocale — Get formatter locale
- NumberFormatter::getPattern — Get formatter pattern
- NumberFormatter::getSymbol — Get a symbol value
- NumberFormatter::getTextAttribute — Get a text attribute
- NumberFormatter::parseCurrency — Parse a currency number
- NumberFormatter::parse — Parse a number
- NumberFormatter::setAttribute — Set an attribute
- NumberFormatter::setPattern — Set formatter pattern
- NumberFormatter::setSymbol — Set a symbol value
- NumberFormatter::setTextAttribute — Set a text attribute
The Locale class
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Wstęp
A "Locale" is an identifier used to get language, culture, or regionally-specific behavior from an API. PHP locales are organized and identified the same way that the CLDR locales used by ICU (and many vendors of Unix-like operating systems, the Mac, Java, and so forth) use. Locales are identified using RFC 4646 language tags (which use hyphen, not underscore) in addition to the more traditional underscore-using identifiers. Unless otherwise noted the functions in this class are tolerant of both formats.
Examples of identifiers include:
- en-US (English, United States)
- zh-Hant-TW (Chinese, Traditional Script, Taiwan)
- fr-CA, fr-FR (French for Canada and France respectively)
The Locale class (and related procedural functions) are used to interact with locale identifiers--to verify that an ID is well-formed, valid, etc. The extensions used by CLDR in UAX #35 (and inherited by ICU) are valid and used wherever they would be in ICU normally.
Locales cannot be instantiated as objects. All of the functions/methods provided are static.
The null or empty string obtains the "root" locale. The "root" locale is equivalent to "en_US_POSIX" in CLDR. Language tags (and thus locale identifiers) are case insensitive. There exists a canonicalization function to make case match the specification.
Krótki opis klasy
$langtag
, string $locale
[, bool $canonicalize = false
[, string $default
]] )Stałe predefiniowane
-
Locale::DEFAULT_LOCALE(null) - Used as locale parameter with the methods of the various locale affected classes, such as NumberFormatter. This constant would make the methods to use default locale.
These constants describe the choice of the locale for getLocalte method of different classes.
-
Locale::ACTUAL_LOCALE(string) - This is locale the data actually comes from.
-
Locale::VALID_LOCALE(string) - This is the most specific locale supported by ICU.
These constants define how the Locales are parsed or composed. They should be used as keys in the argument array to locale_compose() and are returned from locale_parse() as keys of the returned associative array.
-
Locale::LANG_TAG(string) - Language subtag
-
Locale::EXTLANG_TAG(string) - Extended language subtag
-
Locale::SCRIPT_TAG(string) - Script subtag
-
Locale::REGION_TAG(string) - Region subtag
-
Locale::VARIANT_TAG(string) - Variant subtag
-
Locale::GRANDFATHERED_LANG_TAG(string) - Grandfathered Language subtag
-
Locale::PRIVATE_TAG(string) - Private subtag
Locale::acceptFromHttp
locale_accept_from_http
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Locale::acceptFromHttp -- locale_accept_from_http — Tries to find out best available locale based on HTTP "Accept-Language" header
Opis
Styl obiektowy
$header
)Styl proceduralny
$header
)Tries to find locale that can satisfy the language list that is requested by the HTTP "Accept-Language" header.
Parametry
-
header -
The string containing the "Accept-Language" header according to format in RFC 2616.
Zwracane wartości
The corresponding locale identifier.
Przykłady
Przykład #1 locale_accept_from_http() example
<?php
$locale = locale_accept_from_http($_SERVER['HTTP_ACCEPT_LANGUAGE']);
echo $locale;
?>
Przykład #2 OO example
<?php
$locale = Locale::acceptFromHttp($_SERVER['HTTP_ACCEPT_LANGUAGE']);
echo $locale;
?>
Powyższy przykład wyświetli:
en_US
Locale::composeLocale
locale_compose
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Locale::composeLocale -- locale_compose — Returns a correctly ordered and delimited locale ID
Opis
Styl obiektowy
$subtags
)Styl proceduralny
$subtags
)Returns a correctly ordered and delimited locale ID the keys identify the particular locale ID subtags, and the values are the associated subtag values.
Parametry
-
subtags -
an array containing a list of key-value pairs, where the keys identify the particular locale ID subtags, and the values are the associated subtag values.
Informacja:
The 'variant' and 'private' subtags can take maximum 15 values whereas 'extlang' can take maximum 3 values.e.g. Variants are allowed with the suffix ranging from 0-14. Hence the keys for the input array can be variant0, variant1, ...,variant14. In the returned locale id, the subtag is ordered by suffix resulting in variant0 followed by variant1 followed by variant2 and so on.
The 'variant', 'private' and 'extlang' multiple values can be specified both as array under specific key (e.g. 'variant') and as multiple numbered keys (e.g. 'variant0', 'variant1', etc.).
Zwracane wartości
The corresponding locale identifier.
Przykłady
Przykład #1 locale_compose() example
<?php
$arr = array(
'language'=>'en' ,
'script' =>'Hans' ,
'region' =>'CN',
'variant2'=>'rozaj' ,
'variant1'=>'nedis' ,
'private1'=>'prv1' ,
'private2'=>'prv2'
);
echo locale_compose( $arr );
?>
Przykład #2 OO example
<?php
$arr = array(
'language'=>'en' ,
'script' =>'Hans' ,
'region' =>'CN',
'variant2'=>'rozaj' ,
'variant1'=>'nedis' ,
'private1'=>'prv1' ,
'private2'=>'prv2'
);
echo Locale::composeLocale( $arr );
?>
Powyższy przykład wyświetli:
Locale: en_Hans_CN_nedis_rozaj_x_prv1_prv2
Locale::filterMatches
locale_filter_matches
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Locale::filterMatches -- locale_filter_matches — Checks if a language tag filter matches with locale
Opis
Styl obiektowy
$langtag
, string $locale
[, bool $canonicalize = false
] )Styl proceduralny
$langtag
, string $locale
[, bool $canonicalize = false
] )Checks if a $langtag filter matches with $locale according to RFC 4647's basic filtering algorithm
Parametry
-
langtag -
The language tag to check
-
locale -
The language range to check against
-
canonicalize -
If true, the arguments will be converted to canonical form before matching.
Zwracane wartości
TRUE if $locale matches $langtag FALSE otherwise.
Przykłady
Przykład #1 locale_filter_matches() example
<?php
echo (locale_filter_matches('de-DEVA','de-DE', false)) ? "Matches" : "Does not match";
echo '; ';
echo (locale_filter_matches('de-DE_1996','de-DE', false)) ? "Matches" : "Does not match";
?>
Przykład #2 OO example
<?php
echo (Locale::filterMatches('de-DEVA','de-DE', false)) ? "Matches" : "Does not match";
echo '; ';
echo (Locale::filterMatches('de-DE-1996','de-DE', false)) ? "Matches" : "Does not match";
?>
Powyższy przykład wyświetli:
Does not match; Matches
Locale::getAllVariants
locale_get_all_variants
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Locale::getAllVariants -- locale_get_all_variants — Gets the variants for the input locale
Opis
Styl obiektowy
$locale
)Styl proceduralny
$locale
)Gets the variants for the input locale
Parametry
-
locale -
The locale to extract the variants from
Zwracane wartości
The array containing the list of all variants subtag for the locale
or NULL if not present
Przykłady
Przykład #1 locale_get_all_variants() example
<?php
$arr = locale_get_all_variants('sl_IT_NEDIS_ROJAZ_1901');
var_export( $arr );
?>
Przykład #2 OO example
<?php
$arr = Locale::getAllVariants('sl_IT_NEDIS_ROJAZ_1901');
var_export( $arr );
?>
Powyższy przykład wyświetli:
array (
0 => 'NEDIS',
1 => 'ROJAZ',
2 => '1901',
)
Zobacz też:
- locale_get_primary_language() - Gets the primary language for the input locale
- locale_get_script() - Gets the script for the input locale
- locale_get_region() - Gets the region for the input locale
Locale::getDefault
locale_get_default
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Locale::getDefault -- locale_get_default — Gets the default locale value from the INTL global 'default_locale'
Opis
Styl obiektowy
Styl proceduralny
Gets the default locale value. At the PHP initialization this value is set to 'intl.default_locale' value from php.ini if that value exists or from ICU's function uloc_getDefault().
Parametry
Zwracane wartości
The current runtime locale
Przykłady
Przykład #1 locale_get_default() example
<?php
ini_set('intl.default_locale', 'de-DE');
echo locale_get_default();
echo '; ';
locale_set_default('fr');
echo locale_get_default();
?>
Przykład #2 OO example
<?php
ini_set('intl.default_locale', 'de-DE');
echo Locale::getDefault();
echo '; ';
Locale::setDefault('fr');
echo Locale::getDefault();
?>
Powyższy przykład wyświetli:
de-DE; fr
Locale::getDisplayLanguage
locale_get_display_language
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Locale::getDisplayLanguage -- locale_get_display_language — Returns an appropriately localized display name for language of the inputlocale
Opis
Styl obiektowy
$locale
[, string $in_locale
] )Styl proceduralny
$locale
[, string $in_locale
] )
Returns an appropriately localized display name for language of the input
locale. If is NULL then the default locale is used.
Parametry
-
locale -
The locale to return a display language for
-
in_locale -
Optional format locale to use to display the language name
Zwracane wartości
display name of the language for the $locale in the format appropriate for $in_locale.
Przykłady
Przykład #1 locale_get_display_language() example
<?php
echo locale_get_display_language('sl-Latn-IT-nedis', 'en');
echo ";\n";
echo locale_get_display_language('sl-Latn-IT-nedis', 'fr');
echo ";\n";
echo locale_get_display_language('sl-Latn-IT-nedis', 'de');
?>
Przykład #2 OO example
<?php
echo Locale::getDisplayLanguage('sl-Latn-IT-nedis', 'en');
echo ";\n";
echo Locale::getDisplayLanguage('sl-Latn-IT-nedis', 'fr');
echo ";\n";
echo Locale::getDisplayLanguage('sl-Latn-IT-nedis', 'de');
?>
Powyższy przykład wyświetli:
Slovenian; slov\xc3\xa8ne; Slowenisch
Zobacz też:
- locale_get_display_name() - Returns an appropriately localized display name for the input locale
- locale_get_display_script() - Returns an appropriately localized display name for script of the input locale
- locale_get_display_region() - Returns an appropriately localized display name for region of the input locale
- locale_get_display_variant() - Returns an appropriately localized display name for variants of the input locale
Locale::getDisplayName
locale_get_display_name
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Locale::getDisplayName -- locale_get_display_name — Returns an appropriately localized display name for the input locale
Opis
Styl obiektowy
$locale
[, string $in_locale
] )Styl proceduralny
$locale
[, string $in_locale
] )
Returns an appropriately localized display name for the input locale. If is
NULL then the default locale is used.
Parametry
-
locale -
The locale to return a display name for.
-
in_locale -
optional format locale
Zwracane wartości
Display name of the locale in the format appropriate for $in_locale.
Przykłady
Przykład #1 locale_get_display_name() example
<?php
echo locale_get_display_name('sl-Latn-IT-nedis', 'en');
echo ";\n";
echo locale_get_display_name('sl-Latn-IT-nedis', 'fr');
echo ";\n";
echo locale_get_display_name('sl-Latn-IT-nedis', 'de');
?>
Przykład #2 OO example
<?php
echo Locale::getDisplayName('sl-Latn-IT-nedis', 'en');
echo ";\n";
echo Locale::getDisplayName('sl-Latn-IT-nedis', 'fr');
echo ";\n";
echo Locale::getDisplayName('sl-Latn-IT-nedis', 'de');
?>
Powyższy przykład wyświetli:
Slovenian (Latin, Italy, Natisone dialect); slov\xc3\xa8ne (latin, Italie, dialecte de Natisone; Slowenisch (Lateinisch, Italien, NEDIS)
Zobacz też:
- locale_get_display_language() - Returns an appropriately localized display name for language of the inputlocale
- locale_get_display_script() - Returns an appropriately localized display name for script of the input locale
- locale_get_display_region() - Returns an appropriately localized display name for region of the input locale
- locale_get_display_variant() - Returns an appropriately localized display name for variants of the input locale
Locale::getDisplayRegion
locale_get_display_region
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Locale::getDisplayRegion -- locale_get_display_region — Returns an appropriately localized display name for region of the input locale
Opis
Styl obiektowy
$locale
[, string $in_locale
] )Styl proceduralny
$locale
[, string $in_locale
] )
Returns an appropriately localized display name for region of the input
locale. If is NULL then the default locale is used.
Parametry
-
locale -
The locale to return a display region for.
-
in_locale -
Optional format locale to use to display the region name
Zwracane wartości
display name of the region for the $locale in the format appropriate for $in_locale.
Przykłady
Przykład #1 locale_get_display_region() example
<?php
echo locale_get_display_region('sl-Latn-IT-nedis', 'en');
echo ";\n";
echo locale_get_display_region('sl-Latn-IT-nedis', 'fr');
echo ";\n";
echo locale_get_display_region('sl-Latn-IT-nedis', 'de');
?>
Przykład #2 OO example
<?php
echo Locale::getDisplayRegion('sl-Latn-IT-nedis', 'en');
echo ";\n";
echo Locale::getDisplayRegion('sl-Latn-IT-nedis', 'fr');
echo ";\n";
echo Locale::getDisplayRegion('sl-Latn-IT-nedis', 'de');
?>
Powyższy przykład wyświetli:
Italy; Italie; Italien
Zobacz też:
- locale_get_display_name() - Returns an appropriately localized display name for the input locale
- locale_get_display_language() - Returns an appropriately localized display name for language of the inputlocale
- locale_get_display_script() - Returns an appropriately localized display name for script of the input locale
- locale_get_display_variant() - Returns an appropriately localized display name for variants of the input locale
Locale::getDisplayScript
locale_get_display_script
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Locale::getDisplayScript -- locale_get_display_script — Returns an appropriately localized display name for script of the input locale
Opis
Styl obiektowy
$locale
[, string $in_locale
] )Styl proceduralny
$locale
[, string $in_locale
] )
Returns an appropriately localized display name for script of the input
locale. If is NULL then the default locale is used.
Parametry
-
locale -
The locale to return a display script for
-
in_locale -
Optional format locale to use to display the script name
Zwracane wartości
Display name of the script for the $locale in the format appropriate for $in_locale.
Przykłady
Przykład #1 locale_get_display_script() example
<?php
echo locale_get_display_script('sl-Latn-IT-nedis', 'en');
echo ";\n";
echo locale_get_display_script('sl-Latn-IT-nedis', 'fr');
echo ";\n";
echo locale_get_display_script('sl-Latn-IT-nedis', 'de');
?>
Przykład #2 OO example
<?php
echo Locale::getDisplayScript('sl-Latn-IT-nedis', 'en');
echo ";\n";
echo Locale::getDisplayScript('sl-Latn-IT-nedis', 'fr');
echo ";\n";
echo Locale::getDisplayScript('sl-Latn-IT-nedis', 'de');
?>
Powyższy przykład wyświetli:
Latin; latin; Lateinisch
Zobacz też:
- locale_get_display_name() - Returns an appropriately localized display name for the input locale
- locale_get_display_language() - Returns an appropriately localized display name for language of the inputlocale
- locale_get_display_region() - Returns an appropriately localized display name for region of the input locale
- locale_get_display_variant() - Returns an appropriately localized display name for variants of the input locale
Locale::getDisplayVariant
locale_get_display_variant
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Locale::getDisplayVariant -- locale_get_display_variant — Returns an appropriately localized display name for variants of the input locale
Opis
Styl obiektowy
$locale
[, string $in_locale
] )Styl proceduralny
$locale
[, string $in_locale
] )
Returns an appropriately localized display name for variants of the input
locale. If is NULL then the default locale is used.
Parametry
-
locale -
The locale to return a display variant for
-
in_locale -
Optional format locale to use to display the variant name
Zwracane wartości
Display name of the variant for the $locale in the format appropriate for $in_locale.
Przykłady
Przykład #1 locale_get_display_variant() example
<?php
echo locale_get_display_variant('sl-Latn-IT-nedis', 'en');
echo ";\n";
echo locale_get_display_variant('sl-Latn-IT-nedis', 'fr');
echo ";\n";
echo locale_get_display_variant('sl-Latn-IT-nedis', 'de');
?>
Przykład #2 OO example
<?php
echo Locale::getDisplayVariant('sl-Latn-IT-nedis', 'en');
echo ";\n";
echo Locale::getDisplayVariant('sl-Latn-IT-nedis', 'fr');
echo ";\n";
echo Locale::getDisplayVariant('sl-Latn-IT-nedis', 'de');
?>
Powyższy przykład wyświetli:
Natisone dialect; dialecte de Natisone; NEDIS
Zobacz też:
- locale_get_display_name() - Returns an appropriately localized display name for the input locale
- locale_get_display_language() - Returns an appropriately localized display name for language of the inputlocale
- locale_get_display_script() - Returns an appropriately localized display name for script of the input locale
- locale_get_display_region() - Returns an appropriately localized display name for region of the input locale
Locale::getKeywords
locale_get_keywords
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Locale::getKeywords -- locale_get_keywords — Gets the keywords for the input locale
Opis
Styl obiektowy
$locale
)Styl proceduralny
$locale
)Gets the keywords for the input locale.
Parametry
-
locale -
The locale to extract the keywords from
Zwracane wartości
Associative array containing the keyword-value pairs for this locale
Przykłady
Przykład #1 locale_get_keywords() example
<?php
$keywords_arr = locale_get_keywords( 'de_DE@currency=EUR;collation=PHONEBOOK' );
if ($keywords_arr) {
foreach ($keywords_arr as $key => $value) {
echo "$key = $value\n";
}
}
?>
Przykład #2 OO example
<?php
$keywords_arr = Locale::getKeywords( 'de_DE@currency=EUR;collation=PHONEBOOK' );
if ($keywords_arr) {
foreach( $keywords_arr as $key => $value){
echo "$key = $value\n";
}
}
?>
Powyższy przykład wyświetli:
collation = PHONEBOOK currency = EUR
Locale::getPrimaryLanguage
locale_get_primary_language
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Locale::getPrimaryLanguage -- locale_get_primary_language — Gets the primary language for the input locale
Opis
Styl obiektowy
$locale
)Styl proceduralny
$locale
)Gets the primary language for the input locale
Parametry
-
locale -
The locale to extract the primary language code from
Zwracane wartości
The language code associated with the language or NULL in case of error.
Przykłady
Przykład #1 locale_get_primary_language() example
<?php
echo locale_get_primary_language('zh-Hant');
?>
Przykład #2 OO example
<?php
echo Locale::getPrimaryLanguage('zh-Hant');
?>
Powyższy przykład wyświetli:
zh
Zobacz też:
- locale_get_script() - Gets the script for the input locale
- locale_get_region() - Gets the region for the input locale
- locale_get_all_variants() - Gets the variants for the input locale
Locale::getRegion
locale_get_region
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Locale::getRegion -- locale_get_region — Gets the region for the input locale
Opis
Styl obiektowy
$locale
)Styl proceduralny
$locale
)Gets the region for the input locale.
Parametry
-
locale -
The locale to extract the region code from
Zwracane wartości
The region subtag for the locale or NULL if not present
Przykłady
Przykład #1 locale_get_region() example
<?php
echo locale_get_region('de-CH-1901');
?>
Przykład #2 OO example
<?php
echo Locale::getRegion('de-CH-1901');
?>
Powyższy przykład wyświetli:
CH
Zobacz też:
- locale_get_primary_language() - Gets the primary language for the input locale
- locale_get_script() - Gets the script for the input locale
- locale_get_all_variants() - Gets the variants for the input locale
Locale::getScript
locale_get_script
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Locale::getScript -- locale_get_script — Gets the script for the input locale
Opis
Styl obiektowy
$locale
)Styl proceduralny
$locale
)Gets the script for the input locale.
Parametry
-
locale -
The locale to extract the script code from
Zwracane wartości
The script subtag for the locale or NULL if not present
Przykłady
Przykład #1 locale_get_script() example
<?php
echo locale_get_script('sr-Cyrl');
?>
Przykład #2 OO example
<?php
echo Locale::getScript('sr-Cyrl');
?>
Powyższy przykład wyświetli:
Cyrl
Zobacz też:
- locale_get_primary_language() - Gets the primary language for the input locale
- locale_get_region() - Gets the region for the input locale
- locale_get_all_variants() - Gets the variants for the input locale
Locale::lookup
locale_lookup
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Locale::lookup -- locale_lookup — Searches the language tag list for the best match to the language
Opis
Styl obiektowy
$langtag
, string $locale
[, bool $canonicalize = false
[, string $default
]] )Styl proceduralny
$langtag
, string $locale
[, bool $canonicalize = false
[, string $default
]] )
Searches the items in langtag for the best match to
the language range specified in locale according to
RFC 4647's lookup algorithm.
Parametry
-
langtag -
An array containing a list of language tags to compare to
locale. Maximum 100 items allowed. -
locale -
The locale to use as the language range when matching.
-
canonicalize -
If true, the arguments will be converted to canonical form before matching.
-
default -
The locale to use if no match is found.
Zwracane wartości
The closest matching language tag or default value.
Przykłady
Przykład #1 locale_lookup() example
<?php
$arr = array(
'de-DEVA',
'de-DE-1996',
'de',
'de-De'
);
echo locale_lookup($arr, 'de-DE-1996-x-prv1-prv2', 'en_US');
?>
Przykład #2 OO example
<?php
$arr = array(
'de-DEVA',
'de-DE-1996',
'de',
'de-De'
);
echo Locale::lookup($arr, 'de-DE-1996-x-prv1-prv2', 'en_US');
?>
Powyższy przykład wyświetli:
de_de_1996
Locale::parseLocale
locale_parse
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Locale::parseLocale -- locale_parse — Returns a key-value array of locale ID subtag elements.
Opis
Styl obiektowy
$locale
)Styl proceduralny
$locale
)Returns a key-value array of locale ID subtag elements.
Parametry
-
locale -
The locale to extract the subtag array from. Note: The 'variant' and 'private' subtags can take maximum 15 values whereas 'extlang' can take maximum 3 values.
Zwracane wartości
Returns an array containing a list of key-value pairs, where the keys identify the particular locale ID subtags, and the values are the associated subtag values. The array will be ordered as the locale id subtags e.g. in the locale id if variants are '-varX-varY-varZ' then the returned array will have variant0=>varX , variant1=>varY , variant2=>varZ
Przykłady
Przykład #1 locale_parse() example
<?php
$arr = locale_parse('sl-Latn-IT-nedis');
if ($arr) {
foreach ($arr as $key => $value) {
echo "$key : $value , ";
}
}
?>
Przykład #2 OO example
<?php
$arr = Locale::parseLocale('sl-Latn-IT-nedis');
if ($arr) {
foreach ($arr as $key => $value) {
echo "$key : $value , ";
}
}
?>
Powyższy przykład wyświetli:
language : sl , script : Latn , region : IT , variant0 : NEDIS ,
Locale::setDefault
locale_set_default
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Locale::setDefault -- locale_set_default — sets the default runtime locale
Opis
Styl obiektowy
$locale
)Styl proceduralny
$locale
)Sets the default runtime locale to $locale. This changes the value of INTL global 'default_locale' locale identifier. UAX #35 extensions are accepted.
Parametry
-
locale -
Is a BCP 47 compliant language tag containing the
Zwracane wartości
Zwraca TRUE w przypadku powodzenia, FALSE w
przypadku błędu.
Przykłady
Przykład #1 locale_set_default() example
<?php
locale_set_default('de-DE');
echo locale_get_default();
?>
Przykład #2 OO example
<?php
Locale::setDefault('de-DE');
echo Locale::getDefault();
?>
Powyższy przykład wyświetli:
de-DE
Zobacz też:
- locale_get_default() - Gets the default locale value from the INTL global 'default_locale'
Spis treści
- Locale::acceptFromHttp — Tries to find out best available locale based on HTTP "Accept-Language" header
- Locale::composeLocale — Returns a correctly ordered and delimited locale ID
- Locale::filterMatches — Checks if a language tag filter matches with locale
- Locale::getAllVariants — Gets the variants for the input locale
- Locale::getDefault — Gets the default locale value from the INTL global 'default_locale'
- Locale::getDisplayLanguage — Returns an appropriately localized display name for language of the inputlocale
- Locale::getDisplayName — Returns an appropriately localized display name for the input locale
- Locale::getDisplayRegion — Returns an appropriately localized display name for region of the input locale
- Locale::getDisplayScript — Returns an appropriately localized display name for script of the input locale
- Locale::getDisplayVariant — Returns an appropriately localized display name for variants of the input locale
- Locale::getKeywords — Gets the keywords for the input locale
- Locale::getPrimaryLanguage — Gets the primary language for the input locale
- Locale::getRegion — Gets the region for the input locale
- Locale::getScript — Gets the script for the input locale
- Locale::lookup — Searches the language tag list for the best match to the language
- Locale::parseLocale — Returns a key-value array of locale ID subtag elements.
- Locale::setDefault — sets the default runtime locale
The Normalizer class
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Wstęp
Normalization is a process that involves transforming characters and sequences of characters into a formally-defined underlying representation. This process is most important when text needs to be compared for sorting and searching, but it is also used when storing text to ensure that the text is stored in a consistent representation.
The Unicode Consortium has defined a number of normalization forms reflecting the various needs of applications:
- Normalization Form D (NFD) - Canonical Decomposition
- Normalization Form C (NFC) - Canonical Decomposition followed by Canonical Composition
- Normalization Form KD (NFKD) - Compatibility Decomposition
- Normalization Form KC (NFKC) - Compatibility Decomposition followed by Canonical Composition
Krótki opis klasy
Stałe predefiniowane
The following constants define the normalization form used by the normalizer:
-
Normalizer::FORM_C(string) - Normalization Form C (NFC) - Canonical Decomposition followed by Canonical Composition
-
Normalizer::FORM_D(string) - Normalization Form D (NFD) - Canonical Decomposition
-
Normalizer::FORM_KC(string) - Normalization Form KC (NFKC) - Compatibility Decomposition, followed by Canonical Composition
-
Normalizer::FORM_KD(string) - Normalization Form KD (NFKD) - Compatibility Decomposition
-
Normalizer::NONE(string) - No decomposition/composition
-
Normalizer::OPTION_DEFAULT(string) - Default normalization options
Normalizer::isNormalized
normalizer_is_normalized
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Normalizer::isNormalized -- normalizer_is_normalized — Checks if the provided string is already in the specified normalization form.
Opis
Styl obiektowy
$input
[, string $form = Normalizer::FORM_C
] )Styl proceduralny
$input
[, string $form = Normalizer::FORM_C
] )Checks if the provided string is already in the specified normalization form.
Parametry
-
input -
The input string to normalize
-
form -
One of the normalization forms.
Zwracane wartości
TRUE if normalized, FALSE otherwise or if there an error
Przykłady
Przykład #1 normalizer_is_normalized() example
<?php
$char_A_ring = "\xC3\x85"; // 'LATIN CAPITAL LETTER A WITH RING ABOVE' (U+00C5)
$char_combining_ring_above = "\xCC\x8A"; // 'COMBINING RING ABOVE' (U+030A)
$char_orig = 'A' . $char_combining_ring_above;
$char_norm = normalizer_normalize( 'A' . $char_combining_ring_above, Normalizer::FORM_C );
echo ( normalizer_is_normalized($char_orig, Normalizer::FORM_C) ) ? "normalized" : "not normalized";
echo '; ';
echo ( normalizer_is_normalized($char_norm, Normalizer::FORM_C) ) ? "normalized" : "not normalized";
?>
Przykład #2 OO example
<?php
$char_A_ring = "\xC3\x85"; // 'LATIN CAPITAL LETTER A WITH RING ABOVE' (U+00C5)
$char_combining_ring_above = "\xCC\x8A"; // 'COMBINING RING ABOVE' (U+030A)
$char_orig = 'A' . $char_combining_ring_above;
$char_norm = Normalizer::normalize( 'A' . $char_combining_ring_above, Normalizer::FORM_C );
echo ( Normalizer::isNormalized($char_orig, Normalizer::FORM_C) ) ? "normalized" : "not normalized";
echo '; ';
echo ( Normalizer::isNormalized($char_norm, Normalizer::FORM_C) ) ? "normalized" : "not normalized";
?>
Powyższy przykład wyświetli:
not normalized; normalized
Zobacz też:
- normalizer_normalize() - Normalizes the input provided and returns the normalized string
Normalizer::normalize
normalizer_normalize
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Normalizer::normalize -- normalizer_normalize — Normalizes the input provided and returns the normalized string
Opis
Styl obiektowy
$input
[, string $form = Normalizer::FORM_C
] )Styl proceduralny
$input
[, string $form = Normalizer::FORM_C
] )Normalizes the input provided and returns the normalized string
Parametry
-
input -
The input string to normalize
-
form -
One of the normalization forms.
Zwracane wartości
The normalized string or NULL if an error occurred.
Przykłady
Przykład #1 normalizer_normalize() example
<?php
$char_A_ring = "\xC3\x85"; // 'LATIN CAPITAL LETTER A WITH RING ABOVE' (U+00C5)
$char_combining_ring_above = "\xCC\x8A"; // 'COMBINING RING ABOVE' (U+030A)
$char_1 = normalizer_normalize( $char_A_ring, Normalizer::FORM_C );
$char_2 = normalizer_normalize( 'A' . $char_combining_ring_above, Normalizer::FORM_C );
echo urlencode($char_1);
echo ' ';
echo urlencode($char_2);
?>
Przykład #2 OO example
<?php
$char_A_ring = "\xC3\x85"; // 'LATIN CAPITAL LETTER A WITH RING ABOVE' (U+00C5)
$char_combining_ring_above = "\xCC\x8A"; // 'COMBINING RING ABOVE' (U+030A)
$char_1 = Normalizer::normalize( $char_A_ring, Normalizer::FORM_C );
$char_2 = Normalizer::normalize( 'A' . $char_combining_ring_above, Normalizer::FORM_C );
echo urlencode($char_1);
echo ' ';
echo urlencode($char_2);
?>
Powyższy przykład wyświetli:
%C3%85 %C3%85
Zobacz też:
- normalizer_is_normalized() - Checks if the provided string is already in the specified normalization form.
Spis treści
- Normalizer::isNormalized — Checks if the provided string is already in the specified normalization form.
- Normalizer::normalize — Normalizes the input provided and returns the normalized string
The MessageFormatter class
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Wstęp
MessageFormatter is a concrete class that enables users to produce concatenated, language-neutral messages. The methods supplied in this class are used to build all the messages that are seen by end users.
The MessageFormatter class assembles messages from various fragments (such as text fragments, numbers, and dates) supplied by the program. Because of the MessageFormatter class, the program does not need to know the order of the fragments. The class uses the formatting specifications for the fragments to assemble them into a message that is contained in a single string within a resource bundle. For example, MessageFormatter enables you to print the phrase "Finished printing x out of y files..." in a manner that still allows for flexibility in translation.
Previously, an end user message was created as a sentence and handled as a string. This procedure created problems for localizers because the sentence structure, word order, number format and so on are very different from language to language. The language-neutral way to create messages keeps each part of the message separate and provides keys to the data. Using these keys, the MessageFormatter class can concatenate the parts of the message, localize them, and display a well-formed string to the end user.
MessageFormatter takes a set of objects, formats them, and then inserts the formatted strings into the pattern at the appropriate places. Choice formats can be used in conjunction with MessageFormatter to handle plurals, match numbers, and select from an array of items. Typically, the message format will come from resources and the arguments will be dynamically set at runtime.
Krótki opis klasy
MessageFormatter::create
MessageFormatter::__construct
msgfmt_create
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
MessageFormatter::create -- MessageFormatter::__construct -- msgfmt_create — Constructs a new Message Formatter
Opis
Styl obiektowy (method)
Styl obiektowy (constructor):
$locale
, string $pattern
)Styl proceduralny
Constructs a new Message Formatter
Parametry
-
locale -
The locale to use when formatting arguments
-
pattern -
The pattern string to stick arguments into. The pattern uses an 'apostrophe-friendly' syntax; it is run through » umsg_autoQuoteApostrophe before being interpreted.
Zwracane wartości
The formatter object
Przykłady
Przykład #1 msgfmt_create() example
<?php
$fmt = msgfmt_create("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
echo msgfmt_format($fmt, array(4560, 123, 4560/123));
$fmt = msgfmt_create("de", "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum");
echo msgfmt_format($fmt, array(4560, 123, 4560/123));
?>
Przykład #2 OO example
<?php
$fmt = new MessageFormatter("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
echo $fmt->format(array(4560, 123, 4560/123));
$fmt = new MessageFormatter("de", "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum");
echo $fmt->format(array(4560, 123, 4560/123));
?>
Powyższy przykład wyświetli:
4,560 monkeys on 123 trees make 37.073 monkeys per tree 4.560 Affen auf 123 Bäumen sind 37,073 Affen pro Baum
Zobacz też:
- msgfmt_format() - Format the message
- msgfmt_parse() - Parse input string according to pattern
- msgfmt_get_error_code() - Get the error code from last operation
- msgfmt_get_error_message() - Get the error text from the last operation
MessageFormatter::formatMessage
msgfmt_format_message
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
MessageFormatter::formatMessage -- msgfmt_format_message — Quick format message
Opis
Styl obiektowy
$locale
, string $pattern
, array $args
)Styl proceduralny
$locale
, string $pattern
, array $args
)Quick formatting function that formats the string without having to explicitly create the formatter object. Use this function when the format operation is done only once and does not need and parameters or state to be kept.
Parametry
-
locale -
The locale to use for formatting locale-dependent parts
-
pattern -
The pattern string to insert things into. The pattern uses an 'apostrophe-friendly' syntax; it is run through » umsg_autoQuoteApostrophe before being interpreted.
-
args
Zwracane wartości
The formatted pattern string or FALSE if an error occurred
Przykłady
Przykład #1 msgfmt_format_message() example
<?php
echo msgfmt_format_message("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree", array(4560, 123, 4560/123));
echo msgfmt_format_message("de", "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum", array(4560, 123, 4560/123));
?>
Przykład #2 OO example
<?php
echo msgfmt_format_message("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree", array(4560, 123, 4560/123));
echo msgfmt_format_message("de", "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum", array(4560, 123, 4560/123));
?>
Powyższy przykład wyświetli:
4,560 monkeys on 123 trees make 37.073 monkeys per tree 4.560 Affen auf 123 Bäumen sind 37,073 Affen pro Baum
Zobacz też:
- msgfmt_create() - Constructs a new Message Formatter
- msgfmt_parse() - Parse input string according to pattern
- msgfmt_get_error_code() - Get the error code from last operation
- msgfmt_get_error_message() - Get the error text from the last operation
MessageFormatter::format
msgfmt_format
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
MessageFormatter::format -- msgfmt_format — Format the message
Opis
Styl obiektowy
$args
)Styl proceduralny
Format the message by substituting the data into the format string according to the locale rules
Parametry
-
fmt -
The message formatter
-
args -
Arguments to insert into the format string
Zwracane wartości
The formatted string, or FALSE if an error occurred
Przykłady
Przykład #1 msgfmt_format() example
<?php
$fmt = msgfmt_create("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
echo msgfmt_format($fmt, array(4560, 123, 4560/123));
$fmt = msgfmt_create("de", "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum");
echo msgfmt_format($fmt, array(4560, 123, 4560/123));
?>
Przykład #2 OO example
<?php
$fmt = new MessageFormatter("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
echo $fmt->format(array(4560, 123, 4560/123));
$fmt = new MessageFormatter("de", "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum");
echo $fmt->format(array(4560, 123, 4560/123));
?>
Powyższy przykład wyświetli:
4,560 monkeys on 123 trees make 37.073 monkeys per tree 4.560 Affen auf 123 Bäumen sind 37,073 Affen pro Baum
Zobacz też:
- msgfmt_create() - Constructs a new Message Formatter
- msgfmt_parse() - Parse input string according to pattern
- msgfmt_format_message() - Quick format message
- msgfmt_get_error_code() - Get the error code from last operation
- msgfmt_get_error_message() - Get the error text from the last operation
MessageFormatter::getErrorCode
msgfmt_get_error_code
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
MessageFormatter::getErrorCode -- msgfmt_get_error_code — Get the error code from last operation
Opis
Styl obiektowy
Styl proceduralny
Get the error code from last operation.
Parametry
-
fmt -
The message formatter
Zwracane wartości
The error code, one of UErrorCode values. Initial value is U_ZERO_ERROR.
Przykłady
Przykład #1 msgfmt_get_error_code() example
<?php
$fmt = msgfmt_create("en_US", "{0, number} monkeys on {1, number} trees");
$str = msgfmt_format($fmt, array());
if(!$str) {
echo "ERROR: ".msgfmt_get_error_message($fmt) . " (" . msgfmt_get_error_code($fmt) . ")\n";
}
?>
Przykład #2 OO example
<?php
$fmt = new MessageFormatter("en_US", "{0, number} monkeys on {1, number} trees");
$str = $fmt->format(array());
if(!$str) {
echo "ERROR: ".$fmt->getErrorMessage() . " (" . $fmt->getErrorCode() . ")\n";
}
?>
Powyższy przykład wyświetli:
ERROR: msgfmt_format: not enough parameters: U_ILLEGAL_ARGUMENT_ERROR (1)
Zobacz też:
- msgfmt_get_error_message() - Get the error text from the last operation
- intl_get_error_code() - Get the last error code
- intl_is_failure() - Check whether the given error code indicates failure
MessageFormatter::getErrorMessage
msgfmt_get_error_message
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
MessageFormatter::getErrorMessage -- msgfmt_get_error_message — Get the error text from the last operation
Opis
Styl obiektowy
Styl proceduralny
Get the error text from the last operation.
Parametry
-
fmt -
The message formatter
Zwracane wartości
Description of the last error.
Przykłady
Przykład #1 msgfmt_get_error_message() example
<?php
$fmt = msgfmt_create("en_US", "{0, number} monkeys on {1, number} trees");
$str = msgfmt_format($fmt, array());
if(!$str) {
echo "ERROR: ".msgfmt_get_error_message($fmt) . " (" . msgfmt_get_error_code($fmt) . ")\n";
}
?>
Przykład #2 OO example
<?php
$fmt = new MessageFormatter("en_US", "{0, number} monkeys on {1, number} trees");
$str = $fmt->format(array());
if(!$str) {
echo "ERROR: ".$fmt->getErrorMessage() . " (" . $fmt->getErrorCode() . ")\n";
}
?>
Powyższy przykład wyświetli:
ERROR: msgfmt_format: not enough parameters: U_ILLEGAL_ARGUMENT_ERROR (1)
Zobacz też:
- msgfmt_get_error_code() - Get the error code from last operation
- intl_get_error_code() - Get the last error code
- intl_is_failure() - Check whether the given error code indicates failure
MessageFormatter::getLocale
msgfmt_get_locale
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
MessageFormatter::getLocale -- msgfmt_get_locale — Get the locale for which the formatter was created.
Opis
Styl obiektowy
Styl proceduralny
Get the locale for which the formatter was created.
Parametry
-
formatter -
The formatter resource
Zwracane wartości
The locale name
Przykłady
Przykład #1 msgfmt_get_locale() example
<?php
$fmt = msgfmt_create('en_US', "Number {0,number}");
echo msgfmt_get_locale($fmt);
?>
Przykład #2 OO example
<?php
$fmt = new MessageFormatter('en_US', "Number {0,number}");
echo $fmt->getLocale();
?>
Powyższy przykład wyświetli:
en_US
MessageFormatter::getPattern
msgfmt_get_pattern
(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
MessageFormatter::getPattern -- msgfmt_get_pattern — Get the pattern used by the formatter
Opis
Styl obiektowy
Styl proceduralny
Get the pattern used by the formatter
Parametry
-
fmt -
The message formatter
Zwracane wartości
The pattern string for this message formatter
Przykłady
Przykład #1 msgfmt_get_pattern() example
<?php
$fmt = msgfmt_create( "en_US", "{0, number} monkeys on {1, number} trees" );
echo "Default pattern: '" . msgfmt_get_pattern( $fmt ) . "'\n";
echo "Formatting result: " . msgfmt_format( $fmt, array(123, 456) ) . "\n";
msgfmt_set_pattern( $fmt, "{0, number} trees hosting {1, number} monkeys" );
echo "New pattern: '" . msgfmt_get_pattern( $fmt ) . "'\n";
echo "Formatted number: " . msgfmt_format( $fmt, array(123, 456) ) . "\n";
?>
Przykład #2 OO example
<?php
$fmt = new MessageFormatter( "en_US", "{0, number} monkeys on {1, number} trees" );
echo "Default pattern: '" . $fmt->getPattern() . "'\n";
echo "Formatting result: " . $fmt->format(array(123, 456)) . "\n";
$fmt->setPattern("{0, number} trees hosting {1, number} monkeys" );
echo "New pattern: '" . $fmt->getPattern() . "'\n";
echo "Formatted number: " . $fmt->format(array(123, 456)) . "\n";
?>
Powyższy przykład wyświetli: